From b680301c38b43627bffa59432c10b0b352a7fc5d Mon Sep 17 00:00:00 2001 From: "Rodrigo Rodriguez (Pragmatismo)" Date: Sun, 23 Nov 2025 13:46:55 -0300 Subject: [PATCH] - More general docs. --- docs/src/README.md | 20 +- docs/src/SUMMARY.md | 57 +- docs/src/appendix-i/relationships.md | 2 +- docs/src/appendix-i/tables.md | 2 +- docs/src/appendix-ii/README.md | 22 - docs/src/appendix-ii/build-status.md | 221 ------- docs/src/appendix-ii/integration-status.md | 452 --------------- docs/src/appendix-ii/production-status.md | 308 ---------- docs/src/chapter-01/README.md | 42 +- docs/src/chapter-01/first-conversation.md | 44 +- docs/src/chapter-01/installation.md | 370 +++++++----- docs/src/chapter-01/nvidia-gpu-setup.md | 287 ++++++++++ docs/src/chapter-01/overview.md | 91 +-- docs/src/chapter-01/quick-start.md | 96 +++- docs/src/chapter-01/sessions.md | 312 +--------- docs/src/chapter-02/README.md | 94 +-- docs/src/chapter-02/gbai.md | 18 +- docs/src/chapter-02/gbdialog.md | 275 +++++++-- docs/src/chapter-02/gbdrive.md | 7 +- docs/src/chapter-02/gbkb.md | 14 +- docs/src/chapter-02/gbot.md | 9 +- docs/src/chapter-02/gbtheme.md | 229 +++++--- docs/src/chapter-02/summary.md | 6 +- docs/src/chapter-02/templates.md | 542 +++++++----------- docs/src/chapter-03/README.md | 16 +- docs/src/chapter-03/caching.md | 107 +++- docs/src/chapter-03/context-compaction.md | 108 +++- docs/src/chapter-03/indexing.md | 145 ++++- docs/src/chapter-03/kb-and-tools.md | 138 ++--- docs/src/chapter-03/semantic-cache.md | 4 +- docs/src/chapter-03/semantic-search.md | 122 +++- docs/src/chapter-03/vector-collections.md | 133 ++++- docs/src/chapter-04/README.md | 274 +++++---- docs/src/chapter-04/console-mode.md | 392 +++++++++++++ docs/src/chapter-04/desktop-mode.md | 366 ++++++++++++ docs/src/chapter-04/web-interface.md | 172 +++++- docs/src/chapter-05/basics.md | 4 +- docs/src/chapter-05/keyword-add-kb.md | 196 ------- docs/src/chapter-05/keyword-add-suggestion.md | 2 +- docs/src/chapter-05/keyword-add-tool.md | 242 -------- docs/src/chapter-05/keyword-change-theme.md | 84 +++ docs/src/chapter-05/keyword-find.md | 38 +- docs/src/chapter-05/keyword-get.md | 4 +- docs/src/chapter-05/keyword-remember.md | 2 +- docs/src/chapter-05/keyword-remove-tool.md | 37 -- docs/src/chapter-05/keyword-set-context.md | 2 +- docs/src/chapter-05/keyword-set-user.md | 2 +- docs/src/chapter-05/keyword-use-kb.md | 185 ------ docs/src/chapter-05/keyword-use-tool.md | 123 +++- docs/src/chapter-05/keyword-website-of.md | 32 -- docs/src/chapter-05/keywords.md | 115 ++-- docs/src/chapter-05/real-basic-examples.md | 156 ----- docs/src/chapter-05/template-auth.md | 21 - docs/src/chapter-05/template-summary.md | 2 +- docs/src/chapter-06/architecture.md | 18 +- docs/src/chapter-06/building.md | 56 +- docs/src/chapter-06/containers.md | 16 +- docs/src/chapter-06/crates.md | 6 +- docs/src/chapter-06/custom-keywords.md | 2 +- docs/src/chapter-06/dependencies.md | 4 +- docs/src/chapter-06/services.md | 12 +- docs/src/chapter-06/smb-deployment.md | 518 +---------------- docs/src/chapter-07/README.md | 6 +- docs/src/chapter-07/answer-modes.md | 432 -------------- docs/src/chapter-07/config-csv.md | 28 +- docs/src/chapter-07/context-config.md | 4 +- docs/src/chapter-07/llm-config.md | 490 ++++------------ docs/src/chapter-07/minio.md | 198 +++---- docs/src/chapter-07/parameters.md | 6 +- docs/src/chapter-08/compilation.md | 6 +- docs/src/chapter-08/get-integration.md | 14 +- docs/src/chapter-08/openai-format.md | 2 +- docs/src/chapter-09/README.md | 7 +- docs/src/chapter-09/ai-llm.md | 30 - docs/src/chapter-09/conversation.md | 2 +- docs/src/chapter-09/core-features.md | 14 +- docs/src/chapter-09/knowledge-base.md | 8 +- docs/src/chapter-09/storage.md | 46 +- docs/src/chapter-10/README.md | 2 +- docs/src/chapter-10/ide-extensions.md | 302 ++++++++++ docs/src/chapter-10/setup.md | 122 ++-- docs/src/chapter-10/standards.md | 314 +++++----- docs/src/chapter-11/bot-auth.md | 4 +- .../src/chapter-11/compliance-requirements.md | 52 +- docs/src/chapter-11/security-features.md | 37 +- docs/src/chapter-12/ai-api.md | 5 - docs/src/chapter-12/opensource-components.md | 6 +- docs/src/chapter-12/whiteboard-api.md | 4 +- docs/src/glossary.md | 5 +- docs/src/introduction.md | 21 +- prompts/dev/platform/README.md | 6 +- 91 files changed, 4203 insertions(+), 5346 deletions(-) delete mode 100644 docs/src/appendix-ii/README.md delete mode 100644 docs/src/appendix-ii/build-status.md delete mode 100644 docs/src/appendix-ii/integration-status.md delete mode 100644 docs/src/appendix-ii/production-status.md create mode 100644 docs/src/chapter-01/nvidia-gpu-setup.md create mode 100644 docs/src/chapter-04/console-mode.md create mode 100644 docs/src/chapter-04/desktop-mode.md delete mode 100644 docs/src/chapter-05/keyword-add-kb.md delete mode 100644 docs/src/chapter-05/keyword-add-tool.md create mode 100644 docs/src/chapter-05/keyword-change-theme.md delete mode 100644 docs/src/chapter-05/keyword-remove-tool.md delete mode 100644 docs/src/chapter-05/keyword-website-of.md delete mode 100644 docs/src/chapter-05/real-basic-examples.md delete mode 100644 docs/src/chapter-05/template-auth.md create mode 100644 docs/src/chapter-10/ide-extensions.md diff --git a/docs/src/README.md b/docs/src/README.md index efd3519dc..ad632c8f8 100644 --- a/docs/src/README.md +++ b/docs/src/README.md @@ -25,7 +25,7 @@ This documentation has been **recently updated** to accurately reflect the actua - Riot compiler module (`src/riot_compiler/`) - Prompt manager (`src/prompt_manager/`) - API endpoints and web server routes -- MinIO/S3 drive integration details +- Drive (S3-compatible) integration details - Video conferencing (LiveKit) integration --- @@ -37,8 +37,8 @@ BotServer is an open-source conversational AI platform written in Rust. It enabl - **BASIC Scripting**: Simple `.bas` scripts for conversation flows - **Template Packages**: Organize bots as `.gbai` directories with dialogs, knowledge bases, and configuration - **Vector Search**: Semantic document retrieval with Qdrant -- **LLM Integration**: OpenAI, local models, and custom providers -- **Auto-Bootstrap**: Automated installation of PostgreSQL, Redis, MinIO, and more +- **LLM Integration**: Local models, cloud APIs, and custom providers +- **Auto-Bootstrap**: Automated installation of PostgreSQL, cache, drive, and more - **Multi-Bot Hosting**: Run multiple isolated bots on a single server --- @@ -66,7 +66,7 @@ BotServer is an open-source conversational AI platform written in Rust. It enabl - [.gbkb Knowledge Base](chapter-02/gbkb.md) - Document collections - [.gbot Configuration](chapter-02/gbot.md) - Bot parameters - [.gbtheme UI Theming](chapter-02/gbtheme.md) - Web interface customization - - [.gbdrive File Storage](chapter-02/gbdrive.md) - MinIO/S3 integration + - [.gbdrive File Storage](chapter-02/gbdrive.md) - Drive (S3-compatible) integration ### Part III - Knowledge Base - [Chapter 03: gbkb Reference](chapter-03/README.md) - Semantic search and vector database @@ -76,7 +76,7 @@ BotServer is an open-source conversational AI platform written in Rust. It enabl ### Part V - BASIC Dialogs - [Chapter 05: gbdialog Reference](chapter-05/README.md) - Complete BASIC scripting reference - - Keywords: `TALK`, `HEAR`, `LLM`, `SET_CONTEXT`, `USE_KB`, and more + - Keywords: `TALK`, `HEAR`, `LLM`, `SET CONTEXT`, `USE KB`, and more ### Part VI - Extending BotServer - [Chapter 06: Rust Architecture Reference](chapter-06/README.md) - Internal architecture @@ -123,9 +123,9 @@ BotServer is a **monolithic Rust application** (single crate) with the following ### Infrastructure - `bootstrap` - Auto-installation of components -- `package_manager` - Manages PostgreSQL, Redis, MinIO, etc. -- `web_server` - Axum HTTP API and WebSocket -- `drive` - MinIO/S3 storage and vector DB +- `package_manager` - Manages PostgreSQL, cache, drive, etc. +- `web_server` - Axum HTTP REST API +- `drive` - S3-compatible storage and vector DB - `config` - Environment configuration ### Features @@ -143,8 +143,8 @@ BotServer is a **monolithic Rust application** (single crate) with the following - **Language**: Rust 2021 edition - **Web**: Axum + Tower + Tokio - **Database**: Diesel ORM + PostgreSQL -- **Cache**: Redis/Valkey -- **Storage**: AWS SDK S3 (MinIO) +- **Cache**: Valkey (Redis-compatible) +- **Storage**: AWS SDK S3 (drive component) - **Vector DB**: Qdrant (optional) - **Scripting**: Rhai engine - **Security**: Argon2, AES-GCM diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 132336f1e..7f421c1e4 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -10,6 +10,7 @@ - [Installation](./chapter-01/installation.md) - [First Conversation](./chapter-01/first-conversation.md) - [Understanding Sessions](./chapter-01/sessions.md) + - [NVIDIA GPU Setup for LXC](./chapter-01/nvidia-gpu-setup.md) # Part II - Package System @@ -41,6 +42,8 @@ - [Web Interface](./chapter-04/web-interface.md) - [CSS Customization](./chapter-04/css.md) - [HTML Templates](./chapter-04/html.md) + - [Desktop Mode](./chapter-04/desktop-mode.md) + - [Console Mode](./chapter-04/console-mode.md) # Part V - BASIC Dialogs @@ -49,30 +52,28 @@ - [Universal Messaging & Multi-Channel](./chapter-05/universal-messaging.md) - [Template Examples](./chapter-05/templates.md) - [start.bas](./chapter-05/template-start.md) - - [auth.bas](./chapter-05/template-auth.md) - [generate-summary.bas](./chapter-05/template-summary.md) - [enrollment Tool Example](./chapter-05/template-enrollment.md) - [Keyword Reference](./chapter-05/keywords.md) - [TALK](./chapter-05/keyword-talk.md) - [HEAR](./chapter-05/keyword-hear.md) - - [SET_USER](./chapter-05/keyword-set-user.md) - - [SET_CONTEXT](./chapter-05/keyword-set-context.md) + - [SET USER](./chapter-05/keyword-set-user.md) + - [SET CONTEXT](./chapter-05/keyword-set-context.md) - [LLM](./chapter-05/keyword-llm.md) - - [GET_BOT_MEMORY](./chapter-05/keyword-get-bot-memory.md) - - [SET_BOT_MEMORY](./chapter-05/keyword-set-bot-memory.md) - - [USE_KB](./chapter-05/keyword-use-kb.md) - - [CLEAR_KB](./chapter-05/keyword-clear-kb.md) - - [ADD_WEBSITE](./chapter-05/keyword-add-website.md) - - [USE_TOOL](./chapter-05/keyword-use-tool.md) - - [CLEAR_TOOLS](./chapter-05/keyword-clear-tools.md) + - [GET BOT MEMORY](./chapter-05/keyword-get-bot-memory.md) + - [SET BOT MEMORY](./chapter-05/keyword-set-bot-memory.md) + - [USE KB](./chapter-05/keyword-use-kb.md) + - [CLEAR KB](./chapter-05/keyword-clear-kb.md) + - [ADD WEBSITE](./chapter-05/keyword-add-website.md) + - [USE TOOL](./chapter-05/keyword-use-tool.md) + - [CLEAR TOOLS](./chapter-05/keyword-clear-tools.md) - [GET](./chapter-05/keyword-get.md) - - [FIND](./chapter-05/keyword-find.md) - [SET](./chapter-05/keyword-set.md) - [ON](./chapter-05/keyword-on.md) - - [SET_SCHEDULE](./chapter-05/keyword-set-schedule.md) - - [CREATE_SITE](./chapter-05/keyword-create-site.md) - - [CREATE_DRAFT](./chapter-05/keyword-create-draft.md) - - [CREATE_TASK](./chapter-05/keyword-create-task.md) + - [SET SCHEDULE](./chapter-05/keyword-set-schedule.md) + - [CREATE SITE](./chapter-05/keyword-create-site.md) + - [CREATE DRAFT](./chapter-05/keyword-create-draft.md) + - [CREATE TASK](./chapter-05/keyword-create-task.md) - [PRINT](./chapter-05/keyword-print.md) - [WAIT](./chapter-05/keyword-wait.md) - [FORMAT](./chapter-05/keyword-format.md) @@ -80,14 +81,16 @@ - [LAST](./chapter-05/keyword-last.md) - [FOR EACH](./chapter-05/keyword-for-each.md) - [EXIT FOR](./chapter-05/keyword-exit-for.md) - - [ADD_MEMBER](./chapter-05/keyword-add-member.md) - - [ADD_SUGGESTION](./chapter-05/keyword-add-suggestion.md) - - [CLEAR_SUGGESTIONS](./chapter-05/keyword-clear-suggestions.md) + - [ADD MEMBER](./chapter-05/keyword-add-member.md) + - [ADD SUGGESTION](./chapter-05/keyword-add-suggestion.md) + - [CLEAR SUGGESTIONS](./chapter-05/keyword-clear-suggestions.md) - [BOOK](./chapter-05/keyword-book.md) - [REMEMBER](./chapter-05/keyword-remember.md) - - [SAVE_FROM_UNSTRUCTURED](./chapter-05/keyword-save-from-unstructured.md) - - [SEND_MAIL](./chapter-05/keyword-send-mail.md) + - [SAVE FROM UNSTRUCTURED](./chapter-05/keyword-save-from-unstructured.md) + - [SEND MAIL](./chapter-05/keyword-send-mail.md) - [WEATHER](./chapter-05/keyword-weather.md) + - [FIND](./chapter-05/keyword-find.md) + - [CHANGE THEME](./chapter-05/keyword-change-theme.md) # Part VI - Extending BotServer @@ -95,7 +98,6 @@ - [Architecture Overview](./chapter-06/architecture.md) - [Building from Source](./chapter-06/building.md) - [Container Deployment (LXC)](./chapter-06/containers.md) - - [SMB Deployment Guide](./chapter-06/smb-deployment.md) - [Module Structure](./chapter-06/crates.md) - [Service Layer](./chapter-06/services.md) - [Creating Custom Keywords](./chapter-06/custom-keywords.md) @@ -107,10 +109,9 @@ - [Chapter 07: gbot Reference](./chapter-07/README.md) - [config.csv Format](./chapter-07/config-csv.md) - [Bot Parameters](./chapter-07/parameters.md) - - [Answer Modes](./chapter-07/answer-modes.md) - [LLM Configuration](./chapter-07/llm-config.md) - [Context Configuration](./chapter-07/context-config.md) - - [MinIO Drive Integration](./chapter-07/minio.md) + - [Drive Integration](./chapter-07/minio.md) # Part VIII - Tools and Integration @@ -119,7 +120,7 @@ - [PARAM Declaration](./chapter-08/param-declaration.md) - [Tool Compilation](./chapter-08/compilation.md) - [MCP Format](./chapter-08/mcp-format.md) - - [OpenAI Tool Format](./chapter-08/openai-format.md) + - [Tool Format](./chapter-08/openai-format.md) - [GET Keyword Integration](./chapter-08/get-integration.md) - [External APIs](./chapter-08/external-apis.md) @@ -147,6 +148,7 @@ - [Testing](./chapter-10/testing.md) - [Pull Requests](./chapter-10/pull-requests.md) - [Documentation](./chapter-10/documentation.md) + - [IDE Extensions](./chapter-10/ide-extensions.md) # Part XI - Authentication and Security @@ -194,9 +196,4 @@ - [Tables](./appendix-i/tables.md) - [Relationships](./appendix-i/relationships.md) -- [Appendix II: Project Status](./appendix-ii/README.md) - - [Build Status](./appendix-ii/build-status.md) - - [Production Status](./appendix-ii/production-status.md) - - [Integration Status](./appendix-ii/integration-status.md) - -[Glossary](./glossary.md) +[Glossary](./glossary.md) \ No newline at end of file diff --git a/docs/src/appendix-i/relationships.md b/docs/src/appendix-i/relationships.md index 4b0b36c87..81c966176 100644 --- a/docs/src/appendix-i/relationships.md +++ b/docs/src/appendix-i/relationships.md @@ -182,7 +182,7 @@ These relationships are frequently traversed and should be optimized: 2. **bots β†’ bot_memories** - Index: (bot_id, key) - - Used by GET_BOT_MEMORY/SET_BOT_MEMORY + - Used by GET BOT MEMORY/SET BOT MEMORY 3. **kb_collections β†’ kb_documents** - Index: (collection_id, indexed) diff --git a/docs/src/appendix-i/tables.md b/docs/src/appendix-i/tables.md index 829c5f581..4fcbc51a8 100644 --- a/docs/src/appendix-i/tables.md +++ b/docs/src/appendix-i/tables.md @@ -38,7 +38,7 @@ Stores bot-specific configuration parameters from config.csv. | updated_at | TIMESTAMPTZ | Last update timestamp | ### bot_memories -Persistent key-value storage for bots (used by GET_BOT_MEMORY/SET_BOT_MEMORY). +Persistent key-value storage for bots (used by GET BOT MEMORY/SET BOT MEMORY). | Column | Type | Description | |--------|------|-------------| diff --git a/docs/src/appendix-ii/README.md b/docs/src/appendix-ii/README.md deleted file mode 100644 index c9dba915b..000000000 --- a/docs/src/appendix-ii/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Appendix II: Project Status - -This appendix contains current project status information, build metrics, and integration tracking. - -## Contents - -- **[Build Status](./build-status.md)** - Current build status, completed tasks, and remaining issues -- **[Production Status](./production-status.md)** - Production readiness metrics and API endpoints -- **[Integration Status](./integration-status.md)** - Module integration tracking and feature matrix - -## Purpose - -These documents provide up-to-date information about the project's current state, helping developers and contributors understand: - -- What's working and what needs attention -- Which features are production-ready -- Integration status of various modules -- Known issues and their fixes - -## Note - -These status documents are living documents that are updated frequently as the project evolves. For the most current information, always check the latest version in the repository. \ No newline at end of file diff --git a/docs/src/appendix-ii/build-status.md b/docs/src/appendix-ii/build-status.md deleted file mode 100644 index ae6eb8ba7..000000000 --- a/docs/src/appendix-ii/build-status.md +++ /dev/null @@ -1,221 +0,0 @@ -# BotServer Build Status & Fixes - -## Current Status - -Build is failing with multiple issues that need to be addressed systematically. - -## Completed Tasks βœ… - -1. **Security Features Documentation** - - Created comprehensive `docs/SECURITY_FEATURES.md` - - Updated `Cargo.toml` with detailed security feature documentation - - Added security-focused linting configuration - -2. **Documentation Cleanup** - - Moved uppercase .md files to appropriate locations - - Deleted redundant implementation status files - - Created `docs/KB_AND_TOOLS.md` consolidating KB/Tool system documentation - - Created `docs/SMB_DEPLOYMENT_GUIDE.md` with pragmatic SMB examples - -3. **Zitadel Auth Facade** - - Created `src/auth/facade.rs` with comprehensive auth abstraction - - Implemented `ZitadelAuthFacade` for enterprise deployments - - Implemented `SimpleAuthFacade` for SMB deployments - - Added `ZitadelClient` to `src/auth/zitadel.rs` - -4. **Keyword Services API Layer** - - Created `src/api/keyword_services.rs` exposing keyword logic as REST APIs - - Services include: format, weather, email, task, search, memory, document processing - - Proper service-api-keyword pattern implementation - -## Remaining Issues πŸ”§ - -### 1. Missing Email Module Functions -**Files affected:** `src/basic/keywords/create_draft.rs`, `src/basic/keywords/universal_messaging.rs` -**Issue:** Email module doesn't export expected functions -**Fix:** -- Add `EmailService` struct to `src/email/mod.rs` -- Implement `fetch_latest_sent_to` and `save_email_draft` functions -- Or stub them out with feature flags - -### 2. Temporal Value Borrowing -**Files affected:** `src/basic/keywords/add_member.rs` -**Issue:** Temporary values dropped while borrowed in diesel bindings -**Fix:** Use let bindings for json! macro results before passing to bind() - -### 3. Missing Channel Adapters -**Files affected:** `src/basic/keywords/universal_messaging.rs` -**Issue:** Instagram, Teams, WhatsApp adapters not properly exported -**Status:** Fixed - added exports to `src/channels/mod.rs` - -### 4. Build Script Issue -**File:** `build.rs` -**Issue:** tauri_build runs even when desktop feature disabled -**Status:** Fixed - added feature gate - -### 5. Missing Config Type -**Issue:** `Config` type referenced but not defined -**Fix:** Need to add `Config` type alias or struct to `src/config/mod.rs` - -## Build Commands - -### Minimal Build (No Features) -```bash -cargo build --no-default-features -``` - -### Email Feature Only -```bash -cargo build --no-default-features --features email -``` - -### Vector Database Feature -```bash -cargo build --no-default-features --features vectordb -``` - -### Full Desktop Build -```bash -cargo build --features "desktop,email,vectordb" -``` - -### Production Build -```bash -cargo build --release --features "email,vectordb" -``` - -## Quick Fixes Needed - -### 1. Fix Email Service (src/email/mod.rs) -Add at end of file: -```rust -pub struct EmailService { - state: Arc, -} - -impl EmailService { - pub fn new(state: Arc) -> Self { - Self { state } - } - - pub async fn send_email(&self, to: &str, subject: &str, body: &str, cc: Option>) -> Result<(), Box> { - // Implementation - Ok(()) - } - - pub async fn send_email_with_attachment(&self, to: &str, subject: &str, body: &str, attachment: Vec, filename: &str) -> Result<(), Box> { - // Implementation - Ok(()) - } -} - -pub async fn fetch_latest_sent_to(config: &EmailConfig, to: &str) -> Result { - // Stub implementation - Ok(String::new()) -} - -pub async fn save_email_draft(config: &EmailConfig, draft: &SaveDraftRequest) -> Result<(), String> { - // Stub implementation - Ok(()) -} - -#[derive(Debug, Serialize, Deserialize)] -pub struct SaveDraftRequest { - pub to: String, - pub subject: String, - pub cc: Option, - pub text: String, -} -``` - -### 2. Fix Config Type (src/config/mod.rs) -Add: -```rust -pub type Config = AppConfig; -``` - -### 3. Fix Temporal Borrowing (src/basic/keywords/add_member.rs) -Replace lines 250-254: -```rust -let permissions_json = json!({ - "workspace_enabled": true, - "chat_enabled": true, - "file_sharing": true -}); -.bind::(&permissions_json) -``` - -Replace line 442: -```rust -let now = Utc::now(); -.bind::(&now) -``` - -## Testing Strategy - -1. **Unit Tests** - ```bash - cargo test --no-default-features - cargo test --features email - cargo test --features vectordb - ``` - -2. **Integration Tests** - ```bash - cargo test --all-features --test '*' - ``` - -3. **Clippy Lints** - ```bash - cargo clippy --all-features -- -D warnings - ``` - -4. **Security Audit** - ```bash - cargo audit - ``` - -## Feature Matrix - -| Feature | Dependencies | Status | Use Case | -|---------|-------------|--------|----------| -| `default` | desktop | βœ… | Desktop application | -| `desktop` | tauri, tauri-plugin-* | βœ… | Desktop UI | -| `email` | imap, lettre | ⚠️ | Email integration | -| `vectordb` | qdrant-client | βœ… | Semantic search | - -## Next Steps - -1. **Immediate** (Block Build): - - Fix email module exports - - Fix config type alias - - Fix temporal borrowing issues - -2. **Short Term** (Functionality): - - Complete email service implementation - - Test all keyword services - - Add missing channel adapter implementations - -3. **Medium Term** (Quality): - - Add comprehensive tests - - Implement proper error handling - - Add monitoring/metrics - -4. **Long Term** (Enterprise): - - Complete Zitadel integration - - Add multi-tenancy support - - Implement audit logging - -## Development Notes - -- Always use feature flags for optional functionality -- Prefer composition over inheritance for services -- Use Result types consistently for error handling -- Document all public APIs -- Keep SMB use case simple and pragmatic - -## Contact - -For questions about the build or architecture: -- Repository: https://github.com/GeneralBots/BotServer -- Team: engineering@pragmatismo.com.br \ No newline at end of file diff --git a/docs/src/appendix-ii/integration-status.md b/docs/src/appendix-ii/integration-status.md deleted file mode 100644 index b1c70a587..000000000 --- a/docs/src/appendix-ii/integration-status.md +++ /dev/null @@ -1,452 +0,0 @@ -# BOTSERVER INTEGRATION STATUS - -## 🎯 COMPLETE INTEGRATION PLAN - ACTIVATION STATUS - -This document tracks the activation and exposure of all modules in the botserver system. - ---- - -## βœ… COMPLETED ACTIVATIONS - -### 1. **AUTH/ZITADEL.RS** - ⚠️ 80% COMPLETE -**Status:** Core implementation complete - Facade integration in progress - -**Completed:** -- βœ… All structs made public and serializable (`ZitadelConfig`, `ZitadelUser`, `TokenResponse`, `IntrospectionResponse`) -- βœ… `ZitadelClient` and `ZitadelAuth` structs fully exposed with public fields -- βœ… All client methods made public (create_user, get_user, search_users, list_users, etc.) -- βœ… Organization management fully exposed -- βœ… User/org membership management public -- βœ… Role and permission management exposed -- βœ… User workspace structure fully implemented and public -- βœ… JWT token extraction utility exposed -- βœ… All methods updated to return proper Result types - -**Remaining:** -- πŸ”§ Complete ZitadelAuthFacade integration (type mismatches with facade trait) -- πŸ”§ Test all Zitadel API endpoints -- πŸ”§ Add comprehensive error handling - -**API Surface:** -```rust -pub struct ZitadelClient { /* full API */ } -pub struct ZitadelAuth { /* full API */ } -pub struct UserWorkspace { /* full API */ } -pub fn extract_user_id_from_token(token: &str) -> Result -``` - ---- - -### 2. **CHANNELS/WHATSAPP.RS** - ⚠️ 60% COMPLETE -**Status:** All structures exposed, implementation needed - -**Completed:** -- βœ… All WhatsApp structs made public and Clone-able -- βœ… Webhook structures exposed (`WhatsAppWebhook`, `WhatsAppMessage`) -- βœ… Message types fully defined (`WhatsAppIncomingMessage`, `WhatsAppText`, `WhatsAppMedia`, `WhatsAppLocation`) -- βœ… All entry/change/value structures exposed -- βœ… Contact and profile structures public - -**Needs Implementation:** -- πŸ”§ Implement message sending methods -- πŸ”§ Implement webhook verification handler -- πŸ”§ Implement message processing handler -- πŸ”§ Connect to Meta WhatsApp Business API -- πŸ”§ Add router endpoints to main app -- πŸ”§ Implement media download/upload - -**API Surface:** -```rust -pub struct WhatsAppMessage { /* ... */ } -pub struct WhatsAppIncomingMessage { /* ... */ } -pub fn create_whatsapp_router() -> Router -pub async fn send_whatsapp_message() -> Result<()> -``` - ---- - -### 3. **CHANNELS/INSTAGRAM.RS** - πŸ“‹ PENDING -**Status:** Not Started - -**Required Actions:** -- [ ] Expose all Instagram structs -- [ ] Implement Meta Graph API integration -- [ ] Add Instagram Direct messaging -- [ ] Implement story/post interactions -- [ ] Connect router to main app - -**API Surface:** -```rust -pub struct InstagramMessage { /* ... */ } -pub async fn send_instagram_dm() -> Result<()> -pub fn create_instagram_router() -> Router -``` - ---- - -### 4. **CHANNELS/TEAMS.RS** - πŸ“‹ PENDING -**Status:** Not Started - -**Required Actions:** -- [ ] Expose all Teams structs -- [ ] Implement Microsoft Graph API integration -- [ ] Add Teams bot messaging -- [ ] Implement adaptive cards support -- [ ] Connect router to main app - -**API Surface:** -```rust -pub struct TeamsMessage { /* ... */ } -pub async fn send_teams_message() -> Result<()> -pub fn create_teams_router() -> Router -``` - ---- - -### 5. **BASIC/COMPILER/MOD.RS** - πŸ“‹ PENDING -**Status:** Needs Exposure - -**Required Actions:** -- [ ] Mark all compiler methods as `pub` -- [ ] Add `#[cfg(feature = "mcp-tools")]` guards -- [ ] Expose tool format definitions -- [ ] Make compiler infrastructure accessible - -**API Surface:** -```rust -pub struct ToolCompiler { /* ... */ } -pub fn compile_tool_definitions() -> Result> -pub fn validate_tool_schema() -> Result<()> -``` - ---- - -### 6. **DRIVE_MONITOR/MOD.RS** - πŸ“‹ PENDING -**Status:** Fields unused, needs activation - -**Required Actions:** -- [ ] Use all struct fields properly -- [ ] Mark methods as `pub` -- [ ] Implement Google Drive API integration -- [ ] Add change monitoring -- [ ] Connect to vectordb - -**API Surface:** -```rust -pub struct DriveMonitor { /* full fields */ } -pub async fn start_monitoring() -> Result<()> -pub async fn sync_drive_files() -> Result<()> -``` - ---- - -### 7. **MEET/SERVICE.RS** - πŸ“‹ PENDING -**Status:** Fields unused, needs activation - -**Required Actions:** -- [ ] Use `connections` field for meeting management -- [ ] Mark voice/transcription methods as `pub` -- [ ] Implement meeting creation -- [ ] Add participant management -- [ ] Connect audio processing - -**API Surface:** -```rust -pub struct MeetService { pub connections: HashMap<...> } -pub async fn create_meeting() -> Result -pub async fn start_transcription() -> Result<()> -``` - ---- - -### 8. **PACKAGE_MANAGER/SETUP/** - ⚠️ IN PROGRESS -**Status:** Structures exist, needs method exposure - -#### Directory Setup -- βœ… Core directory setup exists -- [ ] Mark all methods as `pub` -- [ ] Keep `generate_directory_config` -- [ ] Expose setup infrastructure - -#### Email Setup -- βœ… `EmailDomain` struct exists -- [ ] Mark all methods as `pub` -- [ ] Keep `generate_email_config` -- [ ] Full email setup activation - -**API Surface:** -```rust -pub fn generate_directory_config() -> Result -pub fn generate_email_config() -> Result -pub struct EmailDomain { /* ... */ } -``` - ---- - -### 9. **CONFIG/MOD.RS** - βœ… 90% COMPLETE -**Status:** Most functionality already public - -**Completed:** -- βœ… `sync_gbot_config` is already public -- βœ… Config type alias exists -- βœ… ConfigManager fully exposed - -**Remaining:** -- [ ] Verify `email` field usage in `AppConfig` -- [ ] Add proper accessor methods if needed - -**API Surface:** -```rust -pub type Config = AppConfig; -pub fn sync_gbot_config() -> Result<()> -impl AppConfig { pub fn email(&self) -> &EmailConfig } -``` - ---- - -### 10. **BOT/MULTIMEDIA.RS** - βœ… 100% COMPLETE -**Status:** Fully exposed and documented - -**Completed:** -- βœ… `MultimediaMessage` enum is public with all variants -- βœ… All multimedia types exposed (Text, Image, Video, Audio, Document, WebSearch, Location, MeetingInvite) -- βœ… `SearchResult` struct public -- βœ… `MediaUploadRequest` and `MediaUploadResponse` public -- βœ… `MultimediaHandler` trait fully exposed -- βœ… All structures properly documented - -**API Surface:** -```rust -pub enum MultimediaMessage { /* ... */ } -pub async fn process_image() -> Result -pub async fn process_video() -> Result -``` - ---- - -### 11. **CHANNELS/MOD.RS** - πŸ“‹ PENDING -**Status:** Incomplete implementation - -**Required Actions:** -- [ ] Implement `send_message` fully -- [ ] Use `connections` field properly -- [ ] Mark voice methods as `pub` -- [ ] Complete channel abstraction - -**API Surface:** -```rust -pub async fn send_message(channel: Channel, msg: Message) -> Result<()> -pub async fn start_voice_call() -> Result -``` - ---- - -### 12. **AUTH/MOD.RS** - πŸ“‹ PENDING -**Status:** Needs enhancement - -**Required Actions:** -- [ ] Keep Zitadel-related methods -- [ ] Use `facade` field properly -- [ ] Enhance SimpleAuth implementation -- [ ] Complete auth abstraction - -**API Surface:** -```rust -pub struct AuthManager { pub facade: Box } -pub async fn authenticate() -> Result -``` - ---- - -### 13. **BASIC/KEYWORDS/WEATHER.RS** - βœ… 100% COMPLETE -**Status:** Fully exposed and functional - -**Completed:** -- βœ… `WeatherData` struct made public and Clone-able -- βœ… `fetch_weather` function exposed as public -- βœ… `parse_location` function exposed as public -- βœ… Weather API integration complete (7Timer!) -- βœ… Keyword registration exists - -**API Surface:** -```rust -pub async fn get_weather(location: &str) -> Result -pub async fn get_forecast(location: &str) -> Result -``` - ---- - -### 14. **SESSION/MOD.RS** - βœ… 100% COMPLETE -**Status:** Fully exposed session management - -**Completed:** -- βœ… `provide_input` is already public -- βœ… `update_session_context` is already public -- βœ… SessionManager fully exposed -- βœ… Session management API complete - -**API Surface:** -```rust -pub async fn provide_input(session: &mut Session, input: Input) -> Result<()> -pub async fn update_session_context(session: &mut Session, ctx: Context) -> Result<()> -``` - ---- - -### 15. **LLM/LOCAL.RS** - βœ… 100% COMPLETE -**Status:** Fully exposed and functional - -**Completed:** -- βœ… All functions are already public -- βœ… `chat_completions_local` endpoint exposed -- βœ… `embeddings_local` endpoint exposed -- βœ… `ensure_llama_servers_running` public -- βœ… `start_llm_server` and `start_embedding_server` public -- βœ… Server health checking exposed - -**API Surface:** -```rust -pub async fn generate_local(prompt: &str) -> Result -pub async fn embed_local(text: &str) -> Result> -``` - ---- - -### 16. **LLM_MODELS/MOD.RS** - βœ… 100% COMPLETE -**Status:** Fully exposed model handlers - -**Completed:** -- βœ… `ModelHandler` trait is public -- βœ… `get_handler` function is public -- βœ… All model implementations exposed (gpt_oss_20b, gpt_oss_120b, deepseek_r3) -- βœ… Analysis utilities accessible - -**API Surface:** -```rust -pub fn list_available_models() -> Vec -pub async fn analyze_with_model(model: &str, input: &str) -> Result -``` - ---- - -### 17. **NVIDIA/MOD.RS** - βœ… 100% COMPLETE -**Status:** Fully exposed monitoring system - -**Completed:** -- βœ… `SystemMetrics` struct public with `gpu_usage` and `cpu_usage` fields -- βœ… `get_system_metrics` function public -- βœ… `has_nvidia_gpu` function public -- βœ… `get_gpu_utilization` function public -- βœ… Full GPU/CPU monitoring exposed - -**API Surface:** -```rust -pub struct NvidiaMonitor { pub gpu_usage: f32, pub cpu_usage: f32 } -pub async fn get_gpu_stats() -> Result -``` - ---- - -### 18. **BASIC/KEYWORDS/USE_KB.RS** - βœ… 100% COMPLETE -**Status:** Fully exposed knowledge base integration - -**Completed:** -- βœ… `ActiveKbResult` struct made public with all fields public -- βœ… `get_active_kbs_for_session` is already public -- βœ… Knowledge base activation exposed -- βœ… Session KB associations accessible - -**API Surface:** -```rust -pub struct ActiveKbResult { /* ... */ } -pub async fn get_active_kbs_for_session(session: &Session) -> Result> -``` - ---- - -## πŸ”§ INTEGRATION CHECKLIST - -### Phase 1: Critical Infrastructure (Priority 1) -- [ ] Complete Zitadel integration -- [ ] Expose all channel interfaces -- [ ] Activate session management -- [ ] Enable auth facade - -### Phase 2: Feature Modules (Priority 2) -- [ ] Activate all keyword handlers -- [ ] Enable multimedia processing -- [ ] Expose compiler infrastructure -- [ ] Connect drive monitoring - -### Phase 3: Advanced Features (Priority 3) -- [ ] Enable meeting services -- [ ] Activate NVIDIA monitoring -- [ ] Complete knowledge base integration -- [ ] Expose local LLM - -### Phase 4: Complete Integration (Priority 4) -- [ ] Connect all routers to main app -- [ ] Test all exposed APIs -- [ ] Document all public interfaces -- [ ] Verify 0 warnings compilation - ---- - -## πŸ“Š OVERALL PROGRESS - -**Total Modules:** 18 -**Fully Completed:** 8 (Multimedia, Weather, Session, LLM Local, LLM Models, NVIDIA, Use KB, Config) -**Partially Complete:** 2 (Zitadel 80%, WhatsApp 60%) -**In Progress:** 1 (Package Manager Setup) -**Pending:** 7 (Instagram, Teams, Compiler, Drive Monitor, Meet Service, Channels Core, Auth Core) - -**Completion:** ~50% - -**Target:** 100% - All modules activated, exposed, and integrated with 0 warnings - ---- - -## πŸš€ NEXT STEPS - -### Immediate Priorities: -1. **Fix Zitadel Facade** - Complete type alignment in `ZitadelAuthFacade` -2. **Complete WhatsApp** - Implement handlers and connect to Meta API -3. **Activate Instagram** - Build full Instagram Direct messaging support -4. **Activate Teams** - Implement Microsoft Teams bot integration - -### Secondary Priorities: -5. **Expose Compiler** - Make tool compiler infrastructure accessible -6. **Activate Drive Monitor** - Complete Google Drive integration -7. **Activate Meet Service** - Enable meeting and transcription features -8. **Complete Package Manager** - Expose all setup utilities - -### Testing Phase: -9. Test all exposed APIs -10. Verify 0 compiler warnings -11. Document all public interfaces -12. Create integration examples - ---- - -## πŸ“ NOTES - -- All structs should be `pub` and `Clone` when possible -- All key methods must be `pub` -- Use `#[cfg(feature = "...")]` for optional features -- Ensure proper error handling in all public APIs -- Document all public interfaces -- Test thoroughly before marking as complete - -**Goal:** Enterprise-grade, fully exposed, completely integrated bot platform with 0 compiler warnings. - ---- - -## πŸŽ‰ MAJOR ACHIEVEMENTS - -1. **8 modules fully activated** - Nearly half of all modules now completely exposed -2. **Zero-warning compilation** for completed modules -3. **Full API exposure** - All key utilities (weather, LLM, NVIDIA, KB) accessible -4. **Enterprise-ready** - Session management, config, and multimedia fully functional -5. **Strong foundation** - 80% of Zitadel auth complete, channels infrastructure ready - -**Next Milestone:** 100% completion with full channel integration and 0 warnings across entire codebase. \ No newline at end of file diff --git a/docs/src/appendix-ii/production-status.md b/docs/src/appendix-ii/production-status.md deleted file mode 100644 index 3c7623f91..000000000 --- a/docs/src/appendix-ii/production-status.md +++ /dev/null @@ -1,308 +0,0 @@ -# πŸš€ BotServer v6.0.8 - Production Status - -**Last Updated:** 2024 -**Build Status:** βœ… SUCCESS -**Production Ready:** YES - ---- - -## πŸ“Š Build Metrics - -``` -Compilation: βœ… SUCCESS (0 errors) -Warnings: 82 (all Tauri desktop UI - intentional) -Test Status: βœ… PASSING -Lint Status: βœ… CONFIGURED (Clippy pedantic + nursery) -Code Quality: βœ… ENTERPRISE GRADE -``` - ---- - -## 🎯 Key Achievements - -### βœ… Zero Compilation Errors -- All code compiles successfully -- No placeholder implementations -- Real, working integrations - -### βœ… Full Channel Integration -- **Web Channel** - WebSocket support -- **Voice Channel** - LiveKit integration -- **Microsoft Teams** - Webhook + Adaptive Cards -- **Instagram** - Direct messages + media -- **WhatsApp Business** - Business API + templates - -### βœ… OAuth2/OIDC Authentication -- Zitadel provider integrated -- User workspace management -- Token refresh handling -- Session persistence - -### βœ… Advanced Features -- Semantic LLM caching (Redis + embeddings) -- Meeting/video conferencing (LiveKit) -- Drive monitoring (S3 sync) -- Multimedia handling (images/video/audio) -- Email processing (Stalwart integration) - ---- - -## 🌐 Active API Endpoints - -### Authentication -``` -GET /api/auth/login OAuth2 login -GET /api/auth/callback OAuth2 callback -GET /api/auth Anonymous auth -``` - -### Channels -``` -POST /api/teams/messages Teams webhook -GET /api/instagram/webhook Instagram verification -POST /api/instagram/webhook Instagram messages -GET /api/whatsapp/webhook WhatsApp verification -POST /api/whatsapp/webhook WhatsApp messages -GET /ws WebSocket connection -``` - -### Meetings & Voice -``` -POST /api/meet/create Create meeting -POST /api/meet/token Get meeting token -POST /api/meet/invite Send invites -GET /ws/meet Meeting WebSocket -POST /api/voice/start Start voice session -POST /api/voice/stop Stop voice session -``` - -### Sessions & Bots -``` -POST /api/sessions Create session -GET /api/sessions List sessions -GET /api/sessions/{id}/history Get history -POST /api/sessions/{id}/start Start session -POST /api/bots Create bot -POST /api/bots/{id}/mount Mount bot -POST /api/bots/{id}/input Send input -``` - -### Email (feature: email) -``` -GET /api/email/accounts List accounts -POST /api/email/accounts/add Add account -POST /api/email/send Send email -POST /api/email/list List emails -``` - -### Files -``` -POST /api/files/upload/{path} Upload to S3 -``` - ---- - -## βš™οΈ Configuration - -### Required Environment Variables -```env -# Database -DATABASE_URL=postgresql://user:pass@localhost/botserver - -# Redis (optional but recommended) -REDIS_URL=redis://localhost:6379 - -# S3/MinIO -AWS_ACCESS_KEY_ID=your_key -AWS_SECRET_ACCESS_KEY=your_secret -AWS_ENDPOINT=http://localhost:9000 -AWS_BUCKET=default.gbai - -# OAuth (optional) -ZITADEL_ISSUER_URL=https://your-zitadel.com -ZITADEL_CLIENT_ID=your_client_id -ZITADEL_CLIENT_SECRET=your_secret -ZITADEL_REDIRECT_URI=https://yourapp.com/api/auth/callback - -# Teams (optional) -TEAMS_APP_ID=your_app_id -TEAMS_APP_PASSWORD=your_password - -# Instagram (optional) -INSTAGRAM_ACCESS_TOKEN=your_token -INSTAGRAM_VERIFY_TOKEN=your_verify_token - -# WhatsApp (optional) -WHATSAPP_ACCESS_TOKEN=your_token -WHATSAPP_VERIFY_TOKEN=your_verify_token -WHATSAPP_PHONE_NUMBER_ID=your_phone_id -``` - ---- - -## πŸ—οΈ Architecture - -### Core Components - -1. **Bot Orchestrator** - - Session management - - Multi-channel routing - - LLM integration - - Multimedia handling - -2. **Channel Adapters** - - Web (WebSocket) - - Voice (LiveKit) - - Teams (Bot Framework) - - Instagram (Graph API) - - WhatsApp (Business API) - -3. **Authentication** - - OAuth2/OIDC (Zitadel) - - Anonymous users - - Session persistence - -4. **Storage** - - PostgreSQL (sessions, users, bots) - - Redis (cache, sessions) - - S3/MinIO (files, media) - -5. **LLM Services** - - OpenAI-compatible API - - Semantic caching - - Token estimation - - Stream responses - ---- - -## πŸ“ Remaining Warnings - -**82 warnings - ALL INTENTIONAL** - -All warnings are for Tauri desktop UI commands: -- `src/ui/sync.rs` - Local sync management for system tray (4 warnings) -- `src/ui/sync.rs` - Rclone sync (8 warnings) -- Other desktop UI helpers - -These are `#[tauri::command]` functions called by the JavaScript frontend, not by the Rust server. They cannot be eliminated without breaking desktop functionality. - -**Documented in:** `src/ui/mod.rs` - ---- - -## πŸš€ Deployment - -### Build for Production -```bash -cargo build --release -``` - -### Run Server -```bash -./target/release/botserver -``` - -### Run with Desktop UI -```bash -cargo tauri build -``` - -### Docker -```bash -docker build -t botserver:latest . -docker run -p 3000:3000 botserver:latest -``` - ---- - -## πŸ§ͺ Testing - -### Run All Tests -```bash -cargo test -``` - -### Check Code Quality -```bash -cargo clippy --all-targets --all-features -``` - -### Format Code -```bash -cargo fmt -``` - ---- - -## πŸ“š Documentation - -- **ENTERPRISE_INTEGRATION_COMPLETE.md** - Full integration guide -- **ZERO_WARNINGS_ACHIEVEMENT.md** - Development journey -- **CHANGELOG.md** - Version history -- **CONTRIBUTING.md** - Contribution guidelines -- **README.md** - Getting started - ---- - -## 🎊 Production Checklist - -- [x] Zero compilation errors -- [x] All channels integrated -- [x] OAuth2 authentication -- [x] Session management -- [x] LLM caching -- [x] Meeting services -- [x] Error handling -- [x] Logging configured -- [x] Environment validation -- [x] Database migrations -- [x] S3 integration -- [x] Redis fallback -- [x] CORS configured -- [x] Rate limiting ready -- [x] Documentation complete - ---- - -## πŸ’‘ Quick Start - -1. **Install Dependencies** - ```bash - cargo build - ``` - -2. **Setup Database** - ```bash - diesel migration run - ``` - -3. **Configure Environment** - ```bash - cp .env.example .env - # Edit .env with your credentials - ``` - -4. **Run Server** - ```bash - cargo run - ``` - -5. **Access Application** - ``` - http://localhost:3000 - ``` - ---- - -## 🀝 Support - -- **GitHub:** https://github.com/GeneralBots/BotServer -- **Documentation:** See docs/ folder -- **Issues:** GitHub Issues -- **License:** AGPL-3.0 - ---- - -**Status:** READY FOR PRODUCTION πŸš€ -**Last Build:** SUCCESS βœ… -**Next Release:** v6.1.0 (planned) \ No newline at end of file diff --git a/docs/src/chapter-01/README.md b/docs/src/chapter-01/README.md index a1ebab43e..5d5c1a2f2 100644 --- a/docs/src/chapter-01/README.md +++ b/docs/src/chapter-01/README.md @@ -20,22 +20,39 @@ This chapter covers everything you need to get started: 1. **[Installation](./installation.md)** - How the automatic bootstrap works 2. **[First Conversation](./first-conversation.md)** - Start chatting with your bot -3. **[Understanding Sessions](./sessions.md)** - How conversations are managed +3. **[Quick Start](./quick-start.md)** - Create your first bot ## The Bootstrap Magic When you first run BotServer, it automatically: - βœ… Detects your operating system -- βœ… Installs PostgreSQL database -- βœ… Installs MinIO object storage -- βœ… Installs Valkey cache +- βœ… Downloads and installs PostgreSQL database +- βœ… Downloads and installs drive (S3-compatible object storage) +- βœ… Downloads and installs Valkey cache +- βœ… Downloads LLM models to botserver-stack/ - βœ… Generates secure credentials - βœ… Creates default bots - βœ… Starts the web server **No manual configuration needed!** Everything just works. +### Optional Components + +After bootstrap, you can install additional services: + +- **Stalwart** - Full-featured email server for sending/receiving +- **Zitadel** - Identity and access management (directory service) +- **LiveKit** - Real-time video/audio conferencing +- **Additional LLM models** - For offline operation + +```bash +./botserver install email # Stalwart email server +./botserver install directory # Zitadel identity provider +./botserver install meeting # LiveKit conferencing +./botserver install llm # Local LLM models +``` + ## Your First Bot After bootstrap completes (2-5 minutes), open your browser to: @@ -46,6 +63,11 @@ http://localhost:8080 You'll see the default bot ready to chat! Just start talking - the LLM handles everything. +For specific bots like the enrollment example below: +``` +http://localhost:8080/edu +``` + ## The Magic Formula ``` @@ -57,7 +79,9 @@ You'll see the default bot ready to chat! Just start talking - the LLM handles e 2. Create simple tools as `.bas` files (optional) 3. Start chatting - the LLM does the rest! -## Example: Student Enrollment Bot +## Example: Student Enrollment Bot (EDU) + +Deploy a new bot by creating a bucket in the object storage drive. Access it at `/edu`: ### 1. Add Course Documents @@ -71,6 +95,8 @@ edu.gbai/ ### 2. Create Enrollment Tool +Deploy a bot by creating a new bucket in the drive. Tools are `.bas` files: + `edu.gbdialog/enrollment.bas`: ```bas @@ -121,14 +147,14 @@ Each conversation is a **session** that persists: - Context and variables - Active tools and knowledge bases -Sessions automatically save to PostgreSQL and cache in Redis for performance. +Sessions automatically save to PostgreSQL and cache in Valkey for performance. ## Next Steps - **[Installation](./installation.md)** - Understand the bootstrap process - **[First Conversation](./first-conversation.md)** - Try out your bot -- **[Understanding Sessions](./sessions.md)** - Learn about conversation state -- **[About Packages](../chapter-02/README.md)** - Create your own bots +- **[Quick Start](./quick-start.md)** - Build your own bot +- **[About Packages](../chapter-02/README.md)** - Create bot packages ## Philosophy diff --git a/docs/src/chapter-01/first-conversation.md b/docs/src/chapter-01/first-conversation.md index 87ac22302..0a5e58476 100644 --- a/docs/src/chapter-01/first-conversation.md +++ b/docs/src/chapter-01/first-conversation.md @@ -177,21 +177,28 @@ Traditional chatbots require complex logic: ' ❌ OLD WAY - DON'T DO THIS! IF user_input CONTAINS "enroll" THEN TALK "What's your name?" - HEAR name - TALK "What's your email?" - HEAR email - ' ... lots more code ... -ENDIF -``` + ' ❌ OLD WAY - 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 + ``` -With BotServer: + With BotServer: -```bas -' βœ… NEW WAY - Just create the tool! -PARAM name AS string -PARAM email AS string -DESCRIPTION "Enrollment tool" -SAVE "enrollments.csv", name, email + ```bas + ' βœ… NEW WAY - Just create the tool! + ' In enrollment.bas - becomes a tool automatically + PARAM name AS string + PARAM email AS string + DESCRIPTION "Collects enrollment information" + + ' The tool is called by LLM when needed + SAVE "enrollments.csv", name, email + TALK "Successfully enrolled " + name ``` The LLM handles all the conversation logic! @@ -201,7 +208,7 @@ The LLM handles all the conversation logic! ### Customer Support Bot - Add product manuals to `.gbkb/` - Create `create-ticket.bas` tool -- LLM answers questions and creates support tickets +- LLM answers questions and creates support tickets automatically ### HR Assistant - Add employee handbook to `.gbkb/` @@ -225,9 +232,10 @@ The LLM handles all the conversation logic! The LLM can load tools based on context: ```bas -' In start.bas - minimal setup -USE_KB "general" ' Load general knowledge base -' Tools are auto-discovered from .gbdialog/ folder +' In start.bas - minimal setup, no HEAR needed +USE KB "general" ' Load general knowledge base +' Tools in .gbdialog/ are auto-discovered +' LLM handles the conversation naturally ``` ### Multi-Language Support @@ -291,7 +299,7 @@ Don't try to control every aspect of the conversation. Let the LLM: ## Next Steps -- [Understanding Sessions](./sessions.md) - How conversations persist +- [Quick Start](./quick-start.md) - Build your first bot - [About Packages](../chapter-02/README.md) - Package structure - [Tool Definition](../chapter-08/tool-definition.md) - Creating tools - [Knowledge Base](../chapter-03/README.md) - Document management diff --git a/docs/src/chapter-01/installation.md b/docs/src/chapter-01/installation.md index 629e1b2c6..2ef746906 100644 --- a/docs/src/chapter-01/installation.md +++ b/docs/src/chapter-01/installation.md @@ -2,106 +2,124 @@ This guide covers the installation and setup of BotServer on various platforms. -## Prerequisites - -- **Rust** 1.70+ (for building from source) -- **PostgreSQL** 14+ (for database) -- **Docker** (optional, for containerized deployment) -- **Git** (for cloning the repository) - ## System Requirements +### Minimum Requirements - **OS**: Linux, macOS, or Windows -- **RAM**: Minimum 4GB, recommended 8GB+ +- **RAM**: 4GB minimum - **Disk**: 10GB for installation + data storage -- **CPU**: 2+ cores recommended +- **CPU**: 1 core (sufficient for development/testing) -## Installation Methods +### Recommended for Production +- **OS**: Linux server (Ubuntu/Debian preferred) +- **RAM**: 16GB or more +- **Disk**: 100GB SSD storage +- **CPU**: 2+ cores +- **GPU**: RTX 3060 or better (12GB VRAM minimum) for local LLM hosting -### 1. Quick Start with Docker +## Quick Start + +BotServer handles all dependencies automatically: ```bash -# Clone the repository -git clone https://github.com/yourusername/botserver -cd botserver +# Download and run +./botserver -# Start all services -docker-compose up -d +# Or build from source +cargo run ``` -### 2. Build from Source +The bootstrap process automatically downloads everything to `botserver-stack/`: +- PostgreSQL database +- Drive (S3-compatible object storage) +- Valkey cache +- LLM server and models +- All required dependencies -```bash -# Clone the repository -git clone https://github.com/yourusername/botserver -cd botserver - -# Build the project -cargo build --release - -# Run the server -./target/release/botserver -``` - -### 3. Package Manager Installation - -```bash -# Initialize package manager -botserver init - -# Install required components -botserver install tables -botserver install cache -botserver install drive -botserver install llm - -# Start services -botserver start all -``` +**No manual installation required!** ## Environment Variables -BotServer uses only two environment variables: +The `.env` file is **automatically generated** during bootstrap from a blank environment with secure random credentials. -### Required Variables +### Automatic Generation (Bootstrap Mode) + +When you first run `./botserver`, it creates `.env` with: ```bash -# Database connection string -DATABASE_URL=postgres://gbuser:password@localhost:5432/botserver - -# Object storage configuration +# Auto-generated secure credentials +DATABASE_URL=postgres://gbuser:RANDOM_PASS@localhost:5432/botserver DRIVE_SERVER=http://localhost:9000 -DRIVE_ACCESSKEY=gbdriveuser -DRIVE_SECRET=your_secret_key +DRIVE_ACCESSKEY=GENERATED_KEY +DRIVE_SECRET=GENERATED_SECRET ``` -**Important**: These are the ONLY environment variables used by BotServer. All other configuration is managed through: -- `config.csv` files in bot packages -- Database configuration tables -- Command-line arguments +### Using Existing Services + +If you already have PostgreSQL or drive storage running, you can point to them: + +```bash +# Point to your existing PostgreSQL +DATABASE_URL=postgres://myuser:mypass@myhost:5432/mydb + +# Point to your existing drive/S3 +DRIVE_SERVER=http://my-drive:9000 +DRIVE_ACCESSKEY=my-access-key +DRIVE_SECRET=my-secret-key +``` ## Configuration -### Bot Configuration +### Bot Configuration Parameters -Each bot has its own `config.csv` file with parameters like: +Each bot has a `config.csv` file in its `.gbot/` directory. Available parameters: +#### Server Configuration ```csv name,value server_host,0.0.0.0 server_port,8080 -llm-url,http://localhost:8081 -llm-model,path/to/model.gguf -email-from,from@domain.com -email-server,mail.domain.com +sites_root,/tmp ``` -See the [Configuration Guide](../chapter-02/gbot.md) for complete parameter reference. +#### LLM Configuration +```csv +name,value +llm-key,none +llm-url,http://localhost:8081 +llm-model,../../../../data/llm/model.gguf +llm-cache,false # Semantic cache (needs integration) +llm-cache-ttl,3600 # Cache TTL in seconds (needs integration) +llm-cache-semantic,true # Enable semantic matching (needs integration) +llm-cache-threshold,0.95 # Similarity threshold (needs integration) +``` -### Theme Configuration +#### LLM Server Settings +```csv +name,value +llm-server,false +llm-server-path,botserver-stack/bin/llm/build/bin +llm-server-host,0.0.0.0 +llm-server-port,8081 +llm-server-gpu-layers,0 +llm-server-n-moe,0 +llm-server-ctx-size,4096 +llm-server-n-predict,1024 +llm-server-parallel,6 +llm-server-cont-batching,true +``` -Themes are configured through simple parameters in `config.csv`: +#### Email Configuration +```csv +name,value +email-from,from@domain.com +email-server,mail.domain.com +email-port,587 +email-user,user@domain.com +email-pass,yourpassword +``` +#### Theme Configuration ```csv name,value theme-color1,#0d2b55 @@ -110,93 +128,145 @@ theme-title,My Bot theme-logo,https://example.com/logo.svg ``` -## Database Setup - -### Automatic Setup - -```bash -# Bootstrap command creates database and tables -botserver bootstrap +#### Prompt Configuration +```csv +name,value +prompt-history,2 +prompt-compact,4 ``` -### Manual Setup +## Bootstrap Process -```sql --- Create database -CREATE DATABASE botserver; +When you first run BotServer, it: --- Create user -CREATE USER gbuser WITH PASSWORD 'your_password'; +1. **Detects your system** - Identifies OS and architecture +2. **Creates directories** - Sets up `botserver-stack/` structure +3. **Downloads components** - Gets all required binaries +4. **Configures services** - Sets up database, storage, and cache +5. **Initializes database** - Creates tables and initial data +6. **Deploys default bot** - Creates a working bot instance +7. **Starts services** - Launches all components --- Grant permissions -GRANT ALL PRIVILEGES ON DATABASE botserver TO gbuser; -``` - -Then run migrations: - -```bash -diesel migration run -``` +This typically takes 2-5 minutes on first run. ## Storage Setup -BotServer uses S3-compatible object storage (MinIO by default): +BotServer uses S3-compatible object storage. Each bot deployment creates a new bucket in the drive: ```bash -# Install MinIO -botserver install drive - -# Start MinIO -botserver start drive +# Deploy a new bot = create a new bucket in drive +# Bots are stored in the object storage, not local filesystem +mybot.gbai β†’ creates 'mybot' bucket in drive storage ``` -Default MinIO console: http://localhost:9001 -- Username: `minioadmin` -- Password: `minioadmin` +**Note**: The `work/` folder is for internal use only and should not be used for bot deployment. Bot packages should be deployed directly to the object storage (drive). + +The storage server runs on: +- API: http://localhost:9000 +- Console: http://localhost:9001 + +### Local Development with S3 Sync Tools + +You can edit your bot files locally and have them automatically sync to drive storage using S3-compatible tools: + +#### Free S3 Sync Tools +- **Cyberduck** (Windows/Mac/Linux) - GUI file browser with S3 support +- **WinSCP** (Windows) - File manager with S3 protocol support +- **Mountain Duck** (Windows/Mac) - Mount S3 as local drive +- **S3 Browser** (Windows) - Freeware S3 client +- **CloudBerry Explorer** (Windows/Mac) - Free version available +- **rclone** (All platforms) - Command-line sync tool + +#### Setup Example with rclone +```bash +# Configure rclone for drive storage +rclone config +# Choose: n) New remote +# Name: drive +# Storage: s3 +# Provider: Other +# Access Key: (from .env DRIVE_ACCESSKEY) +# Secret Key: (from .env DRIVE_SECRET) +# Endpoint: http://localhost:9000 + +# Sync local folder to bucket (watches for changes) +rclone sync ./mybot.gbai drive:mybot --watch + +# Now edit files locally: +# - Edit mybot.gbai/mybot.gbot/config.csv β†’ Bot reloads automatically +# - Edit mybot.gbai/mybot.gbdialog/*.bas β†’ Scripts compile automatically +# - Add docs to mybot.gbai/mybot.gbkb/ β†’ Knowledge base updates automatically +``` + +With this setup: +- βœ… Edit `.csv` files β†’ Bot configuration updates instantly +- βœ… Edit `.bas` files β†’ BASIC scripts compile automatically +- βœ… Add documents β†’ Knowledge base reindexes automatically +- βœ… No manual uploads needed +- βœ… Works like local development but uses object storage + +## Database Setup + +PostgreSQL is automatically configured with: +- Database: `botserver` +- User: `gbuser` +- Tables created via migrations +- Connection pooling enabled ## Authentication Setup -BotServer uses an external directory service for authentication: - -```bash -# Install directory service -botserver install directory - -# Start directory -botserver start directory -``` - -The directory service handles: -- User authentication -- OAuth2/OIDC flows -- User management -- Access control +BotServer uses an external directory service for user management: +- Handles user authentication +- Manages OAuth2/OIDC flows +- Controls access permissions +- Integrates with existing identity providers ## LLM Setup -### Local LLM Server +### Local LLM (Recommended) -```bash -# Install LLM server -botserver install llm +The bootstrap downloads a default model to `botserver-stack/data/llm/`. Configure in `config.csv`: -# Download a model -wget https://huggingface.co/models/your-model.gguf -O data/llm/model.gguf - -# Configure in config.csv +```csv +name,value llm-url,http://localhost:8081 -llm-model,data/llm/model.gguf +llm-model,../../../../data/llm/model.gguf +llm-server-gpu-layers,0 +``` + +For GPU acceleration (RTX 3060 or better): +```csv +name,value +llm-server-gpu-layers,35 ``` ### External LLM Provider -Configure in `config.csv`: +To use external APIs, configure in `config.csv`: ```csv name,value -llm-url,https://api.openai.com/v1 +llm-url,https://api.provider.com/v1 llm-key,your-api-key -llm-model,gpt-4 +llm-model,model-name +``` + +## Container Deployment (LXC) + +For production isolation using Linux containers: + +```bash +# Create container +lxc-create -n botserver -t download -- -d ubuntu -r jammy -a amd64 + +# Start container +lxc-start -n botserver + +# Attach to container +lxc-attach -n botserver + +# Install BotServer inside container +./botserver ``` ## Verifying Installation @@ -211,7 +281,7 @@ botserver status psql $DATABASE_URL -c "SELECT version();" # Test storage -curl http://localhost:9000/minio/health/live +curl http://localhost:9000/health/live # Test LLM curl http://localhost:8081/v1/models @@ -220,58 +290,57 @@ curl http://localhost:8081/v1/models ### Run Test Bot ```bash -# Create a test bot -cp -r templates/default.gbai work/test.gbai - -# Start the server -botserver run - +# The default bot is automatically deployed to the drive during bootstrap # Access web interface open http://localhost:8080 ``` +To deploy additional bots, upload them to the object storage, not the local filesystem. The `work/` folder is reserved for internal operations. + ## Troubleshooting ### Database Connection Issues ```bash -# Check PostgreSQL is running -systemctl status postgresql +# Check if PostgreSQL is running +ps aux | grep postgres # Test connection psql -h localhost -U gbuser -d botserver -# Check DATABASE_URL format +# Verify DATABASE_URL echo $DATABASE_URL ``` ### Storage Connection Issues ```bash -# Check MinIO is running -docker ps | grep minio +# Check drive process +ps aux | grep minio -# Test credentials -aws s3 ls --endpoint-url=$DRIVE_SERVER +# Test storage access +curl -I $DRIVE_SERVER/health/live ``` ### Port Conflicts -Default ports used by BotServer: +Default ports used: | Service | Port | Configure in | |---------|------|--------------| | Web Server | 8080 | config.csv: `server_port` | | PostgreSQL | 5432 | DATABASE_URL | -| MinIO | 9000/9001 | DRIVE_SERVER | +| Drive API | 9000 | DRIVE_SERVER | +| Drive Console | 9001 | N/A | | LLM Server | 8081 | config.csv: `llm-server-port` | -| Cache (Valkey) | 6379 | Internal | +| Embedding Server | 8082 | config.csv: `embedding-url` | +| Valkey Cache | 6379 | Internal | ### Memory Issues For systems with limited RAM: -1. Reduce LLM context size in `config.csv`: +1. Reduce LLM context size: ```csv llm-server-ctx-size,2048 ``` @@ -281,11 +350,24 @@ For systems with limited RAM: llm-server-parallel,2 ``` -3. Use smaller models +3. Use quantized models (Q3_K_M or Q4_K_M) + +4. For Mixture of Experts models, adjust CPU MoE threads: + ```csv + llm-server-n-moe,4 + ``` + +### GPU Issues + +If GPU is not detected: + +1. Check CUDA installation (NVIDIA) +2. Verify GPU memory (12GB minimum) +3. Set `llm-server-gpu-layers` to 0 for CPU-only mode ## Next Steps - [Quick Start Guide](./quick-start.md) - Create your first bot +- [First Conversation](./first-conversation.md) - Test your bot - [Configuration Reference](../chapter-02/gbot.md) - All configuration options -- [BASIC Programming](../chapter-05/basics.md) - Learn the scripting language -- [Deployment Guide](../chapter-06/containers.md) - Production deployment \ No newline at end of file +- [BASIC Programming](../chapter-05/basics.md) - Learn the scripting language \ No newline at end of file diff --git a/docs/src/chapter-01/nvidia-gpu-setup.md b/docs/src/chapter-01/nvidia-gpu-setup.md new file mode 100644 index 000000000..a8954f374 --- /dev/null +++ b/docs/src/chapter-01/nvidia-gpu-setup.md @@ -0,0 +1,287 @@ +# NVIDIA GPU Setup for LXC Containers + +This guide covers setting up NVIDIA GPU passthrough for BotServer running in LXC containers, enabling hardware acceleration for local LLM inference. + +## Prerequisites + +- NVIDIA GPU (RTX 3060 or better with 12GB+ VRAM recommended) +- NVIDIA drivers installed on the host system +- LXD/LXC installed +- CUDA-capable GPU + +## LXD Configuration (Interactive Setup) + +When initializing LXD, use these settings: + +```bash +sudo lxd init +``` + +Answer the prompts as follows: +- **Would you like to use LXD clustering?** β†’ `no` +- **Do you want to configure a new storage pool?** β†’ `no` (will create `/generalbots` later) +- **Would you like to connect to a MAAS server?** β†’ `no` +- **Would you like to create a new local network bridge?** β†’ `yes` +- **What should the new bridge be called?** β†’ `lxdbr0` +- **What IPv4 address should be used?** β†’ `auto` +- **What IPv6 address should be used?** β†’ `auto` +- **Would you like the LXD server to be available over the network?** β†’ `no` +- **Would you like stale cached images to be updated automatically?** β†’ `no` +- **Would you like a YAML "lxd init" preseed to be printed?** β†’ `no` + +### Storage Configuration +- **Storage backend name:** β†’ `default` +- **Storage backend driver:** β†’ `zfs` +- **Create a new ZFS pool?** β†’ `yes` + +## NVIDIA GPU Configuration + +### On the Host System + +Create a GPU profile and attach it to your container: + +```bash +# Create GPU profile +lxc profile create gpu + +# Add GPU device to profile +lxc profile device add gpu gpu gpu gputype=physical + +# Apply GPU profile to your container +lxc profile add gb-system gpu +``` + +### Inside the Container + +Configure NVIDIA driver version pinning and install drivers: + +1. **Pin NVIDIA driver versions** to ensure stability: + +```bash +cat > /etc/apt/preferences.d/nvidia-drivers << 'EOF' +Package: *nvidia* +Pin: version 560.35.05-1 +Pin-Priority: 1001 + +Package: cuda-drivers* +Pin: version 560.35.05-1 +Pin-Priority: 1001 + +Package: libcuda* +Pin: version 560.35.05-1 +Pin-Priority: 1001 + +Package: libxnvctrl* +Pin: version 560.35.05-1 +Pin-Priority: 1001 + +Package: libnv* +Pin: version 560.35.05-1 +Pin-Priority: 1001 +EOF +``` + +2. **Install NVIDIA drivers and CUDA toolkit:** + +```bash +# Update package lists +apt update + +# Install NVIDIA driver and nvidia-smi +apt install -y nvidia-driver nvidia-smi + +# Add CUDA repository +wget https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/cuda-keyring_1.1-1_all.deb +dpkg -i cuda-keyring_1.1-1_all.deb + +# Install CUDA toolkit +apt-get update +apt-get -y install cuda-toolkit-12-8 +apt-get install -y cuda-drivers +``` + +## Verify GPU Access + +After installation, verify GPU is accessible: + +```bash +# Check GPU is visible +nvidia-smi + +# Should show your GPU with driver version 560.35.05 +``` + +## Configure BotServer for GPU + +Update your bot's `config.csv` to use GPU acceleration: + +```csv +name,value +llm-server-gpu-layers,35 +``` + +The number of layers depends on your GPU memory: +- **RTX 3060 (12GB):** 20-35 layers +- **RTX 3070 (8GB):** 15-25 layers +- **RTX 4070 (12GB):** 30-40 layers +- **RTX 4090 (24GB):** 50-99 layers + +## Troubleshooting + +### GPU Not Detected + +If `nvidia-smi` doesn't show the GPU: + +1. Check host GPU drivers: + ```bash + # On host + nvidia-smi + lxc config device list gb-system + ``` + +2. Verify GPU passthrough: + ```bash + # Inside container + ls -la /dev/nvidia* + ``` + +3. Check kernel modules: + ```bash + lsmod | grep nvidia + ``` + +### Driver Version Mismatch + +If you encounter driver version conflicts: + +1. Ensure host and container use the same driver version +2. Remove the version pinning file and install matching drivers: + ```bash + rm /etc/apt/preferences.d/nvidia-drivers + apt update + apt install nvidia-driver-560 + ``` + +### CUDA Library Issues + +If CUDA libraries aren't found: + +```bash +# Add CUDA to library path +echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf.d/cuda.conf +ldconfig + +# Add to PATH +echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc +source ~/.bashrc +``` + +## Custom llama.cpp Compilation + +If you need custom CPU/GPU optimizations or specific hardware support, compile llama.cpp from source: + +### Prerequisites + +```bash +sudo apt update +sudo apt install build-essential cmake git +``` + +### Compilation Steps + +```bash +# Clone llama.cpp repository +git clone https://github.com/ggerganov/llama.cpp +cd llama.cpp + +# Create build directory +mkdir build +cd build + +# Configure with CUDA support +cmake .. -DLLAMA_CUDA=ON -DLLAMA_CURL=OFF + +# Compile using all available cores +make -j$(nproc) +``` + +### Compilation Options + +For different hardware configurations: + +```bash +# CPU-only build (no GPU) +cmake .. -DLLAMA_CURL=OFF + +# CUDA with specific compute capability +cmake .. -DLLAMA_CUDA=ON -DLLAMA_CUDA_FORCE_COMPUTE=75 + +# ROCm for AMD GPUs +cmake .. -DLLAMA_HIPBLAS=ON + +# Metal for Apple Silicon +cmake .. -DLLAMA_METAL=ON + +# AVX2 optimizations for modern CPUs +cmake .. -DLLAMA_AVX2=ON + +# F16C for half-precision support +cmake .. -DLLAMA_F16C=ON +``` + +### After Compilation + +```bash +# Copy compiled binary to BotServer +cp bin/llama-server /path/to/botserver-stack/bin/llm/ + +# Update config.csv to use custom build +llm-server-path,/path/to/botserver-stack/bin/llm/ +``` + +### Benefits of Custom Compilation + +- **Hardware-specific optimizations** for your exact CPU/GPU +- **Custom CUDA compute capabilities** for newer GPUs +- **AVX/AVX2/AVX512** instructions for faster CPU inference +- **Reduced binary size** by excluding unused features +- **Support for experimental features** not in releases + +## Performance Optimization + +### Memory Settings + +For optimal LLM performance with GPU: + +```csv +name,value +llm-server-gpu-layers,35 +llm-server-mlock,true +llm-server-no-mmap,false +llm-server-ctx-size,4096 +``` + +### Multiple GPUs + +For systems with multiple GPUs, specify which GPU to use: + +```bash +# List available GPUs +lxc profile device add gpu gpu0 gpu gputype=physical id=0 +lxc profile device add gpu gpu1 gpu gputype=physical id=1 +``` + +## Benefits of GPU Acceleration + +With GPU acceleration enabled: +- **5-10x faster** inference compared to CPU +- **Higher context sizes** possible (8K-32K tokens) +- **Real-time responses** even with large models +- **Lower CPU usage** for other tasks +- **Support for larger models** (13B, 30B parameters) + +## Next Steps + +- [Installation Guide](./installation.md) - Complete BotServer setup +- [Quick Start](./quick-start.md) - Create your first bot +- [Configuration Reference](../chapter-02/gbot.md) - All GPU-related parameters \ No newline at end of file diff --git a/docs/src/chapter-01/overview.md b/docs/src/chapter-01/overview.md index c4721b80c..fd11d0670 100644 --- a/docs/src/chapter-01/overview.md +++ b/docs/src/chapter-01/overview.md @@ -58,7 +58,6 @@ BotServer uses a modular architecture with these core components: - Web chat interface - WhatsApp Business API - Microsoft Teams -- Slack - Email - SMS (via providers) @@ -73,34 +72,27 @@ BotServer uses a modular architecture with these core components: ### Minimum Requirements - 4GB RAM -- 2 CPU cores +- 1 CPU core (development/testing) - 10GB disk space - Linux, macOS, or Windows ### Recommended for Production - 16GB RAM -- 4+ CPU cores +- 2+ CPU cores - 100GB SSD storage - Linux server (Ubuntu/Debian preferred) +- GPU: RTX 3060 or better (12GB VRAM minimum) for local LLM hosting ## Configuration -BotServer uses only two environment variables: +Bot configuration is managed through `config.csv` files with parameters like: +- `server_host`, `server_port` - Web server settings +- `llm-url`, `llm-model` - LLM configuration +- `email-from`, `email-server` - Email settings +- `theme-color1`, `theme-color2`, `theme-title`, `theme-logo` - UI customization +- `prompt-history`, `prompt-compact` - Conversation settings -```bash -# Database connection -DATABASE_URL=postgres://user:pass@localhost:5432/botserver - -# Object storage -DRIVE_SERVER=http://localhost:9000 -DRIVE_ACCESSKEY=accesskey -DRIVE_SECRET=secretkey -``` - -All other configuration is managed through: -- `config.csv` files in bot packages -- Database configuration tables -- Command-line arguments +See actual config.csv files in bot packages for available parameters. ## Bot Package Structure @@ -127,11 +119,11 @@ Single instance serving multiple bots: - Shared resources - Best for small to medium deployments -### Containerized -Using Docker/Kubernetes: -- Isolated environments -- Easy scaling -- Cloud-native deployment +### LXC Containers +Using Linux containers for isolation: +- Lightweight virtualization +- Resource isolation +- Easy management ### Embedded Integrated into existing applications: @@ -148,15 +140,19 @@ Integrated into existing applications: ``` 2. **Bootstrap Components** - ```bash - # Automatic setup - botserver bootstrap - ``` + The bootstrap automatically downloads everything to `botserver-stack/`: + - Database binaries + - Object storage server + - Cache server + - LLM runtime + - Required dependencies 3. **Deploy a Bot** + Create a new bucket in object storage: ```bash - # Copy template - cp -r templates/default.gbai work/mybot.gbai + # Each bot gets its own storage bucket + # Bots are deployed to the drive, not work folder + # The work/ folder is internal (see .gbapp chapter) ``` 4. **Access Web Interface** @@ -190,15 +186,6 @@ Integrated into existing applications: - Medication reminders - Patient education -## Performance Characteristics - -- **Concurrent Users**: 1000+ per instance -- **Message Throughput**: 100+ msg/sec -- **Response Time**: < 200ms (without LLM) -- **LLM Response**: 1-5 seconds (varies by model) -- **Memory Usage**: 500MB base + 100MB per active bot -- **Storage**: 1GB per 100,000 conversations - ## Security Features - Authentication via directory service @@ -232,16 +219,6 @@ Integrated into existing applications: ## Extensibility -### Custom Keywords -Add new BASIC keywords in Rust: -```rust -pub fn my_keyword(engine: &mut Engine) { - engine.register_fn("MY_KEYWORD", |param: String| { - // Implementation - }); -} -``` - ### Channel Adapters Implement new messaging channels: - WebSocket protocol @@ -265,29 +242,13 @@ Implement new messaging channels: - Example bots in `templates/` - Test suites - Migration tools -- Performance benchmarks ### Contributing -- Open source (MIT License) +- Open source (AGPL - GNU Affero General Public License) - GitHub repository - Issue tracking - Pull requests welcome -## Roadmap - -### Current Focus -- Stability and performance -- Documentation completeness -- Test coverage -- Community building - -### Future Plans -- Advanced LLM features -- More channel integrations -- Visual dialog editor -- Analytics dashboard -- Marketplace for bot packages - ## Summary BotServer provides a complete platform for building conversational AI applications. With its simple BASIC scripting, automatic setup, and enterprise features, it bridges the gap between simple chatbots and complex AI systems. diff --git a/docs/src/chapter-01/quick-start.md b/docs/src/chapter-01/quick-start.md index 23c489560..a9046abb9 100644 --- a/docs/src/chapter-01/quick-start.md +++ b/docs/src/chapter-01/quick-start.md @@ -21,7 +21,7 @@ You'll see: βœ“ Database created βœ“ Schema initialized βœ“ Credentials saved to .env -πŸ“¦ Installing MinIO... +πŸ“¦ Installing Drive... βœ“ Object storage ready βœ“ Buckets created πŸ“¦ Installing Valkey... @@ -47,16 +47,28 @@ Start chatting with your bot! The **automatic bootstrap** process: 1. βœ… Detected your OS (Linux/macOS/Windows) -2. βœ… Installed PostgreSQL database -3. βœ… Installed MinIO object storage -4. βœ… Installed Valkey cache -5. βœ… Generated secure credentials β†’ `.env` +2. βœ… Downloaded PostgreSQL database to botserver-stack/ +3. βœ… Downloaded drive (S3-compatible storage) to botserver-stack/ +4. βœ… Downloaded Valkey cache to botserver-stack/ +5. βœ… Generated secure credentials β†’ `.env` (from blank environment) 6. βœ… Created database schema -7. βœ… Created default bots from `templates/` +7. βœ… Deployed default bots to object storage 8. βœ… Started web server on port 8080 **Zero manual configuration required!** +### Using Existing Services + +If you already have PostgreSQL or drive storage running, update `.env`: + +```bash +# Point to your existing services +DATABASE_URL=postgres://myuser:mypass@myhost:5432/mydb +DRIVE_SERVER=http://my-drive:9000 +DRIVE_ACCESSKEY=my-access-key +DRIVE_SECRET=my-secret-key +``` + --- ## Create Your First Tool @@ -99,27 +111,27 @@ The bot automatically: --- -## Container Mode (LXC) +## Container Deployment (LXC) -BotServer uses **LXC** (Linux Containers) for containerized deployment: +For production isolation, BotServer supports **LXC** (Linux Containers): ```bash -# Force container mode -./botserver --container +# Create container +lxc-create -n botserver -t download -- -d ubuntu -r jammy -a amd64 -# Components run in isolated LXC containers -# - PostgreSQL in {tenant}-tables container -# - MinIO in {tenant}-drive container -# - Valkey in {tenant}-cache container +# Start and attach +lxc-start -n botserver +lxc-attach -n botserver + +# Install BotServer inside container +./botserver ``` **Benefits**: -- βœ… Clean isolation - system-level containers -- βœ… Easy cleanup - `lxc delete {container}` -- βœ… No system pollution - everything in containers -- βœ… Lightweight - more efficient than VMs - -**Requires**: LXC/LXD installed (`sudo snap install lxd`) +- βœ… Process isolation +- βœ… Resource control +- βœ… Easy management +- βœ… Lightweight virtualization --- @@ -140,10 +152,10 @@ Same automatic bootstrap process! After installation, add more features: ```bash -./botserver install email # Stalwart email server -./botserver install directory # Zitadel identity provider +./botserver install email # Email server +./botserver install directory # Identity provider ./botserver install llm # Local LLM server (offline mode) -./botserver install meeting # LiveKit video conferencing +./botserver install meeting # Video conferencing ``` --- @@ -165,7 +177,31 @@ mybot.gbai/ └── custom.css ``` -Save to `templates/mybot.gbai/` and restart - bot created automatically! +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:** +```bash +# 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 --- @@ -203,9 +239,10 @@ The LLM handles ALL conversation logic automatically! ## Configuration (Optional) -Bootstrap creates `.env` automatically: +Bootstrap automatically generates `.env` from a blank environment with secure random credentials: ```env +# Auto-generated during bootstrap DATABASE_URL=postgres://gbuser:RANDOM_PASS@localhost:5432/botserver DRIVE_SERVER=http://localhost:9000 DRIVE_ACCESSKEY=GENERATED_KEY @@ -239,16 +276,17 @@ server_port,3000 ```bash # Remove everything and start fresh -rm -rf /opt/gbo # Linux/macOS -./botserver +rm -rf botserver-stack/ +rm .env +./botserver # Will regenerate everything ``` ### Check component status ```bash ./botserver status tables # PostgreSQL -./botserver status drive # MinIO -./botserver status cache # Valkey +./botserver status drive # Drive storage +./botserver status cache # Valkey cache ``` --- diff --git a/docs/src/chapter-01/sessions.md b/docs/src/chapter-01/sessions.md index 253ca50ee..4c7e90668 100644 --- a/docs/src/chapter-01/sessions.md +++ b/docs/src/chapter-01/sessions.md @@ -1,311 +1 @@ -# Sessions - -Understanding how BotServer manages conversational sessions is crucial for building effective bots. - -## What is a Session? - -A session represents a single conversation between a user and a bot. It maintains: -- User identity -- Conversation state -- Context and memory -- Active knowledge bases -- Loaded tools - -## Session Lifecycle - -### 1. Session Creation - -Sessions are created when: -- A user visits the web interface (cookie-based) -- A message arrives from a messaging channel -- An API call includes a new session ID - -```basic -' Sessions start automatically when user connects -' The start.bas script runs for each new session -TALK "Welcome! This is a new session." -``` - -### 2. Session Persistence - -Sessions persist: -- **Web**: Via browser cookies (30-day default) -- **WhatsApp**: Phone number as session ID -- **Teams**: User ID from Microsoft Graph -- **API**: Client-provided session token - -### 3. Session Termination - -Sessions end when: -- User explicitly ends conversation -- Timeout period expires (configurable) -- Server restarts (optional persistence) -- Memory limit reached - -## Session Storage - -### Database Tables - -Sessions use these primary tables: -- `users`: User profiles and authentication -- `user_sessions`: Active session records -- `conversations`: Message history -- `bot_memories`: Persistent bot data - -### Memory Management - -Each session maintains: -``` -Session Memory -β”œβ”€β”€ User Variables (SET/GET) -β”œβ”€β”€ Context Strings (SET CONTEXT) -β”œβ”€β”€ Active KBs (USE KB) -β”œβ”€β”€ Loaded Tools (USE TOOL) -β”œβ”€β”€ Suggestions (ADD SUGGESTION) -└── Temporary Data -``` - -## Session Variables - -### User Variables -```basic -' Set a variable for this session -SET "user_name", "John" -SET "preference", "email" - -' Retrieve variables -name = GET "user_name" -TALK "Hello, " + name -``` - -### Bot Memory -```basic -' Bot memory persists across all sessions -SET BOT MEMORY "company_name", "ACME Corp" - -' Available to all users -company = GET BOT MEMORY "company_name" -``` - -## Session Context - -Context provides information to the LLM: - -```basic -' Add context for better responses -SET CONTEXT "user_profile" AS "Premium customer since 2020" -SET CONTEXT "preferences" AS "Prefers technical documentation" - -' Context is automatically included in LLM prompts -response = LLM "What products should I recommend?" -``` - -## Multi-Channel Sessions - -### Channel Identification - -Sessions track their origin channel: -```basic -channel = GET SESSION "channel" -IF channel = "whatsapp" THEN - ' WhatsApp-specific features - ADD SUGGESTION "Call Support" AS "phone" -ELSE IF channel = "web" THEN - ' Web-specific features - SHOW IMAGE "dashboard.png" -END IF -``` - -### Channel-Specific Data - -Each channel provides different session data: - -| Channel | Session ID | User Info | Metadata | -|---------|------------|-----------|----------| -| Web | Cookie UUID | IP, Browser | Page URL | -| WhatsApp | Phone Number | Name, Profile | Message Type | -| Teams | User ID | Email, Tenant | Organization | -| Email | Email Address | Name | Subject | - -## Session Security - -### Authentication States - -Sessions can be: -- **Anonymous**: No authentication required -- **Authenticated**: User logged in via directory service -- **Elevated**: Additional verification completed - -```basic -auth_level = GET SESSION "auth_level" -IF auth_level <> "authenticated" THEN - TALK "Please log in to continue" - RUN "auth.bas" -END IF -``` - -### Session Tokens - -Secure token generation: -- UUID v4 for session IDs -- Signed JWTs for API access -- Refresh tokens for long-lived sessions - -## Session Limits - -### Resource Constraints - -| Resource | Default Limit | Configurable | -|----------|--------------|--------------| -| Memory per session | 10MB | Yes | -| Context size | 4096 tokens | Yes | -| Active KBs | 10 | Yes | -| Variables | 100 | Yes | -| Message history | 50 messages | Yes | - -### Concurrent Sessions - -- Server supports 1000+ concurrent sessions -- Database connection pooling -- Redis caching for performance -- Automatic cleanup of stale sessions - -## Session Recovery - -### Automatic Recovery - -If a session disconnects: -1. State preserved for timeout period -2. User can reconnect with same session ID -3. Conversation continues from last point - -```basic -last_message = GET SESSION "last_interaction" -IF last_message <> "" THEN - TALK "Welcome back! We were discussing: " + last_message -END IF -``` - -### Manual Save/Restore - -```basic -' Save session state -state = SAVE SESSION STATE -SET BOT MEMORY "saved_session_" + user_id, state - -' Restore later -saved = GET BOT MEMORY "saved_session_" + user_id -RESTORE SESSION STATE saved -``` - -## Session Analytics - -Track session metrics: -- Duration -- Message count -- User satisfaction -- Completion rate -- Error frequency - -```basic -' Log session events -LOG SESSION "milestone", "order_completed" -LOG SESSION "error", "payment_failed" -``` - -## Best Practices - -### 1. Session Initialization -```basic -' start.bas - Initialize every session properly -user_id = GET SESSION "user_id" -IF user_id = "" THEN - ' First time user - TALK "Welcome! Let me help you get started." - RUN "onboarding.bas" -ELSE - ' Returning user - TALK "Welcome back!" -END IF -``` - -### 2. Session Cleanup -```basic -' Clean up before session ends -ON SESSION END - CLEAR KB ALL - CLEAR SUGGESTIONS - LOG "Session ended: " + SESSION_ID -END ON -``` - -### 3. Session Handoff -```basic -' Transfer session to human agent -FUNCTION HandoffToAgent() - agent_id = GET AVAILABLE AGENT - TRANSFER SESSION agent_id - TALK "Connecting you to an agent..." -END FUNCTION -``` - -### 4. Session Persistence -```basic -' Save important data beyond session -important_data = GET "order_details" -SET BOT MEMORY "user_" + user_id + "_last_order", important_data -``` - -## Debugging Sessions - -### Session Inspection - -View session data: -```basic -' Debug session information -DEBUG SHOW SESSION -DEBUG SHOW CONTEXT -DEBUG SHOW VARIABLES -``` - -### Session Logs - -All sessions are logged: -- Start/end timestamps -- Messages exchanged -- Errors encountered -- Performance metrics - -## Advanced Session Features - -### Session Branching -```basic -' Create sub-session for specific task -sub_session = CREATE SUB SESSION -RUN IN SESSION sub_session, "specialized_task.bas" -MERGE SESSION sub_session -``` - -### Session Templates -```basic -' Apply template to session -APPLY SESSION TEMPLATE "support_agent" -' Automatically loads KBs, tools, and context -``` - -### Cross-Session Communication -```basic -' Send message to another session -SEND TO SESSION other_session_id, "Notification: Your order is ready" -``` - -## Summary - -Sessions are the foundation of conversational state in BotServer. They: -- Maintain conversation continuity -- Store user-specific data -- Manage resources efficiently -- Enable multi-channel support -- Provide security boundaries - -Understanding sessions helps you build bots that feel natural, remember context, and provide personalized experiences across any channel. \ No newline at end of file +# Understanding Sessions diff --git a/docs/src/chapter-02/README.md b/docs/src/chapter-02/README.md index 96806e2b5..f9c4c6141 100644 --- a/docs/src/chapter-02/README.md +++ b/docs/src/chapter-02/README.md @@ -8,10 +8,10 @@ BotServer uses a template-based package system to organize bot resources. Each b |-----------|-----------|------| | Application Interface | `.gbai` | Root directory container for all bot resources | | Dialog scripts | `.gbdialog` | BASIC-style conversational logic (`.bas` files) | -| Knowledge bases | `.gbkb` | Document collections for semantic search | +| Knowledge bases | `.gbkb` | Document collections for semantic search (each folder is a collection for LLM/vector DB) | | Bot configuration | `.gbot` | CSV configuration file (`config.csv`) | -| UI themes | `.gbtheme` | CSS/HTML assets for web interface customization | -| File storage | `.gbdrive` | Object storage integration (MinIO/S3) | +| UI themes | `.gbtheme` | Simple CSS theming - just place a `default.css` file | +| File storage | `.gbdrive` | General file storage for bot data (not KB) - used by SEND FILE, GET, SAVE AS | ## How Packages Work @@ -22,7 +22,7 @@ BotServer uses a template-based approach: 1. **Templates Directory**: Bot packages are stored in `templates/` as `.gbai` folders 2. **Auto-Discovery**: During bootstrap, the system scans for `.gbai` directories 3. **Bot Creation**: Each `.gbai` package automatically creates a bot instance -4. **Storage Upload**: Template files are uploaded to MinIO for persistence +4. **Storage Upload**: Template files are uploaded to object storage for persistence 5. **Runtime Loading**: Bots load their resources from storage when serving requests ### Package Structure @@ -35,35 +35,24 @@ botname.gbai/ β”‚ β”œβ”€β”€ start.bas # Entry point script β”‚ β”œβ”€β”€ auth.bas # Authentication flow β”‚ └── *.bas # Other dialog scripts -β”œβ”€β”€ botname.gbkb/ # Knowledge base -β”‚ β”œβ”€β”€ collection1/ # Document collection -β”‚ └── collection2/ # Another collection +β”œβ”€β”€ botname.gbkb/ # Knowledge base for LLM +β”‚ β”œβ”€β”€ collection1/ # Document collection (USE KB "collection1") +β”‚ └── collection2/ # Another collection (USE KB "collection2") +β”œβ”€β”€ botname.gbdrive/ # File storage (not KB) +β”‚ β”œβ”€β”€ uploads/ # User uploaded files +β”‚ β”œβ”€β”€ exports/ # Generated files (SAVE AS) +β”‚ └── templates/ # File templates β”œβ”€β”€ botname.gbot/ # Configuration β”‚ └── config.csv # Bot parameters └── botname.gbtheme/ # UI theme (optional) - β”œβ”€β”€ css/ - β”œβ”€β”€ html/ - └── assets/ + └── default.css # Theme CSS (CHANGE THEME "default") ``` ## Included Templates -BotServer ships with two example templates: +BotServer includes 21 pre-built templates for various use cases: business bots (CRM, ERP, BI), communication (announcements, WhatsApp), AI tools (search, LLM utilities), and industry-specific solutions (education, legal, e-commerce). -### default.gbai - -A minimal bot with basic configuration: -- Includes only `default.gbot/config.csv` -- Suitable starting point for new bots -- Demonstrates core configuration parameters - -### announcements.gbai - -A complete example bot showcasing all features: -- **Dialogs**: Multiple `.bas` scripts demonstrating conversation flows -- **Knowledge Base**: Three collections (auxiliom, news, toolbix) -- **Configuration**: Full configuration with LLM, email, and database settings -- **Features**: Context management, suggestions, memory retrieval +See [Template Reference](./templates.md) for the complete catalog and detailed descriptions. ## Creating Your Own Package @@ -95,7 +84,7 @@ To create a new bot package: Development β†’ Bootstrap β†’ Storage β†’ Runtime β†’ Updates ↓ ↓ ↓ ↓ ↓ Edit files Scan .gbai Upload Load from Modify & - in templates folders to MinIO storage restart + in templates folders to drive storage restart ``` ### Development Phase @@ -113,9 +102,9 @@ Development β†’ Bootstrap β†’ Storage β†’ Runtime β†’ Updates ### Storage Phase -- Uploads all template files to MinIO (S3-compatible storage) -- Indexes documents into Qdrant vector database -- Stores configuration in PostgreSQL +- Uploads all template files to object storage (drive) +- Indexes documents into vector database +- Stores configuration in database - Ensures persistence across restarts ### Runtime Phase @@ -123,7 +112,7 @@ Development β†’ Bootstrap β†’ Storage β†’ Runtime β†’ Updates - Bots load dialogs on-demand from storage - Configuration is read from database - Knowledge base queries hit vector database -- Session state maintained in Redis cache +- Session state maintained in cache ### Update Phase @@ -145,10 +134,10 @@ A single BotServer instance can host multiple bots: After bootstrap, package data is distributed across services: -- **PostgreSQL**: Bot metadata, users, sessions, configuration -- **MinIO/S3**: Template files, uploaded documents, assets -- **Qdrant**: Vector embeddings for semantic search -- **Redis/Valkey**: Session cache, temporary data +- **Database**: Bot metadata, users, sessions, configuration +- **Object Storage (Drive)**: Template files, uploaded documents, assets +- **Vector Database**: Embeddings for semantic search +- **Cache**: Session cache, temporary data - **File System**: Optional local caching ## Best Practices @@ -182,10 +171,12 @@ After bootstrap, package data is distributed across services: ### Version Control -- Commit entire `.gbai` packages to Git -- Use `.gitignore` for generated files -- Tag releases for production deployments -- Document changes in commit messages +- Packages are versioned in object storage with built-in versioning +- The drive automatically maintains version history +- For larger projects with split BASIC/LLM development teams: + - Use Git to track source changes + - Coordinate between dialog scripting and prompt engineering +- Storage versioning handles production deployments ## Package Component Details @@ -195,18 +186,27 @@ For detailed information about each package type: - **[.gbdialog Dialogs](./gbdialog.md)** - BASIC scripting and conversation flows - **[.gbkb Knowledge Base](./gbkb.md)** - Document indexing and semantic search - **[.gbot Bot Configuration](./gbot.md)** - Configuration parameters and settings -- **[.gbtheme UI Theming](./gbtheme.md)** - Web interface customization -- **[.gbdrive File Storage](./gbdrive.md)** - MinIO/S3 object storage integration +- **[.gbtheme UI Theming](./gbtheme.md)** - Simple CSS theming +- **[.gbdrive File Storage](./gbdrive.md)** - General file storage (not KB) ## Migration from Other Platforms -If you're migrating from other bot platforms: +When migrating from traditional bot platforms, the key is to **let go** of complex logic: -- **Dialog Flows**: Convert to BASIC scripts in `.gbdialog/` -- **Intents/Entities**: Use LLM-based understanding instead -- **Knowledge Base**: Import documents into `.gbkb/` collections -- **Configuration**: Map settings to `config.csv` parameters -- **Custom Code**: Implement as Rust keywords or external tools +- **Dialog Flows**: Use minimal BASIC scripts - let the LLM handle conversation flow +- **Intents/Entities**: Remove entirely - LLM understands naturally +- **State Machines**: Eliminate - LLM maintains context automatically +- **Knowledge Base**: Simply drop documents into `.gbkb/` folders +- **Complex Rules**: Replace with LLM intelligence + +The migration philosophy is to "open hand" (abrir mΓ£o) - release control and trust the LLM. Instead of converting every dialog branch and condition, use the minimum BASIC needed for tools and let the LLM do the heavy lifting. This results in simpler, more maintainable, and more natural conversations. + +Example: Instead of 100 lines of intent matching and routing, just: +```basic +' Let LLM understand and respond naturally +answer = LLM "Help the user with their request" +TALK answer +``` ## Troubleshooting @@ -227,7 +227,7 @@ If you're migrating from other bot platforms: ### Knowledge Base Not Indexed - Ensure `.gbkb/` contains subdirectories with documents -- Check Qdrant is running and accessible +- Check vector database is running and accessible - Verify embedding model is configured - Review indexing logs for errors diff --git a/docs/src/chapter-02/gbai.md b/docs/src/chapter-02/gbai.md index 27016704a..6eca2ef2f 100644 --- a/docs/src/chapter-02/gbai.md +++ b/docs/src/chapter-02/gbai.md @@ -28,7 +28,7 @@ my-bot.gbai/ ## Included Templates -BotServer includes two template `.gbai` packages: +BotServer includes 21 template `.gbai` packages in the `/templates` directory: ### default.gbai @@ -55,7 +55,7 @@ A feature-rich example bot: Contains BASIC-like scripts (`.bas` files) that define conversation logic: - Simple English-like syntax -- Custom keywords: `TALK`, `HEAR`, `LLM`, `GET_BOT_MEMORY`, `SET_CONTEXT` +- Custom keywords: `TALK`, `HEAR`, `LLM`, `GET BOT MEMORY`, `SET CONTEXT` - Control flow and variables - Tool integration @@ -104,9 +104,9 @@ During the Auto Bootstrap process: - Folder name `default.gbai` β†’ Bot name "Default" - Folder name `announcements.gbai` β†’ Bot name "Announcements" 3. **Configuration Loading**: Bot configuration from `.gbot/config.csv` is loaded -4. **Template Upload**: All template files are uploaded to MinIO storage +4. **Template Upload**: All template files are uploaded to object storage (drive) 5. **Dialog Loading**: BASIC scripts from `.gbdialog` are loaded and ready to execute -6. **KB Indexing**: Documents from `.gbkb` are indexed into Qdrant vector database +6. **KB Indexing**: Documents from `.gbkb` are indexed into vector database ## Creating Custom .gbai Packages @@ -152,7 +152,7 @@ To create a custom bot: 1. **Development**: Edit files in `templates/your-bot.gbai/` 2. **Bootstrap**: System creates bot from template -3. **Storage**: Files uploaded to MinIO for persistence +3. **Storage**: Files uploaded to object storage for persistence 4. **Runtime**: Bot loads dialogs and configuration from storage 5. **Updates**: Modify template files and restart to apply changes @@ -167,10 +167,10 @@ A single BotServer instance can host multiple bots: ## Package Storage After bootstrap, packages are stored in: -- **MinIO/S3**: Template files and assets -- **PostgreSQL**: Bot metadata and configuration -- **Qdrant**: Vector embeddings from knowledge bases -- **Redis**: Session and cache data +- **Object Storage**: Template files and assets +- **Database**: Bot metadata and configuration +- **Vector Database**: Embeddings from knowledge bases +- **Cache**: Session and cache data ## Naming Conventions diff --git a/docs/src/chapter-02/gbdialog.md b/docs/src/chapter-02/gbdialog.md index 9e1516ad1..3aff9cbc8 100644 --- a/docs/src/chapter-02/gbdialog.md +++ b/docs/src/chapter-02/gbdialog.md @@ -5,63 +5,252 @@ The `.gbdialog` package contains BASIC scripts that define conversation flows, t ## What is .gbdialog? `.gbdialog` files are written in a specialized BASIC dialect that controls: -- Conversation flow and logic -- Tool calls and integrations -- User input processing -- Context management -- Response generation +- Tool execution and integrations +- LLM prompting and context +- Knowledge base activation +- Session and memory management +- External API calls -## Basic Structure +## Modern Approach: Let the LLM Work +### Minimal BASIC Philosophy -A typical `.gbdialog` script contains: +Instead of complex logic, use the LLM's natural understanding: ```basic -REM This is a comment -TALK "Hello! How can I help you today?" +' 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 +SET BOT MEMORY "resume", resume -HEAR user_input - -IF user_input = "help" THEN - TALK "I can help you with various tasks..." -ELSE - LLM user_input -END IF +' 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. Control Flow -- `IF/THEN/ELSE/END IF` for conditional logic -- `FOR EACH/IN/NEXT` for loops -- `EXIT FOR` to break loops +### 1. LLM Integration +```basic +' Direct LLM usage for natural conversation +response = LLM "Help the user with their question" +TALK response -### 2. User Interaction -- `HEAR variable` to get user input -- `TALK message` to send responses -- `WAIT seconds` to pause execution +' Context-aware responses +SET CONTEXT "user_type" AS "premium customer" +answer = LLM "Provide personalized recommendations" +TALK answer +``` -### 3. Data Manipulation -- `SET variable = value` for assignment -- `GET url` to fetch external data -- `FIND table, filter` to query databases +### 2. Tool Execution +```basic +' Define tools with parameters +PARAM name AS string LIKE "John Smith" DESCRIPTION "Customer name" +PARAM email AS string LIKE "john@example.com" DESCRIPTION "Email" -### 4. AI Integration -- `LLM prompt` for AI-generated responses -- `USE_TOOL tool_name` to enable functionality -- `USE_KB collection` to use knowledge bases +' LLM automatically knows when to call this +SAVE "customers.csv", name, email +TALK "Registration complete!" +``` -## Script Execution +### 3. Knowledge Base Usage +```basic +' Activate knowledge base collections +USE KB "products" +USE KB "policies" -Dialog scripts run in a sandboxed environment with: -- Access to session context and variables -- Ability to call external tools and APIs -- Integration with knowledge bases -- LLM generation capabilities +' LLM searches these automatically when answering +answer = LLM "Answer based on our product catalog and policies" +TALK answer +``` + +### 4. Session Management +```basic +' Store session data +SET "user_name", name +SET "preferences", "email notifications" + +' Retrieve later +saved_name = GET "user_name" +TALK "Welcome back, " + saved_name +``` + +## Script Structure + +### Entry Point: start.bas +Every bot needs a `start.bas` file: + +```basic +' Minimal start script - let LLM handle everything +USE KB "company_docs" +response = LLM "Welcome the user and offer assistance" +TALK response +``` + +### Tool Definitions +Create separate `.bas` files for each tool: + +```basic +' 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 +```basic +' Good - Let LLM handle the conversation +answer = LLM "Process the user's request appropriately" +TALK answer + +' Avoid - Don't micromanage the flow +' IF user_says_this THEN do_that... +``` + +### 2. Clear Tool Descriptions +```basic +DESCRIPTION "This tool books appointments for customers" +' The LLM uses this description to know when to call the tool +``` + +### 3. Context Over Conditions +```basic +' Provide context, not rules +SET CONTEXT "business_hours" AS "9AM-5PM weekdays" +response = LLM "Inform about availability" +' LLM naturally understands to mention hours when relevant +``` + +### 4. Trust the LLM +```basic +' Simple prompt, sophisticated behavior +answer = LLM "Be a helpful customer service agent" +' LLM handles greetings, questions, complaints naturally +``` + +## Common Patterns + +### Document Summarization (from announcements.gbai) +```basic +' Schedule automatic updates +SET SCHEDULE "59 * * * *" + +' Fetch and summarize documents +let text = GET "announcements.gbkb/news/news.pdf" +let resume = LLM "In a few words, resume this: " + text +SET BOT MEMORY "resume", resume +``` + +### Interactive Case Analysis (from law.gbai) +```basic +' Ask for case number +TALK "What is the case number?" +HEAR cod + +' Load case document +text = GET "case-" + cod + ".pdf" + +IF text THEN + ' Set context for LLM to use + 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 +```basic +' 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 +```basic +USE KB "products" +USE KB "reviews" +USE KB "specifications" + +answer = LLM "Answer product questions comprehensively" +TALK answer +``` + +## Advanced Features + +### Memory Management +```basic +SET BOT MEMORY "company_policy", policy_text +' Available across all sessions + +retrieved = GET BOT MEMORY "company_policy" +``` + +### External APIs +```basic +result = GET "https://api.example.com/data" +response = LLM "Interpret this data: " + result +TALK response +``` + +### Suggestions +```basic +ADD SUGGESTION "Schedule Meeting" AS "schedule" +ADD SUGGESTION "View Products" AS "products" +' UI shows these as quick actions +``` ## Error Handling -The system provides built-in error handling: -- Syntax errors are caught during compilation -- Runtime errors log details but don't crash the bot -- Timeouts prevent infinite loops -- Resource limits prevent abuse +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 + +## 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) + +## Migration from Traditional Bots + +### Old Way (Complex Logic) +```basic +' 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 (LLM Intelligence) +```basic +' DO THIS - Let LLM understand naturally +response = LLM "Handle the customer's order request" +TALK response +' LLM understands context and intent automatically +``` + +The key is to **trust the LLM** and write less code for more intelligent behavior. \ No newline at end of file diff --git a/docs/src/chapter-02/gbdrive.md b/docs/src/chapter-02/gbdrive.md index 0e2647955..35301ba9e 100644 --- a/docs/src/chapter-02/gbdrive.md +++ b/docs/src/chapter-02/gbdrive.md @@ -1,6 +1,6 @@ # .gbdrive File Storage -The `.gbdrive` system manages file storage and retrieval using MinIO (S3-compatible object storage). +The `.gbdrive` system manages file storage and retrieval using object storage (S3-compatible drive). ## What is .gbdrive? @@ -33,7 +33,7 @@ org-prefixbot-name.gbai/ ### Uploading Files ```basic REM Files can be uploaded via API or interface -REM They are stored in the bot's MinIO bucket +REM They are stored in the bot's storage bucket ``` ### Retrieving Files @@ -78,8 +78,7 @@ Files have different access levels: ## Storage Backends -Supported storage options: -- **MinIO** (default): Self-hosted S3-compatible +- **Object Storage** (default): Self-hosted S3-compatible drive - **AWS S3**: Cloud object storage - **Local filesystem**: Development and testing - **Hybrid**: Multiple backends with fallback diff --git a/docs/src/chapter-02/gbkb.md b/docs/src/chapter-02/gbkb.md index eaad91bed..0b3d1a66f 100644 --- a/docs/src/chapter-02/gbkb.md +++ b/docs/src/chapter-02/gbkb.md @@ -45,21 +45,21 @@ Each document is processed into vector embeddings using: ### Creating Collections ```basic -USE_KB "company-policies" -ADD_WEBSITE "https://company.com/docs" +USE KB "company-policies" +ADD WEBSITE "https://company.com/docs" ``` ### Using Collections ```basic -USE_KB "company-policies" +USE KB "company-policies" LLM "What is the vacation policy?" ``` ### Multiple Collections ```basic -USE_KB "policies" -USE_KB "procedures" -USE_KB "faqs" +USE KB "policies" +USE KB "procedures" +USE KB "faqs" REM All active collections contribute to context ``` @@ -74,6 +74,6 @@ The knowledge base provides: ## Integration with Dialogs Knowledge bases are automatically used when: -- `USE_KB` is called +- `USE KB` is called - Answer mode is set to use documents - LLM queries benefit from contextual information diff --git a/docs/src/chapter-02/gbot.md b/docs/src/chapter-02/gbot.md index ff1548ce9..fedb5149b 100644 --- a/docs/src/chapter-02/gbot.md +++ b/docs/src/chapter-02/gbot.md @@ -7,8 +7,8 @@ The `.gbot` package contains configuration files that define bot behavior, param `.gbot` files configure: - Bot identity and description - LLM provider settings -- Answer modes and behavior - Context management +- Bot behavior settings - Integration parameters ## Configuration Structure @@ -19,7 +19,6 @@ The primary configuration file is `config.csv`: key,value bot_name,Customer Support Assistant bot_description,AI-powered support agent -answer_mode,1 llm_provider,openai llm_model,gpt-4 temperature,0.7 @@ -73,10 +72,10 @@ Settings are applied in this order (later overrides earlier): Some settings can be changed at runtime: ```basic -REM Change answer mode dynamically -SET_BOT_MEMORY "answer_mode", "2" +REM Store configuration dynamically +SET BOT MEMORY "preferred_style", "detailed" ``` ## Bot Memory -The `SET_BOT_MEMORY` and `GET_BOT_MEMORY` keywords allow storing and retrieving bot-specific data that persists across sessions. +The `SET BOT MEMORY` and `GET BOT MEMORY` keywords allow storing and retrieving bot-specific data that persists across sessions. diff --git a/docs/src/chapter-02/gbtheme.md b/docs/src/chapter-02/gbtheme.md index f3ca51a6c..9f7b2b40c 100644 --- a/docs/src/chapter-02/gbtheme.md +++ b/docs/src/chapter-02/gbtheme.md @@ -1,95 +1,184 @@ # .gbtheme UI Theming -The `.gbtheme` package contains user interface customization files for web and other frontend interfaces. +The `.gbtheme` package provides simple CSS-based theming for the bot's web interface. ## What is .gbtheme? -`.gbtheme` defines the visual appearance and user experience: -- CSS stylesheets for styling -- HTML templates for structure -- JavaScript for interactivity -- Assets like images and fonts +`.gbtheme` is a simplified theming system that uses CSS files to customize the bot's appearance. No complex HTML templates or JavaScript required - just CSS. ## Theme Structure -A typical theme package contains: +A theme is simply one or more CSS files in the `.gbtheme` folder: ``` -theme-name.gbtheme/ -β”œβ”€β”€ web/ -β”‚ β”œβ”€β”€ index.html # Main template -β”‚ β”œβ”€β”€ chat.html # Chat interface -β”‚ └── login.html # Authentication -β”œβ”€β”€ css/ -β”‚ β”œβ”€β”€ main.css # Primary styles -β”‚ β”œβ”€β”€ components.css # UI components -β”‚ └── responsive.css # Mobile styles -β”œβ”€β”€ js/ -β”‚ β”œβ”€β”€ app.js # Application logic -β”‚ └── websocket.js # Real-time communication -└── assets/ - β”œβ”€β”€ images/ - β”œβ”€β”€ fonts/ - └── icons/ +botname.gbtheme/ +└── default.css # Main theme file +└── dark.css # Alternative theme +└── holiday.css # Seasonal theme ``` -## Web Interface +## Using Themes -The main web interface consists of: +### Default Theme -### HTML Templates -- `index.html`: Primary application shell -- `chat.html`: Conversation interface -- Component templates for reusable UI - -### CSS Styling -- Color schemes and typography -- Layout and responsive design -- Animation and transitions -- Dark/light mode support - -### JavaScript -- WebSocket communication -- UI state management -- Event handling -- API integration - -## Theme Variables - -Themes can use CSS custom properties for easy customization: +Place a `default.css` file in your `.gbtheme` folder: ```css +/* default.css */ :root { - --primary-color: #2563eb; - --secondary-color: #64748b; - --background-color: #ffffff; - --text-color: #1e293b; - --border-radius: 8px; - --spacing-unit: 8px; + --primary-color: #0d2b55; + --secondary-color: #fff9c2; + --background: #ffffff; + --text-color: #333333; + --font-family: 'Inter', sans-serif; +} + +.chat-container { + background: var(--background); + color: var(--text-color); +} + +.bot-message { + background: var(--primary-color); + color: white; +} + +.user-message { + background: var(--secondary-color); + color: var(--text-color); } ``` -## Responsive Design +### Changing Themes Dynamically -Themes should support: -- **Desktop**: Full-featured interface -- **Tablet**: Adapted layout and interactions -- **Mobile**: Touch-optimized experience -- **Accessibility**: Screen reader and keyboard support +Use the BASIC keyword to switch themes at runtime: -## Theme Switching +```basic +' Switch to dark theme +CHANGE THEME "dark" -Multiple themes can be provided: -- Light and dark variants -- High contrast for accessibility -- Brand-specific themes -- User-selected preferences +' Switch back to default +CHANGE THEME "default" -## Customization Points +' Seasonal theme +IF month = 12 THEN + CHANGE THEME "holiday" +END IF +``` -Key areas for theme customization: -- Color scheme and branding -- Layout and component arrangement -- Typography and spacing -- Animation and micro-interactions -- Iconography and imagery +## CSS Variables + +The bot interface uses CSS custom properties that themes can override: + +| Variable | Description | Default | +|----------|-------------|---------| +| `--primary-color` | Main brand color | `#0d2b55` | +| `--secondary-color` | Accent color | `#fff9c2` | +| `--background` | Page background | `#ffffff` | +| `--text-color` | Main text | `#333333` | +| `--font-family` | Typography | `system-ui` | +| `--border-radius` | Element corners | `8px` | +| `--spacing` | Base spacing unit | `16px` | +| `--shadow` | Box shadows | `0 2px 4px rgba(0,0,0,0.1)` | + +## Simple Examples + +### Minimal Theme + +```css +/* minimal.css */ +:root { + --primary-color: #000000; + --secondary-color: #ffffff; +} +``` + +### Corporate Theme + +```css +/* corporate.css */ +:root { + --primary-color: #1e3a8a; + --secondary-color: #f59e0b; + --background: #f8fafc; + --text-color: #1e293b; + --font-family: 'Roboto', sans-serif; + --border-radius: 4px; +} +``` + +### Dark Theme + +```css +/* dark.css */ +:root { + --primary-color: #60a5fa; + --secondary-color: #34d399; + --background: #0f172a; + --text-color: #e2e8f0; +} + +body { + background: var(--background); + color: var(--text-color); +} +``` + +## Best Practices + +1. **Keep it simple** - Just override CSS variables +2. **Use one file** - Start with a single `default.css` +3. **Test contrast** - Ensure text is readable +4. **Mobile-first** - Design for small screens +5. **Performance** - Keep file size small + +## Theme Switching in Scripts + +```basic +' User preference +preference = GET USER "theme_preference" +IF preference <> "" THEN + CHANGE THEME preference +END IF + +' Time-based themes +hour = GET TIME "hour" +IF hour >= 18 OR hour < 6 THEN + CHANGE THEME "dark" +ELSE + CHANGE THEME "default" +END IF +``` + +## Integration with config.csv + +You can set the default theme in your bot's configuration: + +```csv +name,value +theme,default +theme-color1,#0d2b55 +theme-color2,#fff9c2 +``` + +These values are available as CSS variables but the `.css` file takes precedence. + +## No Build Process Required + +Unlike complex theming systems, `.gbtheme`: +- No webpack or build tools +- No preprocessors needed +- No template engines +- Just plain CSS files +- Hot reload on change + +## Migration from Complex Themes + +If migrating from a complex theme system: + +1. **Extract colors** - Find your brand colors +2. **Create CSS** - Map to CSS variables +3. **Test interface** - Verify appearance +4. **Remove complexity** - Delete unused assets + +The bot's default UI handles layout and functionality - themes just customize appearance. \ No newline at end of file diff --git a/docs/src/chapter-02/summary.md b/docs/src/chapter-02/summary.md index 2d1e90c21..4aa7e8e86 100644 --- a/docs/src/chapter-02/summary.md +++ b/docs/src/chapter-02/summary.md @@ -6,10 +6,10 @@ This chapter provides a concise overview of the GeneralBots package types introd |---------|------|-------------| | **.gbai** | [gbai.md](gbai.md) | Defines the overall application architecture, metadata, and package hierarchy. | | **.gbdialog** | [gbdialog.md](gbdialog.md) | Contains BASIC‑style dialog scripts that drive conversation flow and tool integration. | -| **.gbdrive** | [gbdrive.md](gbdrive.md) | Manages file storage and retrieval via MinIO (or other S3‑compatible backends). | +| **.gbdrive** | [gbdrive.md](gbdrive.md) | Manages file storage and retrieval via object storage (S3‑compatible drive). | | **.gbkb** | [gbkb.md](gbkb.md) | Handles knowledge‑base collections, vector embeddings, and semantic search. | -| **.gbot** | [gbot.md](gbot.md) | Stores bot configuration (CSV) for identity, LLM settings, answer modes, and runtime parameters. | -| **.gbtheme** | [gbtheme.md](gbtheme.md) | Provides UI theming assets: CSS, HTML templates, JavaScript, and static resources. | +| **.gbot** | [gbot.md](gbot.md) | Stores bot configuration (CSV) for identity, LLM settings, and runtime parameters. | +| **.gbtheme** | [gbtheme.md](gbtheme.md) | Simple CSS theming - just place CSS files like default.css for custom styling. | ## How to Use This Overview diff --git a/docs/src/chapter-02/templates.md b/docs/src/chapter-02/templates.md index d6470132c..f02625bcb 100644 --- a/docs/src/chapter-02/templates.md +++ b/docs/src/chapter-02/templates.md @@ -1,369 +1,249 @@ # Bot Templates -BotServer comes with pre-built templates for common use cases. Each template is a complete `.gbai` package with dialogs, configurations, and knowledge bases ready to use. +BotServer includes 21 pre-built bot templates for various use cases. Each template is a complete `.gbai` package ready to deploy. -## Available Templates +## Template Overview + +| Template | Purpose | Key Features | Use Case | +|----------|---------|--------------|----------| +| **default.gbai** | Minimal starter bot | Basic config only | Simple bots, learning | +| **template.gbai** | Reference implementation | Complete structure example | Creating new templates | +| **announcements.gbai** | Company announcements | Multiple KB collections, auth flows | Internal communications | +| **ai-search.gbai** | AI-powered search | QR generation, PDF samples | Document retrieval | +| **api-client.gbai** | External API integration | Climate API, REST patterns | Third-party services | +| **backup.gbai** | Backup automation | Server backup scripts, scheduling | System administration | +| **bi.gbai** | Business Intelligence | Admin/user roles, data viz | Executive dashboards | +| **broadcast.gbai** | Mass messaging | Recipient management, scheduling | Marketing campaigns | +| **crawler.gbai** | Web indexing | Site crawling, content extraction | Search engines | +| **crm.gbai** | Customer Relations | Sentiment analysis, tracking | Sales & support | +| **edu.gbai** | Education platform | Course management, enrollment | Online learning | +| **erp.gbai** | Enterprise Planning | Process automation, integrations | Resource management | +| **law.gbai** | Legal assistant | Document templates, regulations | Legal departments | +| **llm-server.gbai** | LLM hosting | Model serving, GPU config | AI infrastructure | +| **llm-tools.gbai** | LLM utilities | Prompt engineering, testing | AI development | +| **marketing.gbai** | Marketing automation | Campaign tools, lead generation | Marketing teams | +| **public-apis.gbai** | Public API access | Weather, news, data sources | Information services | +| **reminder.gbai** | Task reminders | Scheduling, notifications | Personal assistants | +| **store.gbai** | E-commerce | Product catalog, orders | Online stores | +| **talk-to-data.gbai** | Natural language queries | SQL generation, data viz | Data exploration | +| **whatsapp.gbai** | WhatsApp Business | Meta API, media handling | Mobile messaging | + +## 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) +β”œβ”€β”€ template-name.gbkb/ # Knowledge base collections +β”‚ β”œβ”€β”€ collection1/ # Documents for USE KB "collection1" +β”‚ └── collection2/ # Documents for USE KB "collection2" +β”œβ”€β”€ 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 + +```bash +# Templates are auto-deployed during bootstrap +# Access at: http://localhost:8080/template-name +``` + +### 3. Customize Configuration + +Edit `template-name.gbot/config.csv`: + +```csv +name,value +bot-name,My Custom Bot +welcome-message,Hello! How can I help? +llm-model,gpt-4 +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 (Optional) + +Add `.bas` files to `.gbdialog`: +- Each file becomes a tool +- Auto-discovered by the system +- Called automatically by LLM when needed + +## Template Details ### Core Templates #### default.gbai -The foundation template that all bots inherit from. Contains: -- Basic conversation handling -- Session management -- Error handling -- Standard responses -- Core dialog flows +- **Files**: Minimal configuration only +- **Best for**: Learning, simple bots +- **Customization**: Start from scratch #### template.gbai -A minimal starting point for custom bots with: -- Skeleton structure -- Basic configuration -- Example dialogs -- Placeholder knowledge base +- **Files**: Complete example structure +- **Best for**: Reference implementation +- **Customization**: Copy and modify -### Business Templates - -#### crm.gbai -Customer Relationship Management bot featuring: -- Contact management -- Lead tracking -- Customer inquiries -- Follow-up scheduling -- Sales pipeline integration -- Customer data lookup - -#### erp.gbai -Enterprise Resource Planning assistant with: -- Inventory queries -- Order processing -- Supply chain info -- Resource allocation -- Business metrics -- Report generation - -#### bi.gbai -Business Intelligence bot providing: -- Data analysis -- Report generation -- Dashboard queries -- KPI tracking -- Trend analysis -- Executive summaries - -#### store.gbai -E-commerce assistant offering: -- Product catalog -- Order status -- Shopping cart help -- Payment processing -- Shipping information -- Return handling - -### Communication Templates +### Business Applications #### announcements.gbai -Broadcast messaging system for: -- Company announcements -- News distribution -- Event notifications -- Alert broadcasting -- Multi-channel delivery -- Scheduled messages +- **Files**: `auth.bas`, `start.bas`, multiple KB collections +- **Collections**: auxiliom, news, toolbix +- **Features**: Authentication, summaries -#### broadcast.gbai -Mass communication bot with: -- Bulk messaging -- Audience segmentation -- Campaign management -- Delivery tracking -- Response collection -- Analytics reporting +#### bi.gbai +- **Files**: `bi-admin.bas`, `bi-user.bas` +- **Features**: Role separation, dashboards +- **Data**: Report generation -#### whatsapp.gbai -WhatsApp-optimized bot featuring: -- WhatsApp Business API integration -- Media handling -- Quick replies -- List messages -- Location sharing -- Contact cards +#### crm.gbai +- **Files**: `analyze-customer-sentiment.bas`, `check.bas` +- **Features**: Sentiment analysis +- **Data**: Customer tracking -#### reminder.gbai -Automated reminder system for: -- Task reminders -- Appointment notifications -- Deadline alerts -- Recurring reminders -- Calendar integration -- Follow-up scheduling +#### store.gbai +- **Features**: Product catalog, order processing +- **Integration**: E-commerce workflows -### AI & Automation Templates +### AI & Search #### ai-search.gbai -Advanced search assistant with: -- Semantic search -- Multi-source queries -- Result ranking -- Context understanding -- Query refinement -- Search analytics - -#### llm-server.gbai -LLM gateway bot providing: -- Model selection -- Prompt management -- Token optimization -- Response caching -- Rate limiting -- Cost tracking - -#### llm-tools.gbai -AI tools collection featuring: -- Text generation -- Summarization -- Translation -- Code generation -- Image description -- Sentiment analysis - -#### crawler.gbai -Web scraping bot with: -- Site crawling -- Data extraction -- Content indexing -- Change monitoring -- Structured data parsing -- API integration +- **Files**: `qr.bas`, PDF samples +- **Features**: QR codes, document search +- **Data**: Sample PDFs included #### talk-to-data.gbai -Data conversation interface offering: -- Natural language queries -- Database access -- Data visualization -- Export capabilities -- Statistical analysis -- Report generation +- **Features**: Natural language to SQL +- **Integration**: Database connections +- **Output**: Data visualization -### Industry Templates +### Communication -#### edu.gbai -Education assistant providing: -- Course information -- Student support -- Assignment help -- Schedule queries -- Resource access -- Grade lookup +#### broadcast.gbai +- **Files**: `broadcast.bas` +- **Features**: Mass messaging +- **Scheduling**: Message campaigns -#### law.gbai -Legal information bot with: -- Legal term definitions -- Document templates -- Case lookup -- Regulation queries -- Compliance checking -- Disclaimer management +#### whatsapp.gbai +- **Config**: Meta Challenge parameter +- **Features**: WhatsApp API integration +- **Media**: Image/video support -#### marketing.gbai -Marketing automation bot featuring: -- Lead generation -- Campaign management -- Content distribution -- Social media integration -- Analytics tracking -- A/B testing - -### Integration Templates +### Development Tools #### api-client.gbai -REST API integration bot with: -- API endpoint management -- Authentication handling -- Request formatting -- Response parsing -- Error handling -- Rate limiting +- **Files**: `climate.vbs`, `msft-partner-center.bas` +- **Examples**: REST API patterns +- **Integration**: External services -#### public-apis.gbai -Public API aggregator providing: -- Weather information -- News feeds -- Stock prices -- Currency conversion -- Maps/directions -- Public data access - -#### backup.gbai -Backup management bot offering: -- Scheduled backups -- Data archiving -- Restore operations -- Backup verification -- Storage management -- Disaster recovery - -## Using Templates - -### Quick Start - -1. **Copy template to your workspace**: - ```bash - cp -r templates/crm.gbai mybot.gbai - ``` - -2. **Customize configuration**: - ```bash - cd mybot.gbai/mybot.gbot - vim config.csv - ``` - -3. **Modify dialogs**: - ```bash - cd ../mybot.gbdialog - vim start.bas - ``` - -4. **Add knowledge base**: - ```bash - cd ../mybot.gbkb - # Add your documents - ``` - -### Template Structure - -Every template follows this structure: - -``` -template-name.gbai/ -β”œβ”€β”€ template-name.gbdialog/ -β”‚ β”œβ”€β”€ start.bas # Entry point -β”‚ β”œβ”€β”€ menu.bas # Menu system -β”‚ └── tools/ # Tool definitions -β”œβ”€β”€ template-name.gbot/ -β”‚ └── config.csv # Configuration -β”œβ”€β”€ template-name.gbkb/ -β”‚ β”œβ”€β”€ docs/ # Documentation -β”‚ └── data/ # Reference data -└── template-name.gbtheme/ - └── style.css # Optional theming -``` - -## Customization Guide - -### Extending Templates - -Templates are designed to be extended: - -1. **Inherit from template**: - ```basic - INCLUDE "template://default/common.bas" - ``` - -2. **Override functions**: - ```basic - FUNCTION handle_greeting() - ' Custom greeting logic - TALK "Welcome to MyBot!" - END FUNCTION - ``` - -3. **Add new features**: - ```basic - ' Add to existing template - FUNCTION new_feature() - ' Your custom code - END FUNCTION - ``` - -### Combining Templates - -Mix features from multiple templates: - -```basic -' Use CRM contact management -INCLUDE "template://crm/contacts.bas" - -' Add marketing automation -INCLUDE "template://marketing/campaigns.bas" - -' Integrate with APIs -INCLUDE "template://api-client/rest.bas" -``` +#### llm-server.gbai +- **Config**: Model serving parameters +- **Features**: GPU configuration +- **Purpose**: Local LLM hosting ## Best Practices ### Template Selection -1. **Start with the right template**: Choose based on primary use case -2. **Combine when needed**: Mix templates for complex requirements -3. **Keep core intact**: Don't modify template originals -4. **Document changes**: Track customizations +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 Tips +### Customization Strategy -1. **Configuration first**: Adjust config.csv before code -2. **Test incrementally**: Verify each change -3. **Preserve structure**: Maintain template organization -4. **Version control**: Track template modifications +#### Minimal BASIC Approach +Instead of complex dialog flows, use simple LLM calls: -### Performance Considerations - -1. **Remove unused features**: Delete unnecessary dialogs -2. **Optimize knowledge base**: Index only needed content -3. **Configure appropriately**: Adjust settings for scale -4. **Monitor resource usage**: Track memory and CPU - -## Template Development - -### Creating Custom Templates - -1. **Start from template.gbai**: Use as foundation -2. **Define clear purpose**: Document template goals -3. **Include examples**: Provide sample data -4. **Write documentation**: Explain usage -5. **Test thoroughly**: Verify all features - -### Template Guidelines - -- Keep templates focused on specific use cases -- Include comprehensive examples -- Provide clear documentation -- Use consistent naming conventions -- Include error handling -- Make configuration obvious -- Test across channels - -## Contributing Templates - -To contribute a new template: - -1. Create template in `templates/` directory -2. Include README with description -3. Add example configuration -4. Provide sample knowledge base -5. Include test cases -6. Submit pull request - -## Template Updates - -Templates are versioned and updated regularly: -- Bug fixes -- Security patches -- Feature additions -- Performance improvements -- Documentation updates - -Check for updates: -```bash -git pull -diff templates/template-name.gbai +```basic +' Traditional: 100+ lines of intent matching +' BotServer: Let LLM handle it +response = LLM prompt +TALK response ``` -## Support +#### Tool Creation +Only create `.bas` files for specific actions: +- API calls +- Database operations +- File processing +- Calculations -For template-specific help: -- Check template README -- Review example code -- Consult documentation -- Ask in community forums -- Report issues on GitHub \ No newline at end of file +#### 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 + +## 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 + +## Migration Philosophy + +When migrating from traditional platforms: + +### Remove Complexity +- ❌ Intent detection β†’ βœ… LLM understands naturally +- ❌ State machines β†’ βœ… LLM maintains context +- ❌ Routing logic β†’ βœ… LLM handles flow +- ❌ Entity extraction β†’ βœ… LLM identifies information + +### Embrace Simplicity +- Let LLM handle conversations +- Create tools only for actions +- Use knowledge bases for context +- Trust the system's capabilities + +## Template Maintenance + +- Templates updated with BotServer releases +- Check repository for latest versions +- Review changes before upgrading +- Test in development first + +## Support Resources + +- README files in each template folder +- Example configurations included +- Sample knowledge bases provided +- Community forums for discussions \ No newline at end of file diff --git a/docs/src/chapter-03/README.md b/docs/src/chapter-03/README.md index 270dec8c7..a018d85ce 100644 --- a/docs/src/chapter-03/README.md +++ b/docs/src/chapter-03/README.md @@ -1,24 +1,24 @@ ## gbkb Reference The knowledge‑base package provides three main commands: -- **USE_KB** – Loads and embeds files from the `.gbkb/collection-name` folder into the vector database, making them available for semantic search in the current session. Multiple KBs can be active simultaneously. -- **CLEAR_KB** – Removes a knowledge base from the current session (files remain embedded in the vector database). -- **ADD_WEBSITE** – Crawl a website and add its pages to a collection. +- **USE KB** – Loads and embeds files from the `.gbkb/collection-name` folder into the vector database, making them available for semantic search in the current session. Multiple KBs can be active simultaneously. +- **CLEAR KB** – Removes a knowledge base from the current session (files remain embedded in the vector database). +- **ADD WEBSITE** – Crawl a website and add its pages to a collection. **Example:** ```bas ' Add support docs KB - files from work/botname/botname.gbkb/support_docs/ are embedded -USE_KB "support_docs" +USE KB "support_docs" ' Add multiple KBs to the same session -USE_KB "policies" -USE_KB "procedures" +USE KB "policies" +USE KB "procedures" ' Remove a specific KB from session -CLEAR_KB "policies" +CLEAR KB "policies" ' Remove all KBs from session -CLEAR_KB +CLEAR KB ``` The vector database retrieves relevant chunks/excerpts from active KBs and injects them into LLM prompts automatically, providing context-aware responses. diff --git a/docs/src/chapter-03/caching.md b/docs/src/chapter-03/caching.md index 294bf9ef3..e3f61d900 100644 --- a/docs/src/chapter-03/caching.md +++ b/docs/src/chapter-03/caching.md @@ -1,43 +1,100 @@ -# Caching (Optional) +# Caching -Caching can improve response times for frequently accessed knowledge‑base queries. +BotServer includes automatic caching to improve response times and reduce redundant processing. -## In‑Memory Cache +## How Caching Works -The bot maintains an LRU (least‑recently‑used) cache of the last 100 `FIND` results. This cache is stored in the bot’s process memory and cleared on restart. - -## Persistent Cache - -For longer‑term caching, the `gbkb` package can write query results to a local SQLite file (`cache.db`). The cache key is a hash of the query string and collection name. +Caching in BotServer is controlled by configuration parameters in `config.csv`. The system automatically caches LLM responses and manages conversation history. ## Configuration -Add the following to `.gbot/config.csv`: +From `default.gbai/default.gbot/config.csv`: ```csv -key,value -cache_enabled,true -cache_max_entries,500 +llm-cache,false # Enable/disable LLM response caching +llm-cache-ttl,3600 # Cache time-to-live in seconds +llm-cache-semantic,true # Use semantic similarity for cache matching +llm-cache-threshold,0.95 # Similarity threshold for cache hits ``` -## Usage Example +## Conversation History Management + +The system manages conversation context through these parameters: + +```csv +prompt-history,2 # Number of previous messages to include in context +prompt-compact,4 # Compact conversation after N exchanges +``` + +### What These Settings Do + +- **prompt-history**: Keeps the last 2 exchanges in the conversation context +- **prompt-compact**: After 4 exchanges, older messages are summarized or removed to save tokens + +## LLM Response Caching + +When `llm-cache` is enabled: + +1. User asks a question +2. System checks if a semantically similar question was asked before +3. If similarity > threshold (0.95), returns cached response +4. Otherwise, generates new response and caches it + +## Example Usage ```basic -USE_KB "company-policies" -FIND "vacation policy" INTO RESULT ' first call hits VectorDB -FIND "vacation policy" INTO RESULT ' second call hits cache -TALK RESULT +' Caching happens automatically when enabled +USE KB "policies" + +' First user asks: "What's the vacation policy?" +' System generates response and caches it + +' Second user asks: "Tell me about vacation days" +' System finds cached response (high semantic similarity) +' Returns instantly without calling LLM ``` -The second call returns instantly from the cache. +## Cache Storage -## Cache Invalidation - -- When a document is added or updated, the cache for that collection is cleared. -- Manual invalidation: `CLEAR_CACHE "company-policies"` (custom keyword provided by the system). +The cache is stored in the cache component (Valkey) when available, providing: +- Fast in-memory access +- Persistence across restarts +- Shared cache across sessions ## Benefits -- Reduces latency for hot queries. -- Lowers load on VectorDB. -- Transparent to the script author; caching is automatic. +- **Faster responses** for common questions +- **Lower costs** by reducing LLM API calls +- **Consistent answers** for similar questions +- **Automatic management** with no code changes + +## Best Practices + +1. **Enable for FAQ bots** - High cache hit rate +2. **Adjust threshold** - Lower for more cache hits, higher for precision +3. **Set appropriate TTL** - Balance freshness vs performance +4. **Monitor cache hits** - Ensure it's providing value + +## Performance Impact + +With caching enabled: +- Common questions: <50ms response time +- Cache misses: Normal LLM response time +- Memory usage: Minimal (only stores text responses) + +## Clearing Cache + +Cache is automatically cleared when: +- TTL expires (after 3600 seconds by default) +- Bot configuration changes +- Knowledge base is updated +- System restarts (if not using persistent cache) + +## Important Notes + +- Caching is transparent to dialog scripts +- No special commands needed +- Works with all LLM providers +- Respects conversation context + +Remember: Caching is configured in `config.csv`, not through BASIC commands! \ No newline at end of file diff --git a/docs/src/chapter-03/context-compaction.md b/docs/src/chapter-03/context-compaction.md index 709d6e537..e6f660e33 100644 --- a/docs/src/chapter-03/context-compaction.md +++ b/docs/src/chapter-03/context-compaction.md @@ -1,36 +1,98 @@ # Context Compaction -When a conversation grows long, the bot’s context window can exceed the LLM’s token limit. **Context compaction** reduces the stored history while preserving essential information. +Context compaction automatically manages conversation history to stay within token limits while preserving important information. -## Strategies +## How It Works -1. **Summarization** – Periodically run `TALK FORMAT` with a summarization prompt and replace older messages with the summary. -2. **Memory Pruning** – Use `SET_BOT_MEMORY` to store only key facts (e.g., user name, preferences) and discard raw chat logs. -3. **Chunk Rotation** – Keep a sliding window of the most recent *N* messages (configurable via `context_window` in `.gbot/config.csv`). +Context compaction is controlled by two parameters in `config.csv`: -## Implementation Example - -```basic -' After 10 exchanges, summarize -IF MESSAGE_COUNT >= 10 THEN - TALK "Summarizing recent conversation..." - SET_BOT_MEMORY "summary" FORMAT(RECENT_MESSAGES, "summarize") - CLEAR_MESSAGES ' removes raw messages -ENDIF +```csv +prompt-history,2 # Keep last 2 message exchanges +prompt-compact,4 # Compact after 4 total exchanges ``` -## Configuration +## Configuration Parameters -- `context_window` (in `.gbot/config.csv`) defines how many recent messages are kept automatically. -- `memory_enabled` toggles whether the bot uses persistent memory. +### prompt-history +Determines how many previous exchanges to include in the LLM context: +- Default: `2` (keeps last 2 user messages and 2 bot responses) +- Range: 1-10 depending on your token budget +- Higher values = more context but more tokens used + +### prompt-compact +Triggers compaction after N exchanges: +- Default: `4` (compacts conversation after 4 back-and-forth exchanges) +- When reached, older messages are summarized or removed +- Helps manage long conversations efficiently + +## Automatic Behavior + +The system automatically: +1. Tracks conversation length +2. When exchanges exceed `prompt-compact` value +3. Keeps only the last `prompt-history` exchanges +4. Older messages are dropped from context + +## Example Flow + +With default settings (`prompt-history=2`, `prompt-compact=4`): + +``` +Exchange 1: User asks, bot responds +Exchange 2: User asks, bot responds +Exchange 3: User asks, bot responds +Exchange 4: User asks, bot responds +Exchange 5: Compaction triggers - only exchanges 3-4 kept +Exchange 6: Only exchanges 4-5 in context +``` ## Benefits -- Keeps token usage within limits. -- Improves response relevance by focusing on recent context. -- Allows long‑term facts to persist without bloating the prompt. +- **Automatic management** - No manual intervention needed +- **Token efficiency** - Stay within model limits +- **Relevant context** - Keeps recent, important exchanges +- **Cost savings** - Fewer tokens = lower API costs -## Caveats +## Adjusting Settings -- Over‑aggressive pruning may lose important details. -- Summaries should be concise (max 200 tokens) to avoid re‑inflating the context. +### For longer context: +```csv +prompt-history,5 # Keep more history +prompt-compact,10 # Compact less frequently +``` + +### For minimal context: +```csv +prompt-history,1 # Only last exchange +prompt-compact,2 # Compact aggressively +``` + +## Use Cases + +### Customer Support +- Lower values work well (customers ask independent questions) +- `prompt-history,1` and `prompt-compact,2` + +### Complex Discussions +- Higher values needed (maintain conversation flow) +- `prompt-history,4` and `prompt-compact,8` + +### FAQ Bots +- Minimal context needed (each question is standalone) +- `prompt-history,1` and `prompt-compact,2` + +## Important Notes + +- Compaction is automatic based on config.csv +- No BASIC commands control compaction +- Settings apply to all conversations +- Changes require bot restart + +## Best Practices + +1. **Start with defaults** - Work well for most use cases +2. **Monitor token usage** - Adjust if hitting limits +3. **Consider conversation type** - Support vs discussion +4. **Test different values** - Find optimal balance + +The system handles all compaction automatically - just configure the values that work for your use case! \ No newline at end of file diff --git a/docs/src/chapter-03/indexing.md b/docs/src/chapter-03/indexing.md index 463e0d7c5..2b62ff559 100644 --- a/docs/src/chapter-03/indexing.md +++ b/docs/src/chapter-03/indexing.md @@ -1,22 +1,143 @@ # Document Indexing -When a document is added to a knowledge‑base collection with `USE_KB` or `ADD_WEBSITE`, the system performs several steps to make it searchable: +Document indexing in BotServer is automatic. When documents are added to `.gbkb` folders, they are processed and made searchable without any manual configuration. -1. **Content Extraction** – Files are read and plain‑text is extracted (PDF, DOCX, HTML, etc.). -2. **Chunking** – The text is split into 500‑token chunks to keep embeddings manageable. -3. **Embedding Generation** – Each chunk is sent to the configured LLM embedding model (default **BGE‑small‑en‑v1.5**) to produce a dense vector. -4. **Storage** – Vectors, along with metadata (source file, chunk offset), are stored in VectorDB under the collection’s namespace. -5. **Indexing** – VectorDB builds an IVF‑PQ index for fast approximate nearest‑neighbor search. +## Automatic Indexing -## Index Refresh +The system automatically indexes documents when: +- Files are added to any `.gbkb` folder +- `USE KB` is called for a collection +- Files are modified or updated +- `ADD WEBSITE` crawls new content -If a document is updated, the system re‑processes the file and replaces the old vectors. The index is automatically refreshed; no manual action is required. +## How Indexing Works -## Example +1. **Document Detection** - System scans `.gbkb` folders for files +2. **Text Extraction** - Content extracted from PDF, DOCX, HTML, MD, TXT +3. **Chunking** - Text split into manageable segments +4. **Embedding Generation** - Chunks converted to vectors using BGE model +5. **Storage** - Vectors stored for semantic search + +## Supported File Types + +- **PDF** - Full text extraction +- **DOCX** - Microsoft Word documents +- **TXT** - Plain text files +- **HTML** - Web pages (text only) +- **MD** - Markdown documents +- **CSV** - Structured data + +## Website Indexing + +To keep web content fresh, schedule regular crawls: ```basic -USE_KB "company-policies" -ADD_WEBSITE "https://example.com/policies" +' In update-docs.bas +SET SCHEDULE "0 2 * * *" ' Run daily at 2 AM + +ADD WEBSITE "https://docs.example.com" +' Website is crawled and indexed automatically ``` -After execution, the `company-policies` collection contains indexed vectors ready for semantic search via the `FIND` keyword. +### Scheduling Options + +```basic +SET SCHEDULE "0 * * * *" ' Every hour +SET SCHEDULE "*/30 * * * *" ' Every 30 minutes +SET SCHEDULE "0 0 * * 0" ' Weekly on Sunday +SET SCHEDULE "0 0 1 * *" ' Monthly on the 1st +``` + +## Real-Time Updates + +Documents are re-indexed automatically when: +- File content changes +- New files appear in folders +- Files are deleted (removed from index) + +## Using Indexed Content + +Once indexed, content is automatically available: + +```basic +USE KB "documentation" +' All documents in the documentation folder are now searchable +' The LLM will use this knowledge when answering questions +``` + +You don't need to explicitly search - the system does it automatically when generating responses. + +## Configuration + +Indexing uses settings from `config.csv`: + +```csv +embedding-url,http://localhost:8082 +embedding-model,../../../../data/llm/bge-small-en-v1.5-f32.gguf +``` + +The BGE embedding model can be replaced with any compatible model. + +## Performance Optimization + +The system optimizes indexing by: +- Processing only changed files +- Caching embeddings +- Parallel processing when possible +- Incremental updates + +## Example: Knowledge Base Maintenance + +Structure your knowledge base: +``` +company.gbkb/ +β”œβ”€β”€ products/ +β”‚ β”œβ”€β”€ manual-v1.pdf +β”‚ └── specs.docx +β”œβ”€β”€ policies/ +β”‚ β”œβ”€β”€ hr-policy.pdf +β”‚ └── it-policy.md +└── news/ + └── updates.html +``` + +Schedule regular web updates: +```basic +' In maintenance.bas +SET SCHEDULE "0 1 * * *" + +' Update news daily +ADD WEBSITE "https://company.com/news" + +' Update product docs weekly +IF DAY_OF_WEEK = "Monday" THEN + ADD WEBSITE "https://company.com/products" +END IF +``` + +## Best Practices + +1. **Organize documents** by topic in separate folders +2. **Schedule updates** for web content +3. **Keep files updated** - system handles re-indexing +4. **Monitor folder sizes** - very large collections may impact performance +5. **Use clear naming** - helps with organization + +## Troubleshooting + +### Documents Not Appearing +- Check file is in a `.gbkb` folder +- Verify file type is supported +- Ensure `USE KB` was called for that collection + +### Slow Indexing +- Large PDFs may take time to process +- Consider splitting very large documents +- Check available system resources + +### Outdated Content +- Set up scheduled crawls for web content +- Ensure files are being updated +- Check that re-indexing is triggered + +Remember: Indexing is automatic - just add documents to folders and use `USE KB` to activate them! \ No newline at end of file diff --git a/docs/src/chapter-03/kb-and-tools.md b/docs/src/chapter-03/kb-and-tools.md index f7ac5eb4b..c16ef5d1f 100644 --- a/docs/src/chapter-03/kb-and-tools.md +++ b/docs/src/chapter-03/kb-and-tools.md @@ -4,10 +4,10 @@ The General Bots system provides **4 essential keywords** for managing Knowledge Bases (KB) and Tools dynamically during conversation sessions: -1. **USE_KB** - Load and embed files from `.gbkb` folders into vector database -2. **CLEAR_KB** - Remove KB from current session -3. **USE_TOOL** - Make a tool available for LLM to call -4. **CLEAR_TOOLS** - Remove all tools from current session +1. **USE KB** - Load and embed files from `.gbkb` folders into vector database +2. **CLEAR KB** - Remove KB from current session +3. **USE TOOL** - Make a tool available for LLM to call +4. **CLEAR TOOLS** - Remove all tools from current session --- @@ -54,22 +54,22 @@ work/ - **HTML** - Web pages (text only) - **JSON** - Structured data -### USE_KB Keyword +### USE KB Keyword ```basic -USE_KB "circular" +USE KB "circular" # Loads the 'circular' KB folder into session # All documents in that folder are now searchable -USE_KB "comunicado" +USE KB "comunicado" # Adds another KB to the session # Both 'circular' and 'comunicado' are now active ``` -### CLEAR_KB Keyword +### CLEAR KB Keyword ```basic -CLEAR_KB +CLEAR KB # Removes all loaded KBs from current session # Frees up memory and context space ``` @@ -89,57 +89,44 @@ Tools are **callable functions** that the LLM can invoke to perform specific act ### Tool Definition -Tools are defined in `.gbtool` files with JSON schema: +Tools are defined in .bas files that generate MCP and OpenAI-compatible tool definitions: -```json -{ - "name": "get_weather", - "description": "Get current weather for a location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "City name or coordinates" - }, - "units": { - "type": "string", - "enum": ["celsius", "fahrenheit"], - "default": "celsius" - } - }, - "required": ["location"] - }, - "endpoint": "https://api.weather.com/current", - "method": "GET" -} +```basic +' weather.bas - becomes a tool automatically +PARAM location AS string +PARAM units AS string DEFAULT "celsius" +DESCRIPTION "Get current weather for a location" + +' Tool implementation +weather_data = GET "https://api.weather.com/v1/current?location=" + location +result = LLM "Format this weather data nicely: " + weather_data +TALK result ``` ### Tool Registration -Tools can be registered in three ways: +Tools are registered in two ways: -1. **Static Registration** - In bot configuration -2. **Dynamic Loading** - Via USE_TOOL keyword -3. **Auto-discovery** - From `.gbtool` files in work directory +1. **Auto-discovery** - All `.bas` files in `.gbdialog` folder (except start.bas) become tools +2. **Dynamic Loading** - Via USE TOOL keyword for external tools -### USE_TOOL Keyword +### USE TOOL Keyword ```basic -USE_TOOL "weather" +USE TOOL "weather" # Makes the weather tool available to LLM -USE_TOOL "database_query" +USE TOOL "database_query" # Adds database query tool to session -USE_TOOL "email_sender" +USE TOOL "email_sender" # Enables email sending capability ``` -### CLEAR_TOOLS Keyword +### CLEAR TOOLS Keyword ```basic -CLEAR_TOOLS +CLEAR TOOLS # Removes all tools from current session # LLM can no longer call external functions ``` @@ -151,7 +138,7 @@ CLEAR_TOOLS ### Context Lifecycle 1. **Session Start** - Clean slate, no KB or tools -2. **Load Resources** - USE_KB and USE_TOOL as needed +2. **Load Resources** - USE KB and USE TOOL as needed 3. **Active Use** - LLM uses loaded resources 4. **Clear Resources** - CLEAR_KB/CLEAR_TOOLS when done 5. **Session End** - Automatic cleanup @@ -238,7 +225,7 @@ ws.send({ // Load Tool ws.send({ - type: "USE_TOOL", + type: "USE TOOL", tool_name: "weather" }); @@ -292,12 +279,13 @@ Configuration: ## Error Handling ### Common Errors +### Common Issues | Error | Cause | Solution | |-------|-------|----------| | `KB_NOT_FOUND` | KB folder doesn't exist | Check folder name and path | -| `VECTORDB_ERROR` | Qdrant connection issue | Check vectorDB service | -| `EMBEDDING_FAILED` | OpenAI API error | Check API key and limits | +| `VECTORDB_ERROR` | Vector database connection issue | Check vector database service | +| `EMBEDDING_FAILED` | Embedding API error | Check API key and limits | | `TOOL_NOT_FOUND` | Tool not registered | Verify tool name | | `TOOL_EXECUTION_ERROR` | Tool failed to execute | Check tool endpoint/logic | | `MEMORY_LIMIT` | Too many KBs loaded | Clear unused KBs | @@ -328,10 +316,10 @@ USE_KB "product_docs" USE_KB "faqs" # Enable support tools -USE_TOOL "ticket_system" -USE_TOOL "knowledge_search" +USE TOOL "ticket_system" +USE TOOL "knowledge_search" -# Bot now has access to docs and can create tickets +# Bot now has access to docs and can work with tickets HEAR user_question # ... process with KB context and tools ... @@ -348,8 +336,8 @@ USE_KB "papers_2024" USE_KB "citations" # Enable research tools -USE_TOOL "arxiv_search" -USE_TOOL "citation_formatter" +USE TOOL "arxiv_search" +USE TOOL "citation_formatter" # Assistant can now search papers and format citations # ... research session ... @@ -367,11 +355,11 @@ USE_KB "hr_policies" USE_KB "it_procedures" # Enable enterprise tools -USE_TOOL "active_directory" -USE_TOOL "jira_integration" -USE_TOOL "slack_notifier" +USE TOOL "active_directory" +USE TOOL "jira_integration" +USE TOOL "slack_notifier" -# Bot can now query AD, create Jira tickets, send Slack messages +# Bot can now query AD, work with Jira, send Slack messages # ... handle employee request ... # End of shift cleanup @@ -409,22 +397,16 @@ CLEAR_TOOLS ## Configuration -### Environment Variables +Configuration is handled automatically through `config.csv`. No manual environment variables needed. -```bash -# Vector Database -QDRANT_URL=http://localhost:6333 -QDRANT_API_KEY=your_key + +- [ ] Tool versioning system +- [ ] Enhanced parallel execution -# Embeddings -OPENAI_API_KEY=your_key -EMBEDDING_MODEL=text-embedding-ada-002 -CHUNK_SIZE=1000 -CHUNK_OVERLAP=200 - -# Tools -MAX_TOOLS_PER_SESSION=10 -TOOL_TIMEOUT_SECONDS=30 +### Platform Expansion +- [ ] More language bindings +- [ ] Additional databases +- [ ] Extended file formats TOOL_RATE_LIMIT=100 # KB @@ -506,25 +488,9 @@ collection_prefix = "botserver_" 1. Convert function to tool definition 2. Create .gbtool file 3. Implement endpoint/handler -4. Test with USE_TOOL +4. Test with USE TOOL 5. Remove static registration --- -## Future Enhancements -### Planned Features - -- **Incremental KB Updates** - Add/remove single documents -- **Multi-language Support** - Embeddings in multiple languages -- **Tool Chaining** - Tools calling other tools -- **KB Versioning** - Track KB changes over time -- **Smart Caching** - Cache frequent searches -- **Tool Analytics** - Usage statistics and optimization - -### Roadmap - -- Q1 2024: Incremental updates, multi-language -- Q2 2024: Tool chaining, KB versioning -- Q3 2024: Smart caching, analytics -- Q4 2024: Advanced security, enterprise features \ No newline at end of file diff --git a/docs/src/chapter-03/semantic-cache.md b/docs/src/chapter-03/semantic-cache.md index f478294cc..4038ab62f 100644 --- a/docs/src/chapter-03/semantic-cache.md +++ b/docs/src/chapter-03/semantic-cache.md @@ -2,7 +2,7 @@ ## Overview -The BotServer now supports semantic caching for LLM responses using Valkey (Redis-compatible in-memory database). This feature can significantly reduce response times and API costs by intelligently caching and reusing previous LLM responses. +The BotServer now supports semantic caching for LLM responses using Valkey (cache component - a Redis-compatible in-memory database). This feature can significantly reduce response times and API costs by intelligently caching and reusing previous LLM responses. ## Features @@ -169,7 +169,7 @@ Monitor these metrics: ### Cache Not Working -1. Verify Valkey/Redis is running and accessible +1. Verify cache (Valkey) is running and accessible 2. Check `llm-cache` is set to `true` in config.csv 3. Ensure sufficient memory is available in Valkey 4. Check logs for connection errors diff --git a/docs/src/chapter-03/semantic-search.md b/docs/src/chapter-03/semantic-search.md index 645f00c12..8dd7ef207 100644 --- a/docs/src/chapter-03/semantic-search.md +++ b/docs/src/chapter-03/semantic-search.md @@ -1,36 +1,118 @@ # Semantic Search -Semantic search enables the bot to retrieve information based on meaning rather than exact keyword matches. It leverages the vector embeddings stored in VectorDB. +Semantic search in BotServer happens automatically when you use `USE KB`. The system searches for relevant information based on meaning, not just keywords, and injects it into the LLM's context. -## How It Works +## How It Works Automatically -1. **Query Embedding** – The user’s query string is converted into a dense vector using the same embedding model as the documents. -2. **Nearest‑Neighbor Search** – VectorDB returns the top‑k vectors that are closest to the query vector. -3. **Result Formatting** – The matching document chunks are concatenated and passed to the LLM as context for the final response. +1. **User asks a question** - Natural language input +2. **Query converted to vector** - Using the embedding model +3. **Search active collections** - Finds semantically similar content +4. **Inject into context** - Relevant chunks added to LLM prompt +5. **Generate response** - LLM answers using the knowledge -## Using the `FIND` Keyword +## Activating Semantic Search + +Simply use `USE KB` to enable search for a collection: ```basic -USE_KB "company-policies" -FIND "how many vacation days do I have?" INTO RESULT -TALK RESULT +USE KB "policies" +USE KB "procedures" +' Both collections are now searchable +' No explicit search commands needed ``` -- `USE_KB` adds the collection to the session. -- `FIND` performs the semantic search. -- `RESULT` receives the best matching snippet. +When users ask questions, the system automatically searches these collections and provides relevant context to the LLM. -## Parameters +## How Meaning-Based Search Works -- **k** – Number of results to return (default 3). Can be overridden with `FIND "query" LIMIT 5 INTO RESULT`. -- **filter** – Optional metadata filter, e.g., `FILTER source="policy.pdf"`. +Unlike keyword search, semantic search understands meaning: -## Best Practices +- "How many days off do I get?" matches "vacation policy" +- "What's the return policy?" matches "refund procedures" +- "I'm feeling sick" matches "medical leave guidelines" -- Keep the query concise (1‑2 sentences) for optimal embedding quality. -- Use `FORMAT` to clean up the result before sending to the user. -- Combine with `GET_BOT_MEMORY` to store frequently accessed answers. +The system uses vector embeddings to find conceptually similar content, even when exact words don't match. + +## Configuration + +Search behavior is controlled by `config.csv`: + +```csv +prompt-history,2 # How many previous messages to include +prompt-compact,4 # Compact context after N exchanges +``` + +These settings manage how much context the LLM receives, not the search itself. + +## Multiple Collections + +When multiple collections are active, the system searches all of them: + +```basic +USE KB "products" +USE KB "support" +USE KB "warranty" + +' User: "My laptop won't turn on" +' System searches all three collections for relevant info +``` + +## Search Quality + +The quality of semantic search depends on: +- **Document organization** - Well-structured folders help +- **Embedding model** - BGE model works well, can be replaced +- **Content quality** - Clear, descriptive documents work best + +## Real Example + +```basic +' In start.bas +USE KB "company-handbook" + +' User types: "What's the dress code?" +' System automatically: +' 1. Searches company-handbook for dress code info +' 2. Finds relevant sections about attire +' 3. Injects them into LLM context +' 4. LLM generates natural response with the information +``` ## Performance -Semantic search latency is typically <β€―100β€―ms for collections under 50β€―k vectors. Larger collections may require tuning VectorDB’s HNSW parameters. +- Search happens in milliseconds +- No configuration needed +- Cached for repeated queries +- Only active collections are searched + +## Best Practices + +1. **Activate only needed collections** - Don't overload context +2. **Organize content well** - One topic per folder +3. **Use descriptive text** - Helps with matching +4. **Keep documents updated** - Fresh content = better answers + +## Common Misconceptions + +❌ **Wrong**: You need to call a search function +βœ… **Right**: Search happens automatically with `USE KB` + +❌ **Wrong**: You need to configure search parameters +βœ… **Right**: It works out of the box + +❌ **Wrong**: You need special commands to query +βœ… **Right**: Users just ask questions naturally + +## Troubleshooting + +### Not finding relevant content? +- Check the collection is activated with `USE KB` +- Verify documents are in the right folder +- Ensure content is descriptive + +### Too much irrelevant content? +- Use fewer collections simultaneously +- Organize documents into more specific folders +- Clear unused collections with `CLEAR KB` + +Remember: The beauty of semantic search in BotServer is its simplicity - just `USE KB` and let the system handle the rest! \ No newline at end of file diff --git a/docs/src/chapter-03/vector-collections.md b/docs/src/chapter-03/vector-collections.md index 9ae32b080..8ac1c4435 100644 --- a/docs/src/chapter-03/vector-collections.md +++ b/docs/src/chapter-03/vector-collections.md @@ -1,45 +1,124 @@ # Vector Collections -A **vector collection** is a set of documents that have been transformed into vector embeddings for fast semantic similarity search. Each collection lives under a `.gbkb` folder and is identified by a unique name. +A **vector collection** is automatically generated from each folder in `.gbkb`. Each folder becomes a searchable collection that the LLM can use during conversations. -## Creating a Collection +## How Collections Work -Use the `USE_KB` keyword in a dialog script: +Each `.gbkb` folder is automatically: +1. Scanned for documents (PDF, DOCX, TXT, HTML, MD) +2. Text extracted from all files +3. Split into chunks for processing +4. Converted to vector embeddings using BGE model (replaceable) +5. Made available for semantic search -```basic -USE_KB "company-policies" +## Folder Structure + +``` +botname.gbkb/ +β”œβ”€β”€ policies/ # Becomes "policies" collection +β”œβ”€β”€ procedures/ # Becomes "procedures" collection +└── faqs/ # Becomes "faqs" collection ``` -This creates a new collection named `company-policies` in the bot’s knowledge base. +## Using Collections -## Adding Documents - -Documents can be added directly from files or by crawling a website: +Simply activate a collection with `USE KB`: ```basic -USE_KB "company-policies" ' loads and embeds all files from .gbkb/company-policies/ folder -ADD_WEBSITE "https://example.com/policies" +USE KB "policies" +' The LLM now has access to all documents in the policies folder +' No need to explicitly search - happens automatically during responses ``` -The system will download the content, split it into chunks, generate embeddings using the default LLM model, and store them in the collection. +## Multiple Collections -## Managing Collections - -- `USE_KB "collection-name"` – loads and embeds files from the `.gbkb/collection-name` folder into the vector database, making them available for semantic search in the current session. -- `CLEAR_KB "collection-name"` – removes the collection from the current session (files remain embedded in vector database). - -## Use in Dialogs - -When a KB is added to a session, the vector database is queried to retrieve relevant document chunks/excerpts that are automatically injected into LLM prompts, providing context-aware responses. +Load multiple collections for comprehensive knowledge: ```basic -USE_KB "company-policies" -FIND "vacation policy" INTO RESULT -TALK RESULT +USE KB "policies" +USE KB "procedures" +USE KB "faqs" +' All three collections are now active +' LLM searches across all when generating responses ``` -## Technical Details +## Automatic Document Indexing -- Embeddings are generated with the BGE‑small‑en‑v1.5 model. -- Vectors are stored in VectorDB (see Chapterβ€―04). -- Each document is chunked into 500‑token pieces for efficient retrieval. +Documents are indexed automatically when: +- Files are added to `.gbkb` folders +- `USE KB` is called for the first time +- The system detects new or modified files + +## Website Indexing + +To keep web content updated, schedule regular crawls: + +```basic +' In update-content.bas +SET SCHEDULE "0 3 * * *" ' Run daily at 3 AM +ADD WEBSITE "https://example.com/docs" +' Website content is crawled and added to the collection +``` + +## How Search Works + +When `USE KB` is active: +1. User asks a question +2. System automatically searches relevant collections +3. Finds semantically similar content +4. Injects relevant chunks into LLM context +5. LLM generates response using the knowledge + +**Important**: Search happens automatically - you don't need to call any search function. Just activate the KB with `USE KB` and ask questions naturally. + +## Embeddings Configuration + +The system uses BGE embeddings by default: + +```csv +embedding-url,http://localhost:8082 +embedding-model,../../../../data/llm/bge-small-en-v1.5-f32.gguf +``` + +You can replace BGE with any compatible embedding model by changing the model path in config.csv. + +## Collection Management + +- `USE KB "name"` - Activates a collection for the session +- `CLEAR KB` - Removes all active collections +- `CLEAR KB "name"` - Removes a specific collection + +## Best Practices + +1. **Organize by topic** - One folder per subject area +2. **Name clearly** - Use descriptive folder names +3. **Update regularly** - Schedule website crawls if using web content +4. **Keep files current** - System auto-indexes changes +5. **Don't overload** - Use only necessary collections per session + +## Example: Customer Support Bot + +``` +support.gbkb/ +β”œβ”€β”€ products/ # Product documentation +β”œβ”€β”€ policies/ # Company policies +β”œβ”€β”€ troubleshooting/ # Common issues and solutions +└── contact/ # Contact information +``` + +In your dialog: +```basic +' Activate all support knowledge +USE KB "products" +USE KB "troubleshooting" +' Bot can now answer product questions and solve issues +``` + +## Performance Notes + +- Collections are cached for fast access +- Only active collections consume memory +- Embeddings are generated once and reused +- Changes trigger automatic re-indexing + +No manual configuration needed - just organize your documents in folders and use `USE KB` to activate them! \ No newline at end of file diff --git a/docs/src/chapter-04/README.md b/docs/src/chapter-04/README.md index 310213b48..272caf06c 100644 --- a/docs/src/chapter-04/README.md +++ b/docs/src/chapter-04/README.md @@ -1,157 +1,197 @@ -# Chapter 04: UI Customization +# Chapter 04: gbtheme Reference -BotServer provides basic UI customization through configuration parameters in the `config.csv` file. While there's no dedicated `.gbtheme` package type, you can customize the appearance of the web interface using theme parameters. +Themes control how your bot looks in the web interface. A theme is simply a CSS file that changes colors, fonts, and styles. -## Overview +## Quick Start -The web interface theming system allows you to customize: -- Brand colors (primary and secondary) -- Logo image -- Application title -- Logo text +1. Create a `.gbtheme` folder in your bot package +2. Add a CSS file (like `default.css` or `3dbevel.css`) +3. The theme loads automatically when the bot starts -These customizations are applied dynamically to the web interface and broadcast to all connected clients in real-time. - -## Theme Configuration - -Theme settings are configured in your bot's `config.csv` file located in the `.gbot` directory: +## Theme Structure ``` -templates/your-bot.gbai/your-bot.gbot/config.csv +mybot.gbai/ +└── mybot.gbtheme/ + β”œβ”€β”€ default.css # Main theme + β”œβ”€β”€ 3dbevel.css # Retro Windows 95 style + └── dark.css # Dark mode variant ``` -### Available Theme Parameters +## The 3D Bevel Theme -| Parameter | Description | Example | -|-----------|-------------|---------| -| `theme-color1` | Primary theme color | `#0d2b55` | -| `theme-color2` | Secondary theme color | `#fff9c2` | -| `theme-logo` | Logo image URL | `https://example.com/logo.svg` | -| `theme-title` | Browser tab title | `My Custom Bot` | -| `theme-logo-text` | Text displayed with logo | `Company Name` | -| `Theme Color` | Simple color name (alternative) | `green`, `purple`, `indigo` | +The `3dbevel.css` theme gives your bot a classic Windows 95 look with 3D beveled edges: -## Implementation Details +```css +/* Everything uses monospace font for that retro feel */ +body, .card, .popover, .input, .button, .menu, .dialog { + font-family: 'IBM Plex Mono', 'Courier New', monospace !important; + background: #c0c0c0 !important; + color: #000 !important; + border-radius: 0 !important; /* No rounded corners */ + box-shadow: none !important; +} -### How Theme Changes Work +/* 3D bevel effect on panels */ +.card, .popover, .menu, .dialog { + border: 2px solid #fff !important; /* Top/left highlight */ + border-bottom: 2px solid #404040 !important; /* Bottom shadow */ + border-right: 2px solid #404040 !important; /* Right shadow */ + padding: 8px !important; + background: #e0e0e0 !important; +} -1. **Configuration Loading**: When a bot loads, it reads theme parameters from `config.csv` -2. **Drive Monitoring**: The `DriveMonitor` watches for changes to the configuration file -3. **Broadcasting**: Theme changes are broadcast to all connected web clients via WebSocket -4. **Dynamic Application**: The web interface applies theme changes without requiring a page refresh +/* Buttons with 3D effect */ +.button, button, input[type="button"], input[type="submit"] { + background: #e0e0e0 !important; + color: #000 !important; + border: 2px solid #fff !important; + border-bottom: 2px solid #404040 !important; + border-right: 2px solid #404040 !important; + padding: 4px 12px !important; + font-weight: bold !important; +} -### Theme Event Structure +/* Input fields look recessed */ +input, textarea, select { + background: #fff !important; + color: #000 !important; + border: 2px solid #404040 !important; /* Reversed for inset look */ + border-bottom: 2px solid #fff !important; + border-right: 2px solid #fff !important; +} -When theme parameters change, the system broadcasts a `change_theme` event: +/* Classic scrollbars */ +::-webkit-scrollbar { + width: 16px !important; + background: #c0c0c0 !important; +} +::-webkit-scrollbar-thumb { + background: #404040 !important; + border: 2px solid #fff !important; + border-bottom: 2px solid #404040 !important; + border-right: 2px solid #404040 !important; +} -```json -{ - "event": "change_theme", - "data": { - "color1": "#0d2b55", - "color2": "#fff9c2", - "logo_url": "https://example.com/logo.svg", - "title": "Custom Title", - "logo_text": "Company Name" - } +/* Blue hyperlinks like Windows 95 */ +a { + color: #0000aa !important; + text-decoration: underline !important; } ``` -## Web Interface Structure +## How Themes Work -The BotServer web interface consists of: +1. **CSS Variables**: Themes use CSS custom properties for colors +2. **Class Targeting**: Style specific bot UI elements +3. **Important Rules**: Override default styles with `!important` +4. **Font Stacks**: Provide fallback fonts for compatibility -### Main Directories -- `web/desktop/` - Desktop web application - - `chat/` - Chat interface components - - `css/` - Stylesheets - - `js/` - JavaScript files - - `public/` - Static assets -- `web/html/` - Simplified HTML interface +## Creating Your Own Theme -### Key Files -- `index.html` - Main application entry point -- `chat/chat.js` - Chat interface logic with theme handling -- `account.html` - User account management -- `settings.html` - Bot settings interface +Start with this template: -## Customization Examples +```css +/* Basic color scheme */ +:root { + --primary: #007bff; + --background: #ffffff; + --text: #333333; + --border: #dee2e6; +} -### Example 1: Corporate Branding +/* Chat container */ +.chat-container { + background: var(--background); + color: var(--text); +} -```csv -name,value -theme-color1,#003366 -theme-color2,#FFD700 -theme-logo,https://company.com/logo.png -theme-title,Corporate Assistant -theme-logo-text,ACME Corp +/* Messages */ +.message-user { + background: var(--primary); + color: white; +} + +.message-bot { + background: var(--border); + color: var(--text); +} + +/* Input area */ +.chat-input { + border: 1px solid var(--border); + background: var(--background); +} ``` -### Example 2: Simple Color Theme +## Switching Themes -```csv -name,value -Theme Color,teal +Use the `CHANGE THEME` keyword in your BASIC scripts: + +```basic +' Switch to retro theme +CHANGE THEME "3dbevel" + +' Back to default +CHANGE THEME "default" + +' Seasonal themes +month = MONTH(NOW()) +IF month = 12 THEN + CHANGE THEME "holiday" +END IF ``` -### Example 3: Educational Institution +## Common Theme Elements -```csv -name,value -theme-color1,#1e3a5f -theme-color2,#f0f0f0 -theme-logo,https://university.edu/seal.svg -theme-title,Campus Assistant -theme-logo-text,State University +### Message Bubbles +```css +.message { + padding: 10px; + margin: 5px; + border-radius: 10px; +} ``` -## Dark Mode Support +### Suggestion Buttons +```css +.suggestion-button { + background: #f0f0f0; + border: 1px solid #ccc; + padding: 8px 16px; + margin: 4px; + cursor: pointer; +} +``` -The web interface includes built-in dark mode support with CSS data attributes: +### Input Field +```css +.chat-input { + width: 100%; + padding: 10px; + font-size: 16px; +} +``` -- Light mode: `[data-theme="light"]` -- Dark mode: `[data-theme="dark"]` +## Theme Best Practices -The interface automatically adjusts colors, backgrounds, and contrast based on the user's theme preference. +1. **Test on Multiple Browsers**: Ensure compatibility +2. **Use Web-Safe Fonts**: Or include font files +3. **High Contrast**: Ensure readability +4. **Mobile Responsive**: Test on different screen sizes +5. **Keep It Simple**: Don't overcomplicate the CSS -## Limitations +## File Naming -Current theming capabilities are limited to: -- Color customization (2 colors) -- Logo replacement -- Title and text changes +- `default.css` - Loaded automatically as main theme +- `dark.css` - Dark mode variant +- `3dbevel.css` - Special theme (Windows 95 style) +- `[name].css` - Any custom theme name -Advanced customization like: -- Custom CSS injection -- Layout modifications -- Component replacement -- Font changes +## Loading Order -...are not currently supported through configuration. For these changes, you would need to modify the web interface source files directly. +1. System default styles +2. Theme CSS file +3. Inline style overrides (if any) -## Best Practices - -1. **Use Web-Safe Colors**: Ensure your color choices have sufficient contrast for accessibility -2. **Logo Format**: Use SVG for logos when possible for better scaling -3. **Logo Hosting**: Host logos on reliable CDNs or your own servers -4. **Title Length**: Keep titles concise to avoid truncation in browser tabs -5. **Test Changes**: Verify theme changes work across different browsers and devices - -## Real-Time Updates - -One of the key features is real-time theme updates. When you modify the `config.csv` file: - -1. Save your changes to `config.csv` -2. The system detects the change automatically -3. All connected clients receive the theme update -4. The interface updates without requiring a refresh - -This makes it easy to experiment with different themes and see results immediately. - -## Next Steps - -- See [Theme Structure](./structure.md) for details on how themes are applied -- See [Web Interface](./web-interface.md) for understanding the UI components -- See [CSS Customization](./css.md) for advanced styling options -- See [HTML Templates](./html.md) for modifying the interface structure \ No newline at end of file +The theme system keeps styling separate from bot logic, making it easy to change the look without touching the code. \ No newline at end of file diff --git a/docs/src/chapter-04/console-mode.md b/docs/src/chapter-04/console-mode.md new file mode 100644 index 000000000..2c675f0d8 --- /dev/null +++ b/docs/src/chapter-04/console-mode.md @@ -0,0 +1,392 @@ +# Console Mode + +BotServer includes a powerful terminal-based UI for monitoring, debugging, and managing bots directly from the console. + +## Overview + +Console mode (`--console`) provides a text-based user interface (TUI) using the terminal for full system control without a web browser. + +## Launching Console Mode + +```bash +# Start BotServer with console UI +./botserver --console + +# Console with specific bot +./botserver --console --bot edu + +# Console with custom refresh rate +./botserver --console --refresh 500 +``` + +## UI Tree Structure + +The console interface uses a tree-based layout for navigation and display: + +``` +β”Œβ”€ BotServer Console ────────────────────────────────┐ +β”‚ β”‚ +β”‚ β–Ό System Status β”‚ +β”‚ β”œβ”€ CPU: 45% β”‚ +β”‚ β”œβ”€ Memory: 2.3GB / 8GB β”‚ +β”‚ β”œβ”€ Uptime: 2d 14h 23m β”‚ +β”‚ └─ Active Sessions: 127 β”‚ +β”‚ β”‚ +β”‚ β–Ό Bots β”‚ +β”‚ β”œβ”€ ● default (8 sessions) β”‚ +β”‚ β”œβ”€ ● edu (45 sessions) β”‚ +β”‚ β”œβ”€ β—‹ crm (offline) β”‚ +β”‚ └─ ● announcements (74 sessions) β”‚ +β”‚ β”‚ +β”‚ β–Ά Services β”‚ +β”‚ β–Ά Logs β”‚ +β”‚ β–Ά Sessions β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +[q]uit [↑↓]navigate [←→]expand [enter]select [h]elp +``` + +## Navigation + +### Keyboard Controls + +| Key | Action | +|-----|--------| +| `↑` `↓` | Navigate up/down | +| `←` `β†’` | Collapse/expand nodes | +| `Enter` | Select/activate item | +| `Tab` | Switch panels | +| `Space` | Toggle item | +| `q` | Quit console | +| `h` | Show help | +| `f` | Filter/search | +| `r` | Refresh display | +| `/` | Quick search | +| `Esc` | Cancel operation | + +### Mouse Support + +When terminal supports mouse: +- Click to select items +- Double-click to expand/collapse +- Scroll wheel for navigation +- Right-click for context menu + +## Console Components + +### System Monitor + +Real-time system metrics display: +``` +System Resources +β”œβ”€ CPU +β”‚ β”œβ”€ Core 0: 23% +β”‚ β”œβ”€ Core 1: 45% +β”‚ β”œβ”€ Core 2: 67% +β”‚ └─ Core 3: 12% +β”œβ”€ Memory +β”‚ β”œβ”€ Used: 4.2GB +β”‚ β”œβ”€ Free: 3.8GB +β”‚ └─ Swap: 0.5GB +└─ Disk + β”œβ”€ /: 45GB/100GB + └─ /data: 234GB/500GB +``` + +### Bot Manager + +Interactive bot control panel: +``` +Bots Management +β”œβ”€ default.gbai [RUNNING] +β”‚ β”œβ”€ Status: Active +β”‚ β”œβ”€ Sessions: 23 +β”‚ β”œβ”€ Memory: 234MB +β”‚ β”œβ”€ Requests/min: 45 +β”‚ └─ Actions +β”‚ β”œβ”€ [R]estart +β”‚ β”œβ”€ [S]top +β”‚ β”œβ”€ [C]onfig +β”‚ └─ [L]ogs +``` + +### Service Dashboard + +Monitor all services: +``` +Services +β”œβ”€ Database [βœ“] +β”‚ β”œβ”€ Type: PostgreSQL +β”‚ β”œβ”€ Connections: 12/100 +β”‚ └─ Response: 2ms +β”œβ”€ Cache [βœ“] +β”‚ β”œβ”€ Type: Valkey +β”‚ β”œβ”€ Memory: 234MB +β”‚ └─ Hit Rate: 94% +β”œβ”€ Storage [βœ“] +β”‚ β”œβ”€ Type: Drive (S3-compatible) +β”‚ β”œβ”€ Buckets: 21 +β”‚ └─ Usage: 45GB +└─ Vector DB [βœ—] + └─ Status: Offline +``` + +### Session Viewer + +Live session monitoring: +``` +Active Sessions +β”œβ”€ Session #4f3a2b1c +β”‚ β”œβ”€ User: john@example.com +β”‚ β”œβ”€ Bot: edu +β”‚ β”œβ”€ Duration: 00:12:34 +β”‚ β”œβ”€ Messages: 23 +β”‚ └─ State: active +β”œβ”€ Session #8d9e7f6a +β”‚ β”œβ”€ User: anonymous +β”‚ β”œβ”€ Bot: default +β”‚ β”œβ”€ Duration: 00:03:21 +β”‚ β”œβ”€ Messages: 7 +β”‚ └─ State: idle +``` + +### Log Viewer + +Filtered log display with levels: +``` +Logs [ERROR|WARN|INFO|DEBUG] +β”œβ”€ 12:34:56 [INFO] Bot 'edu' started +β”œβ”€ 12:34:57 [DEBUG] Session created: 4f3a2b1c +β”œβ”€ 12:34:58 [WARN] Cache miss for key: user_123 +β”œβ”€ 12:35:01 [ERROR] Database connection timeout +β”‚ └─ Details: Connection pool exhausted +β”œβ”€ 12:35:02 [INFO] Reconnecting to database... +``` + +## Console Features + +### Real-time Updates + +- Auto-refresh configurable (100ms - 10s) +- WebSocket-based live data +- Efficient diff rendering +- Smooth scrolling + +### Interactive Commands + +``` +Commands (press : to enter command mode) +:help Show help +:quit Exit console +:restart Restart specific bot +:stop Stop bot +:start Start bot +:clear Clear screen +:export Export logs +:filter Filter display +:connect Connect to session +``` + +### BASIC Debugger Integration + +Debug BASIC scripts directly in console: +``` +BASIC Debugger - enrollment.bas +β”œβ”€ Breakpoints +β”‚ β”œβ”€ Line 12: PARAM validation +β”‚ └─ Line 34: SAVE operation +β”œβ”€ Variables +β”‚ β”œβ”€ name: "John Smith" +β”‚ β”œβ”€ email: "john@example.com" +β”‚ └─ course: "Computer Science" +β”œβ”€ Call Stack +β”‚ β”œβ”€ main() +β”‚ β”œβ”€ validate_input() +β”‚ └─ > save_enrollment() +└─ Controls + [F5]Run [F10]Step [F11]Into [F9]Break +``` + +### Performance Monitoring + +``` +Performance Metrics +β”œβ”€ Response Times +β”‚ β”œβ”€ P50: 45ms +β”‚ β”œβ”€ P90: 123ms +β”‚ β”œβ”€ P95: 234ms +β”‚ └─ P99: 567ms +β”œβ”€ Throughput +β”‚ β”œβ”€ Current: 234 req/s +β”‚ β”œβ”€ Average: 189 req/s +β”‚ └─ Peak: 456 req/s +└─ Errors + β”œβ”€ Rate: 0.02% + └─ Last: 2 min ago +``` + +## Console Layouts + +### Split Views + +``` +β”Œβ”€ Bots ─────────┬─ Logs ──────────┐ +β”‚ β”‚ β”‚ +β”‚ ● default β”‚ [INFO] Ready β”‚ +β”‚ ● edu β”‚ [DEBUG] Session β”‚ +β”‚ β”‚ β”‚ +β”œβ”€ Sessions ─────┼─ Metrics ───────── +β”‚ β”‚ β”‚ +β”‚ 4f3a2b1c β”‚ CPU: 45% β”‚ +β”‚ 8d9e7f6a β”‚ RAM: 2.3GB β”‚ +β”‚ β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Focus Mode + +Press `F` to focus on single component: +``` +β”Œβ”€ Focused: Log Viewer ───────────────┐ +β”‚ β”‚ +β”‚ 12:35:01 [ERROR] Connection failed β”‚ +β”‚ Stack trace: β”‚ +β”‚ at connect() line 234 β”‚ +β”‚ at retry() line 123 β”‚ +β”‚ at main() line 45 β”‚ +β”‚ β”‚ +β”‚ 12:35:02 [INFO] Retrying... β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +[ESC] to exit focus mode +``` + +## Color Schemes + +### Default Theme +- Background: Terminal default +- Text: White +- Headers: Cyan +- Success: Green +- Warning: Yellow +- Error: Red +- Selection: Blue background + +### Custom Themes +Configure in `~/.botserver/console.toml`: +```toml +[colors] +background = "#1e1e1e" +foreground = "#d4d4d4" +selection = "#264f78" +error = "#f48771" +warning = "#dcdcaa" +success = "#6a9955" +``` + +## Console Configuration + +### Settings File +`~/.botserver/console.toml`: +```toml +[general] +refresh_rate = 500 +mouse_support = true +unicode_borders = true +time_format = "24h" + +[layout] +default = "split" +show_tree_lines = true +indent_size = 2 + +[shortcuts] +quit = "q" +help = "h" +filter = "f" +``` + +## Performance Considerations + +### Terminal Requirements +- Minimum 80x24 characters +- 256 color support recommended +- UTF-8 encoding for borders +- Fast refresh rate capability + +### Optimization Tips +- Use `--refresh 1000` for slower terminals +- Disable unicode with `--ascii` +- Limit log tail with `--log-lines 100` +- Filter unnecessary components + +## Remote Console + +### SSH Access +```bash +# SSH with console auto-start +ssh user@server -t "./botserver --console" + +# Persistent session with tmux +ssh user@server -t "tmux attach || tmux new './botserver --console'" +``` + +### Security +- Read-only mode: `--console-readonly` +- Audit logging of console actions +- Session timeout configuration +- IP-based access control + +## Troubleshooting + +### Display Issues + +1. **Garbled characters** + - Set `TERM=xterm-256color` + - Ensure UTF-8 locale + - Try `--ascii` mode + +2. **Slow refresh** + - Increase refresh interval + - Reduce displayed components + - Check network latency (remote) + +3. **Colors not working** + - Verify terminal color support + - Check TERM environment + - Try different terminal emulator + +## Integration with Development Tools + +### VSCode Integration +- Terminal panel for console +- Task runner integration +- Debug console connection + +### Tmux/Screen +- Persistent console sessions +- Multiple console windows +- Session sharing for collaboration + +## Console API + +### Programmatic Access +```python +# Python example +from botserver_console import Console + +console = Console("localhost:8080") +console.connect() + +# Get system stats +stats = console.get_system_stats() +print(f"CPU: {stats.cpu}%") + +# Monitor sessions +for session in console.watch_sessions(): + print(f"Session {session.id}: {session.state}") +``` + +## Summary + +Console mode provides a powerful, efficient interface for managing BotServer without leaving the terminal. Perfect for server administration, debugging, and monitoring in headless environments or over SSH connections. \ No newline at end of file diff --git a/docs/src/chapter-04/desktop-mode.md b/docs/src/chapter-04/desktop-mode.md new file mode 100644 index 000000000..256eaea35 --- /dev/null +++ b/docs/src/chapter-04/desktop-mode.md @@ -0,0 +1,366 @@ +# Desktop Mode & Mobile Apps + +BotServer includes a complete desktop interface and mobile app support for rich conversational experiences beyond simple chat. + +## Overview + +Desktop mode (`--desktop`) transforms BotServer into a full-featured workspace with integrated tools for communication, collaboration, and productivity. + +## Launching Desktop Mode + +```bash +# Start BotServer in desktop mode +./botserver --desktop + +# With custom port +./botserver --desktop --port 8080 + +# Mobile-optimized interface +./botserver --mobile +``` + +## Desktop Components + +### Chat Interface (`/chat`) +The main conversational interface with enhanced features: +- Multi-session support +- File attachments and sharing +- Rich media rendering +- Conversation history +- Quick actions and suggestions +- Voice input/output +- Screen sharing capabilities + +### Attendant (`/attendant`) +AI-powered personal assistant features: +- Calendar integration +- Task management +- Reminders and notifications +- Meeting scheduling +- Contact management +- Email summaries +- Daily briefings + +### Drive Integration (`/drive`) +File management and storage interface: +- Browse object storage buckets +- Upload/download files +- Share documents with chat +- Preview documents +- Organize bot resources +- Version control for files +- Collaborative editing support + +### Mail Client (`/mail`) +Integrated email functionality: +- Send/receive emails through bots +- AI-powered email composition +- Smart inbox filtering +- Email-to-task conversion +- Automated responses +- Template management +- Thread summarization + +### Meeting Room (`/meet`) +Video conferencing and collaboration: +- WebRTC-based video calls +- Screen sharing +- Recording capabilities +- AI meeting notes +- Real-time transcription +- Meeting bot integration +- Calendar sync + +### Task Management (`/tasks`) +Project and task tracking: +- Kanban boards +- Sprint planning +- Time tracking +- Bot automation for tasks +- Progress reporting +- Team collaboration +- Integration with chat + +### Account Settings (`/account.html`) +User profile and preferences: +- Profile management +- Authentication settings +- API keys management +- Subscription details +- Usage statistics +- Privacy controls +- Data export + +### System Settings (`/settings.html`) +Application configuration: +- Theme customization +- Language preferences +- Notification settings +- Bot configurations +- Integration settings +- Performance tuning +- Debug options + +## Mobile Application + +### Progressive Web App (PWA) +BotServer desktop mode works as a PWA: +- Install on mobile devices +- Offline capabilities +- Push notifications +- Native app experience +- Responsive design +- Touch-optimized UI + +### Mobile Features +- Swipe gestures for navigation +- Voice-first interaction +- Location sharing +- Camera integration +- Contact integration +- Mobile-optimized layouts +- Reduced data usage mode + +### Installation on Mobile + +#### Android +1. Open BotServer URL in Chrome +2. Tap "Add to Home Screen" +3. Accept installation prompt +4. Launch from home screen + +#### iOS +1. Open in Safari +2. Tap Share button +3. Select "Add to Home Screen" +4. Name the app and add + +## Desktop Interface Structure + +``` +web/desktop/ +β”œβ”€β”€ index.html # Main desktop dashboard +β”œβ”€β”€ account.html # User account management +β”œβ”€β”€ settings.html # Application settings +β”œβ”€β”€ chat/ # Chat interface components +β”œβ”€β”€ attendant/ # AI assistant features +β”œβ”€β”€ drive/ # File management +β”œβ”€β”€ mail/ # Email client +β”œβ”€β”€ meet/ # Video conferencing +β”œβ”€β”€ tasks/ # Task management +β”œβ”€β”€ css/ # Stylesheets +β”œβ”€β”€ js/ # JavaScript modules +└── public/ # Static assets +``` + +## Features by Screen + +### Dashboard (index.html) +- Widget-based layout +- Quick access tiles +- Recent conversations +- Pending tasks +- Calendar view +- System notifications +- Bot status indicators + +### Chat Screen +- Conversation list +- Message composer +- Rich text formatting +- Code syntax highlighting +- File attachments +- Emoji picker +- Message reactions +- Thread support + +### Drive Screen +- File browser +- Folder navigation +- Upload queue +- Preview pane +- Sharing controls +- Storage metrics +- Search functionality + +### Mail Screen +- Inbox/Sent/Drafts +- Message composer +- Rich HTML editor +- Attachment handling +- Contact autocomplete +- Filter and labels +- Bulk operations + +## Responsive Design + +### Breakpoints +```css +/* Mobile: < 768px */ +/* Tablet: 768px - 1024px */ +/* Desktop: > 1024px */ +/* Wide: > 1440px */ +``` + +### Adaptive Layouts +- Mobile: Single column, bottom navigation +- Tablet: Two-column with collapsible sidebar +- Desktop: Three-column with persistent panels +- Wide: Multi-panel with docked windows + +## Theming + +### CSS Variables +```css +:root { + --primary-color: #0d2b55; + --secondary-color: #fff9c2; + --background: #ffffff; + --text-color: #333333; + --border-color: #e0e0e0; +} +``` + +### Dark Mode +Automatic dark mode based on: +- System preferences +- Time of day +- User selection +- Per-component overrides + +## Performance + +### Optimization Strategies +- Lazy loading of components +- Virtual scrolling for long lists +- Image optimization and CDN +- Code splitting by route +- Service worker caching +- WebAssembly for compute tasks + +### Resource Management +- Maximum 50MB cache size +- Automatic cleanup of old data +- Compressed asset delivery +- Efficient WebSocket usage +- Battery-aware processing + +## Security + +### Authentication +- OAuth2/OIDC support +- Biometric authentication (mobile) +- Session management +- Secure token storage +- Auto-logout on inactivity + +### Data Protection +- End-to-end encryption for sensitive data +- Local storage encryption +- Secure WebSocket connections +- Content Security Policy +- XSS protection + +## Offline Capabilities + +### Service Worker +- Cache-first strategy for assets +- Network-first for API calls +- Background sync for messages +- Offline message queue +- Automatic retry logic + +### Local Storage +- IndexedDB for structured data +- localStorage for preferences +- Cache API for resources +- File system access (desktop) + +## Integration APIs + +### JavaScript SDK +```javascript +// Initialize desktop mode +const desktop = new BotDesktop({ + server: 'ws://localhost:8080', + theme: 'auto', + modules: ['chat', 'drive', 'mail'] +}); + +// Subscribe to events +desktop.on('message', (msg) => { + console.log('New message:', msg); +}); + +// Send commands +desktop.chat.send('Hello from desktop!'); +``` + +## Debugging + +### Developer Tools +- Console logging levels +- Network request inspector +- WebSocket frame viewer +- Performance profiler +- Memory leak detector +- Component tree inspector + +### Debug Mode +```bash +# Enable debug mode +./botserver --desktop --debug + +# Verbose logging +./botserver --desktop --verbose +``` + +## Deployment + +### Web Server Configuration +```nginx +location /desktop { + proxy_pass http://localhost:8080; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; +} +``` + +### CDN Setup +- Static assets on CDN +- Dynamic content from server +- Geographic distribution +- Cache invalidation strategy + +## Troubleshooting + +### Common Issues + +1. **Blank screen on load** + - Check JavaScript console + - Verify WebSocket connection + - Clear browser cache + +2. **Slow performance** + - Reduce active modules + - Clear local storage + - Check network latency + +3. **PWA not installing** + - Ensure HTTPS connection + - Valid manifest.json + - Service worker registered + +## Future Enhancements + +- Native mobile apps (React Native) +- Desktop app (Electron) +- AR/VR interfaces +- Voice-only mode +- Collaborative whiteboards +- Plugin marketplace + +## Summary + +Desktop mode transforms BotServer from a simple chatbot platform into a comprehensive AI-powered workspace. With mobile PWA support, users can access all features from any device while maintaining a consistent, responsive experience. \ No newline at end of file diff --git a/docs/src/chapter-04/web-interface.md b/docs/src/chapter-04/web-interface.md index 10f8be011..203485259 100644 --- a/docs/src/chapter-04/web-interface.md +++ b/docs/src/chapter-04/web-interface.md @@ -1,32 +1,162 @@ # Web Interface -The **gbtheme** web interface provides the front‑end experience for end users. It consists of three core HTML pages and a set of JavaScript modules that handle real‑time communication with the bot server. +The **gbtheme** web interface provides the front-end experience for end users through a simple REST API architecture. -## Pages +## Interface Components -| Page | Purpose | -|------|---------| -| `index.html` | Application shell, loads the main JavaScript bundle and displays the navigation bar. | -| `chat.html` | Primary conversation view – shows the chat transcript, input box, and typing indicator. | -| `login.html` | Simple authentication screen used when the bot is configured with a login flow. | +| Component | Purpose | +|-----------|---------| +| Chat UI | Main conversation interface with input and message display | +| REST API | HTTP endpoints for message exchange | +| CSS Theme | Visual customization through CSS variables | -## JavaScript Modules +## REST API Endpoints -* **app.js** – Initializes the WebSocket connection, routes incoming bot messages to the UI, and sends user input (`TALK`) back to the server. -* **websocket.js** – Low‑level wrapper around the browser’s `WebSocket` API, handling reconnection logic and ping/pong keep‑alive. +The bot communicates through standard HTTP REST endpoints: -## Interaction Flow +``` +POST /api/message Send user message +GET /api/session Get session info +POST /api/upload Upload files +GET /api/history Get conversation history +``` -1. **Load** – `index.html` loads `app.js`, which creates a `WebSocket` to `ws:///ws`. -2. **Handshake** – The server sends a `HELLO` message containing bot metadata (name, version). -3. **User Input** – When the user presses *Enter* in the chat input, `app.js` sends a `TALK` JSON payload. -4. **Bot Response** – The server streams `MESSAGE` events; `app.js` appends them to the chat window. -5. **Typing Indicator** – While the LLM processes, the server sends a `TYPING` event; the UI shows an animated ellipsis. +## Message Flow -## Customization Points +1. **User Input** - User types message in chat interface +2. **API Call** - Frontend sends POST to `/api/message` +3. **Processing** - Server processes with LLM and tools +4. **Response** - JSON response with bot message +5. **Display** - Frontend renders response in chat -* **CSS Variables** – Override colors, fonts, and spacing in `css/main.css` (`:root { --primary-color: … }`). -* **HTML Layout** – Replace the `
` or `