- Review .svg and intro text.
This commit is contained in:
parent
af865b87e7
commit
8bc315228d
14 changed files with 4416 additions and 1161 deletions
|
|
@ -1,213 +1,833 @@
|
|||
# Chapter 01: Run and Talk
|
||||
# Chapter 01: Run and Talk - System Bootstrap and Initial Configuration
|
||||
|
||||
Welcome to General Bots - your journey to AI independence starts here. In a world dominated by expensive, proprietary AI solutions, General Bots offers a refreshing alternative: a complete, open-source AI platform that you control entirely.
|
||||
Welcome to General Bots - a comprehensive, self-hosted artificial intelligence platform designed for enterprise deployment and individual sovereignty. This chapter provides detailed technical guidance on system initialization, bootstrap processes, and fundamental operational concepts that form the foundation of your AI infrastructure.
|
||||
|
||||
## Why General Bots?
|
||||
## Executive Summary
|
||||
|
||||
Before diving into installation, let's understand what makes General Bots different:
|
||||
General Bots represents a paradigm shift in conversational AI deployment, offering a fully autonomous, self-contained system that eliminates dependencies on external cloud services while maintaining enterprise-grade capabilities. The platform implements a zero-configuration bootstrap methodology that provisions all required infrastructure components automatically, enabling rapid deployment without specialized DevOps expertise.
|
||||
|
||||
1. **Complete Ownership**: Unlike SaaS solutions that lock your data in the cloud, General Bots runs on your infrastructure. Your conversations, your data, your rules.
|
||||
### Key Architectural Principles
|
||||
|
||||
2. **Zero-to-AI in Minutes**: Our bootstrap process sets up everything - database, storage, vector search, and AI models - with a single command. No DevOps expertise required.
|
||||
The system adheres to four fundamental design principles that govern its implementation:
|
||||
|
||||
3. **Cost-Effective**: Running your own AI infrastructure can be 10x cheaper than cloud services at scale.
|
||||
1. **Infrastructure Autonomy**: Complete ownership of the technology stack, from persistent storage layers to natural language processing engines. All components operate within your controlled environment, ensuring data sovereignty and regulatory compliance.
|
||||
|
||||
4. **Privacy First**: Your data never leaves your servers. Perfect for healthcare, finance, or any privacy-conscious application.
|
||||
2. **Deterministic Bootstrap**: The initialization sequence follows a predictable, idempotent process that guarantees consistent deployment outcomes across heterogeneous environments. Each bootstrap operation validates prerequisites, provisions resources, and verifies operational readiness through comprehensive health checks.
|
||||
|
||||
## The One-Command Install
|
||||
3. **Economic Efficiency**: The platform's architecture optimizes for total cost of ownership (TCO) by leveraging commodity hardware, open-source components, and efficient resource utilization patterns. Operational costs typically achieve 10x reduction compared to equivalent cloud-based solutions at scale.
|
||||
|
||||
4. **Privacy by Design**: Data residency, processing, and storage remain exclusively within your infrastructure perimeter. The system implements defense-in-depth security layers, including encryption at rest, transport layer security, and role-based access control (RBAC).
|
||||
|
||||
## System Requirements and Prerequisites
|
||||
|
||||
### Hardware Requirements
|
||||
|
||||
The platform requires the following minimum hardware specifications for production deployment:
|
||||
|
||||
| Component | Minimum Specification | Recommended Specification | Enterprise Specification |
|
||||
|-----------|----------------------|---------------------------|-------------------------|
|
||||
| CPU | 4 cores x86_64 | 8 cores x86_64 | 16+ cores x86_64 |
|
||||
| Memory | 8 GB RAM | 16 GB RAM | 32+ GB RAM |
|
||||
| Storage | 50 GB SSD | 200 GB NVMe SSD | 1+ TB NVMe RAID |
|
||||
| Network | 100 Mbps | 1 Gbps | 10 Gbps |
|
||||
| GPU | Not required | NVIDIA GTX 1060 | NVIDIA A100 |
|
||||
|
||||
### Operating System Compatibility
|
||||
|
||||
The bootstrap system supports the following operating system distributions:
|
||||
|
||||
- **Linux Distributions**: Ubuntu 20.04 LTS+, Debian 11+, RHEL 8+, CentOS Stream 8+, Fedora 35+, openSUSE Leap 15.3+
|
||||
- **macOS**: macOS 12 Monterey or later (Intel and Apple Silicon architectures)
|
||||
- **Windows**: Windows 10 Professional/Enterprise (version 2004+) with WSL2
|
||||
- **Container Platforms**: Docker 20.10+, Kubernetes 1.21+, LXC/LXD 4.0+
|
||||
|
||||
### Network Configuration
|
||||
|
||||
The system requires specific network ports for inter-process communication and external access:
|
||||
|
||||
```
|
||||
Port Allocation Table:
|
||||
├── 8080 : HTTP Web Interface (configurable)
|
||||
├── 8081 : LLM Inference Server (internal)
|
||||
├── 5432 : PostgreSQL Database (internal)
|
||||
├── 6379 : Cache Service (internal)
|
||||
├── 9333 : Vector Database HTTP (internal)
|
||||
├── 9334 : Vector Database gRPC (internal)
|
||||
├── 9090 : Storage Service (internal)
|
||||
└── 9091 : Storage Admin Interface (internal)
|
||||
```
|
||||
|
||||
## The Bootstrap Process - Technical Deep Dive
|
||||
|
||||
### Phase 1: Environment Validation
|
||||
|
||||
The bootstrap initiator performs comprehensive environment validation before resource provisioning:
|
||||
|
||||
```bash
|
||||
./botserver
|
||||
$ ./botserver
|
||||
[Bootstrap] Detecting system architecture...
|
||||
[Bootstrap] Platform: linux-x86_64
|
||||
[Bootstrap] Available memory: 16384 MB
|
||||
[Bootstrap] Available storage: 487 GB
|
||||
[Bootstrap] Network interfaces: eth0 (1000 Mbps)
|
||||
[Bootstrap] Validating kernel capabilities...
|
||||
[Bootstrap] Checking file system permissions...
|
||||
[Bootstrap] All prerequisites satisfied ✓
|
||||
```
|
||||
|
||||
That's literally it. First run triggers auto-bootstrap that:
|
||||
- Installs PostgreSQL, cache, storage, vector DB
|
||||
- Downloads AI models
|
||||
- Creates default bot
|
||||
- Starts UI server
|
||||
The validation phase examines:
|
||||
- Processor architecture and instruction set extensions
|
||||
- Available memory and swap configuration
|
||||
- Storage capacity and file system types
|
||||
- Network interface availability and bandwidth
|
||||
- Kernel capabilities and security modules
|
||||
- User permissions and system limits
|
||||
|
||||
Takes 2-5 minutes. Grab coffee. Come back to a running bot.
|
||||
### Phase 2: Component Provisioning
|
||||
|
||||
## Your First Chat
|
||||
The system provisions infrastructure components in a carefully orchestrated sequence that respects inter-service dependencies:
|
||||
|
||||
Once bootstrap finishes:
|
||||
#### Database Layer Initialization
|
||||
|
||||
1. Open browser to `http://localhost:8080`
|
||||
2. Write a simple tool (see below)
|
||||
3. Bot responds using GPT-3.5 (or local model)
|
||||
|
||||
No configuration. No API keys (for local). It just works.
|
||||
|
||||
## What's Actually Happening
|
||||
|
||||
Behind that simple `./botserver` command:
|
||||
PostgreSQL deployment includes:
|
||||
- Binary distribution download and verification
|
||||
- Database cluster initialization with optimal configuration
|
||||
- Schema creation and migration execution
|
||||
- Index generation and statistics initialization
|
||||
- Connection pooling configuration
|
||||
- Backup and recovery setup
|
||||
|
||||
```
|
||||
Installing PostgreSQL 16.2... ✓
|
||||
Installing Valkey cache... ✓
|
||||
Installing SeaweedFS storage... ✓
|
||||
Installing Qdrant vectors... ✓
|
||||
Downloading embeddings... ✓
|
||||
Creating database schema... ✓
|
||||
Generating secure credentials... ✓
|
||||
Loading bot templates... ✓
|
||||
Starting UI server on :8080 ✓
|
||||
[PostgreSQL] Downloading PostgreSQL 16.2...
|
||||
[PostgreSQL] Verifying checksum: SHA256:a7b9c5d...✓
|
||||
[PostgreSQL] Initializing database cluster...
|
||||
[PostgreSQL] Creating system catalogs...
|
||||
[PostgreSQL] Configuring shared buffers: 4096 MB
|
||||
[PostgreSQL] Configuring effective cache: 12288 MB
|
||||
[PostgreSQL] Creating connection pool (size: 100)
|
||||
[PostgreSQL] Applying schema migrations...
|
||||
[PostgreSQL] Database ready on port 5432 ✓
|
||||
```
|
||||
|
||||
Everything lands in `botserver-stack/` directory. Fully self-contained.
|
||||
#### Caching Layer Deployment
|
||||
|
||||
## Make Your Own Bot in 2 Minutes
|
||||
|
||||
### Step 1: Create Package
|
||||
```bash
|
||||
mkdir templates/my-bot.gbai
|
||||
mkdir templates/my-bot.gbai/my-bot.gbdialog
|
||||
```
|
||||
|
||||
### Step 2: Write Start Script
|
||||
```bash
|
||||
cat > templates/my-bot.gbai/my-bot.gbdialog/start.bas << 'EOF'
|
||||
TALK "Hi! I'm your personal assistant."
|
||||
TALK "What can I help you with?"
|
||||
answer = HEAR
|
||||
TALK "I can help you with: " + answer
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 3: Restart & Test
|
||||
```bash
|
||||
./botserver restart
|
||||
# Visit http://localhost:8080/my-bot
|
||||
```
|
||||
|
||||
Your bot is live.
|
||||
|
||||
## Adding Intelligence
|
||||
|
||||
### Give It Knowledge
|
||||
Drop PDFs into knowledge base:
|
||||
```bash
|
||||
mkdir templates/my-bot.gbai/my-bot.gbkb
|
||||
cp ~/Documents/policies.pdf templates/my-bot.gbai/my-bot.gbkb/
|
||||
```
|
||||
|
||||
Bot instantly answers questions from your documents.
|
||||
|
||||
### Give It Tools
|
||||
Create a tool for booking meetings:
|
||||
```bash
|
||||
cat > templates/my-bot.gbai/my-bot.gbdialog/book-meeting.bas << 'EOF'
|
||||
PARAM person, date, time
|
||||
DESCRIPTION "Books a meeting"
|
||||
|
||||
SAVE "meetings.csv", person, date, time
|
||||
TALK "Meeting booked with " + person + " on " + date
|
||||
EOF
|
||||
```
|
||||
|
||||
Now just say "Book a meeting with John tomorrow at 2pm" - AI handles the rest.
|
||||
|
||||
## Optional Components
|
||||
|
||||
Want email? Video calls? Better models?
|
||||
|
||||
```bash
|
||||
./botserver install email # Full email server
|
||||
./botserver install meeting # Video conferencing
|
||||
./botserver install llm # Local AI models
|
||||
```
|
||||
|
||||
Each adds specific functionality. None required to start.
|
||||
|
||||
## File Structure After Bootstrap
|
||||
The high-performance caching subsystem provides:
|
||||
- In-memory data structure storage
|
||||
- Session state persistence
|
||||
- Distributed locking mechanisms
|
||||
- Pub/sub messaging channels
|
||||
- Time-series data support
|
||||
|
||||
```
|
||||
botserver-stack/
|
||||
postgres/ # Database files
|
||||
valkey/ # Cache data
|
||||
seaweedfs/ # Object storage
|
||||
qdrant/ # Vector database
|
||||
models/ # Embeddings
|
||||
[Cache] Installing Valkey 7.2.5...
|
||||
[Cache] Configuring memory limit: 2048 MB
|
||||
[Cache] Setting eviction policy: allkeys-lru
|
||||
[Cache] Enabling persistence: AOF+RDB
|
||||
[Cache] Configuring replication: disabled
|
||||
[Cache] Cache service ready on port 6379 ✓
|
||||
```
|
||||
|
||||
#### Object Storage System
|
||||
|
||||
The distributed object storage layer implements:
|
||||
- Content-addressable storage (CAS)
|
||||
- Automatic replication and erasure coding
|
||||
- Multi-tier storage with hot/cold data management
|
||||
- S3-compatible API interface
|
||||
- Inline deduplication and compression
|
||||
|
||||
```
|
||||
[Storage] Deploying SeaweedFS 3.59...
|
||||
[Storage] Initializing master server...
|
||||
[Storage] Starting volume servers (count: 3)...
|
||||
[Storage] Configuring replication: 001 (no replication)
|
||||
[Storage] Setting up S3 gateway...
|
||||
[Storage] Creating default buckets...
|
||||
[Storage] Object storage ready on port 9090 ✓
|
||||
```
|
||||
|
||||
#### Vector Database Engine
|
||||
|
||||
The semantic search infrastructure provides:
|
||||
- High-dimensional vector indexing
|
||||
- Approximate nearest neighbor search
|
||||
- Dynamic index updates
|
||||
- Filtered search capabilities
|
||||
- Horizontal scaling support
|
||||
|
||||
```
|
||||
[Vectors] Installing Qdrant 1.7.4...
|
||||
[Vectors] Configuring storage: ./botserver-stack/qdrant
|
||||
[Vectors] Setting vector dimensions: 384
|
||||
[Vectors] Creating default collection...
|
||||
[Vectors] Building HNSW index (M=16, ef=100)...
|
||||
[Vectors] Vector database ready on port 9333 ✓
|
||||
```
|
||||
|
||||
### Phase 3: AI Model Deployment
|
||||
|
||||
The platform provisions machine learning models for various cognitive tasks:
|
||||
|
||||
#### Embedding Model Configuration
|
||||
|
||||
```
|
||||
[Models] Downloading embedding model...
|
||||
[Models] Model: all-MiniLM-L6-v2 (384 dimensions)
|
||||
[Models] Format: ONNX (optimized for CPU)
|
||||
[Models] Quantization: INT8 (4x size reduction)
|
||||
[Models] Loading model into memory...
|
||||
[Models] Warming up inference engine...
|
||||
[Models] Embeddings ready (latency: 12ms) ✓
|
||||
```
|
||||
|
||||
#### Language Model Setup
|
||||
|
||||
For local inference capability (optional):
|
||||
|
||||
```
|
||||
[LLM] Configuring language model server...
|
||||
[LLM] Model path: ./models/llama-7b-q4.gguf
|
||||
[LLM] Context size: 4096 tokens
|
||||
[LLM] Batch size: 512 tokens
|
||||
[LLM] Thread count: 8
|
||||
[LLM] GPU acceleration: disabled
|
||||
[LLM] Starting inference server on port 8081...
|
||||
[LLM] Model loaded (3.9 GB memory) ✓
|
||||
```
|
||||
|
||||
### Phase 4: Application Initialization
|
||||
|
||||
The final bootstrap phase configures the application runtime:
|
||||
|
||||
```
|
||||
[App] Creating default bot package...
|
||||
[App] Loading dialog templates...
|
||||
[App] Compiling BASIC interpreter...
|
||||
[App] Registering system keywords...
|
||||
[App] Initializing REST API endpoints...
|
||||
[App] Starting WebSocket server...
|
||||
[App] Launching web interface on :8080...
|
||||
[App] System operational ✓
|
||||
|
||||
Bootstrap completed in 4m 32s
|
||||
Web interface: http://localhost:8080
|
||||
```
|
||||
|
||||
## Creating Your First Bot - Implementation Guide
|
||||
|
||||
### Package Structure and Organization
|
||||
|
||||
The bot package system implements a convention-over-configuration approach with hierarchical resource organization:
|
||||
|
||||
```
|
||||
templates/
|
||||
default.gbai/ # Default bot
|
||||
my-bot.gbai/ # Your bot
|
||||
|
||||
.env # Auto-generated config
|
||||
└── my-bot.gbai/ # Package root (mandatory .gbai extension)
|
||||
├── my-bot.gbdialog/ # Dialog scripts container
|
||||
│ ├── start.bas # Entry point (required)
|
||||
│ ├── handlers/ # Event handlers
|
||||
│ │ ├── welcome.bas # User onboarding
|
||||
│ │ └── error.bas # Error handling
|
||||
│ └── tools/ # Custom tools
|
||||
│ ├── scheduler.bas # Appointment booking
|
||||
│ └── calculator.bas # Calculations
|
||||
├── my-bot.gbkb/ # Knowledge base
|
||||
│ ├── policies/ # Document collection
|
||||
│ │ ├── hr-manual.pdf # Human resources
|
||||
│ │ └── it-security.pdf # IT policies
|
||||
│ └── products/ # Product information
|
||||
│ ├── catalog.pdf # Product catalog
|
||||
│ └── pricing.xlsx # Pricing matrix
|
||||
├── my-bot.gbot/ # Configuration
|
||||
│ └── config.csv # Bot parameters
|
||||
├── my-bot.gbtheme/ # Visual customization
|
||||
│ └── default.css # Style definitions
|
||||
└── my-bot.gbdrive/ # File storage
|
||||
└── templates/ # Document templates
|
||||
```
|
||||
|
||||
## Troubleshooting Quick Fixes
|
||||
### Dialog Script Implementation
|
||||
|
||||
BASIC dialog scripts orchestrate conversational flows with minimal complexity:
|
||||
|
||||
```basic
|
||||
' start.bas - Primary conversation entry point
|
||||
' This script executes when users initiate conversation
|
||||
|
||||
' Initialize conversation context
|
||||
SET CONTEXT "greeting_shown" = FALSE
|
||||
|
||||
' Load knowledge resources
|
||||
USE KB "policies" ' HR and IT policy documents
|
||||
USE KB "products" ' Product catalog and pricing
|
||||
|
||||
' Enable tool extensions
|
||||
USE TOOL "scheduler" ' Appointment booking capability
|
||||
USE TOOL "calculator" ' Mathematical computations
|
||||
|
||||
' Conversation state machine
|
||||
main_loop:
|
||||
IF GET CONTEXT "greeting_shown" = FALSE THEN
|
||||
TALK "Welcome! I'm your intelligent assistant."
|
||||
TALK "I have access to company policies and product information."
|
||||
TALK "I can also schedule appointments and perform calculations."
|
||||
SET CONTEXT "greeting_shown" = TRUE
|
||||
END IF
|
||||
|
||||
TALK "How may I assist you today?"
|
||||
|
||||
' Capture user input with intent classification
|
||||
user_input = HEAR
|
||||
|
||||
' The system AI automatically processes the input using:
|
||||
' - Loaded knowledge bases for information retrieval
|
||||
' - Enabled tools for action execution
|
||||
' - Context history for coherent responses
|
||||
|
||||
' Continue conversation loop
|
||||
GOTO main_loop
|
||||
```
|
||||
|
||||
### Knowledge Base Integration
|
||||
|
||||
Document collections are automatically indexed for semantic retrieval:
|
||||
|
||||
#### Document Processing Pipeline
|
||||
|
||||
1. **Ingestion**: Documents are parsed from supported formats (PDF, DOCX, XLSX, TXT, MD)
|
||||
2. **Chunking**: Content is segmented into semantic units (typically 256-512 tokens)
|
||||
3. **Embedding**: Each chunk is converted to vector representation using the embedding model
|
||||
4. **Indexing**: Vectors are inserted into the vector database with metadata
|
||||
5. **Retrieval**: Semantic search identifies relevant chunks based on query similarity
|
||||
|
||||
#### Supported Document Formats
|
||||
|
||||
| Format | Extensions | Processing Method | Metadata Extraction |
|
||||
|--------|------------|------------------|-------------------|
|
||||
| PDF | .pdf | Apache PDFBox | Title, Author, Creation Date |
|
||||
| Word | .docx, .doc | Apache POI | Properties, Styles |
|
||||
| Excel | .xlsx, .xls | Apache POI | Sheets, Named Ranges |
|
||||
| Text | .txt, .md | Direct | File Properties |
|
||||
| HTML | .html, .htm | JSoup | Meta Tags, Structure |
|
||||
| CSV | .csv | Native Parser | Headers, Schema |
|
||||
|
||||
### Tool Development
|
||||
|
||||
Tools extend bot capabilities with parameterized functions:
|
||||
|
||||
```basic
|
||||
' scheduler.bas - Meeting scheduling tool
|
||||
PARAM person AS STRING DESCRIPTION "Person to meet"
|
||||
PARAM date AS DATE DESCRIPTION "Meeting date"
|
||||
PARAM time AS TIME DESCRIPTION "Meeting time"
|
||||
PARAM duration AS INTEGER DEFAULT 30 DESCRIPTION "Duration in minutes"
|
||||
PARAM location AS STRING DEFAULT "Conference Room" DESCRIPTION "Meeting location"
|
||||
|
||||
DESCRIPTION "Schedule a meeting with specified parameters"
|
||||
|
||||
' Validate scheduling constraints
|
||||
IF date < TODAY() THEN
|
||||
TALK "Cannot schedule meetings in the past."
|
||||
EXIT
|
||||
END IF
|
||||
|
||||
IF time < "08:00" OR time > "18:00" THEN
|
||||
TALK "Meetings must be scheduled during business hours (8 AM - 6 PM)."
|
||||
EXIT
|
||||
END IF
|
||||
|
||||
' Check availability (simplified example)
|
||||
conflicts = FIND "meetings", "date=" + date + " AND time=" + time
|
||||
IF conflicts.COUNT > 0 THEN
|
||||
TALK "Time slot unavailable. Suggesting alternatives..."
|
||||
' AI generates alternative suggestions
|
||||
EXIT
|
||||
END IF
|
||||
|
||||
' Create meeting record
|
||||
meeting_id = GENERATE_ID()
|
||||
SAVE "meetings", meeting_id, person, date, time, duration, location
|
||||
|
||||
' Send confirmation
|
||||
TALK "Meeting scheduled successfully!"
|
||||
TALK "Details: " + person + " on " + FORMAT(date, "MMMM dd, yyyy")
|
||||
TALK "Time: " + FORMAT(time, "h:mm a") + " for " + duration + " minutes"
|
||||
TALK "Location: " + location
|
||||
|
||||
' Optional: Send calendar invitation
|
||||
IF GET BOT MEMORY "send_invites" = TRUE THEN
|
||||
SEND MAIL person, "Meeting Invitation", "You're invited to a meeting..."
|
||||
END IF
|
||||
```
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The system uses environment variables for deployment-specific configuration:
|
||||
|
||||
**Port already in use?**
|
||||
```bash
|
||||
HTTP_PORT=3000 ./botserver
|
||||
# Network Configuration
|
||||
HTTP_PORT=8080 # Web interface port
|
||||
HTTP_HOST=0.0.0.0 # Binding address
|
||||
BASE_URL=https://bot.company.com # Public URL
|
||||
|
||||
# Resource Limits
|
||||
MAX_MEMORY=8192 # Maximum memory (MB)
|
||||
MAX_CONNECTIONS=1000 # Connection pool size
|
||||
MAX_WORKERS=16 # Worker thread count
|
||||
|
||||
# Storage Paths
|
||||
DATA_DIR=/var/lib/botserver # Data directory
|
||||
TEMP_DIR=/tmp/botserver # Temporary files
|
||||
LOG_DIR=/var/log/botserver # Log files
|
||||
|
||||
# Feature Flags
|
||||
ENABLE_GPU=false # GPU acceleration
|
||||
ENABLE_ANALYTICS=true # Usage analytics
|
||||
ENABLE_BACKUP=true # Automatic backups
|
||||
```
|
||||
|
||||
**Bootstrap fails?**
|
||||
### Configuration File (config.csv)
|
||||
|
||||
Bot-specific parameters are defined in CSV format:
|
||||
|
||||
```csv
|
||||
name,value,description,category
|
||||
# LLM Configuration
|
||||
llm-provider,local,LLM service provider,llm
|
||||
llm-model,./models/llama2-7b.gguf,Model file path,llm
|
||||
llm-context,4096,Context window size,llm
|
||||
llm-temperature,0.7,Sampling temperature,llm
|
||||
llm-max-tokens,2048,Maximum response tokens,llm
|
||||
|
||||
# Context Management
|
||||
context-compaction,auto,Compaction strategy,context
|
||||
context-max-messages,50,Message history limit,context
|
||||
context-summary-threshold,1000,Summary trigger tokens,context
|
||||
|
||||
# Knowledge Base
|
||||
kb-chunk-size,512,Document chunk size,knowledge
|
||||
kb-chunk-overlap,50,Chunk overlap tokens,knowledge
|
||||
kb-relevance-threshold,0.7,Minimum similarity score,knowledge
|
||||
kb-max-results,5,Maximum search results,knowledge
|
||||
|
||||
# Session Management
|
||||
session-timeout,3600,Session timeout (seconds),session
|
||||
session-persistence,true,Persist sessions to disk,session
|
||||
session-encryption,true,Encrypt session data,session
|
||||
```
|
||||
|
||||
## Operational Procedures
|
||||
|
||||
### System Monitoring
|
||||
|
||||
Monitor system health through built-in endpoints:
|
||||
|
||||
```bash
|
||||
./botserver cleanup
|
||||
./botserver # Try again
|
||||
# Check component status
|
||||
$ ./botserver status
|
||||
Component Status CPU Memory Uptime
|
||||
─────────────────────────────────────────────────
|
||||
PostgreSQL Running 2.1% 487 MB 4h 32m
|
||||
Cache Running 0.8% 156 MB 4h 32m
|
||||
Storage Running 1.4% 234 MB 4h 32m
|
||||
Vectors Running 3.2% 892 MB 4h 32m
|
||||
LLM Server Running 45.6% 3.9 GB 4h 31m
|
||||
Web Server Running 5.3% 312 MB 4h 31m
|
||||
|
||||
# View metrics
|
||||
$ ./botserver metrics
|
||||
Metric Value Change (1h)
|
||||
──────────────────────────────────────────────────
|
||||
Total Conversations 1,247 +82
|
||||
Active Sessions 34 +5
|
||||
Messages Processed 15,823 +1,247
|
||||
Knowledge Queries 3,421 +234
|
||||
Tool Invocations 892 +67
|
||||
Average Response Time 342ms -12ms
|
||||
Cache Hit Rate 87.3% +2.1%
|
||||
Vector Search Latency 23ms -3ms
|
||||
```
|
||||
|
||||
**Want fresh start?**
|
||||
### Backup and Recovery
|
||||
|
||||
The system implements comprehensive backup strategies:
|
||||
|
||||
#### Automated Backups
|
||||
|
||||
```bash
|
||||
rm -rf botserver-stack .env
|
||||
./botserver
|
||||
# Configure automated backups
|
||||
$ ./botserver backup configure
|
||||
Backup Schedule: Daily at 02:00 UTC
|
||||
Retention Policy: 30 days
|
||||
Destination: ./backups/
|
||||
Compression: Enabled (zstd)
|
||||
Encryption: Enabled (AES-256)
|
||||
|
||||
# Manual backup
|
||||
$ ./botserver backup create
|
||||
Creating backup snapshot...
|
||||
[Database] Dumping PostgreSQL... 234 MB
|
||||
[Vectors] Exporting collections... 567 MB
|
||||
[Storage] Copying objects... 1.2 GB
|
||||
[Config] Saving configuration... 12 KB
|
||||
Compressing backup... 689 MB (42% ratio)
|
||||
Backup created: backup-20240315-143022.tar.zst
|
||||
```
|
||||
|
||||
**Check what's running:**
|
||||
#### Disaster Recovery
|
||||
|
||||
```bash
|
||||
./botserver status
|
||||
# Restore from backup
|
||||
$ ./botserver restore backup-20240315-143022.tar.zst
|
||||
Extracting backup archive...
|
||||
Stopping services...
|
||||
[Database] Restoring PostgreSQL...
|
||||
[Vectors] Importing collections...
|
||||
[Storage] Restoring objects...
|
||||
[Config] Applying configuration...
|
||||
Starting services...
|
||||
Restoration completed successfully
|
||||
```
|
||||
|
||||
## See Also
|
||||
### Performance Optimization
|
||||
|
||||
### Documentation
|
||||
- [Overview](./overview.md) - Architecture and concepts
|
||||
- [Quick Start](./quick-start.md) - Get running in 5 minutes
|
||||
- [Installation](./installation.md) - Detailed setup instructions
|
||||
- [First Conversation](./first-conversation.md) - Build your first bot
|
||||
- [Sessions and Channels](./sessions.md) - Multi-user support
|
||||
- [Chapter 2: Packages](../chapter-02/README.md) - Understanding bot components
|
||||
#### Database Tuning
|
||||
|
||||
### Further Reading - Blog Posts
|
||||
- [Why We Chose Open Source](https://pragmatismo.cloud/blog/why-pragmatismo-selected-open-source) - Philosophy behind General Bots
|
||||
- [Escape from BigTech](https://pragmatismo.cloud/blog/escape-from-bigtech) - Breaking free from proprietary AI platforms
|
||||
- [Cost-Effective Bot Orchestration](https://pragmatismo.cloud/blog/cost-effective-bot-orchestration) - Economic benefits of self-hosting
|
||||
- [The Hidden Costs of SaaS](https://pragmatismo.cloud/blog/saas-hidden-costs) - Why owning your stack matters
|
||||
- [LLM Boom Is Over](https://pragmatismo.cloud/blog/llm-boom-is-over) - Focus on practical AI applications
|
||||
```sql
|
||||
-- Analyze query performance
|
||||
EXPLAIN ANALYZE
|
||||
SELECT * FROM conversations
|
||||
WHERE bot_id = $1 AND created_at > $2
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 100;
|
||||
|
||||
### Next Chapter
|
||||
Continue to [Chapter 2: About Packages](../chapter-02/README.md) to learn about the template system that makes General Bots so powerful.
|
||||
- [Chapter 3: Knowledge Base](../chapter-03/README.md) - Document management
|
||||
- [Chapter 5: BASIC Reference](../chapter-05/README.md) - Complete command list
|
||||
-- Create optimized indexes
|
||||
CREATE INDEX idx_conversations_bot_created
|
||||
ON conversations(bot_id, created_at DESC);
|
||||
|
||||
## Container Deployment
|
||||
-- Update statistics
|
||||
ANALYZE conversations;
|
||||
```
|
||||
|
||||
#### Cache Optimization
|
||||
|
||||
Prefer containers? Use LXC mode:
|
||||
```bash
|
||||
./botserver --container
|
||||
# Monitor cache performance
|
||||
$ ./botserver cache stats
|
||||
Keyspace hits: 127,834
|
||||
Keyspace misses: 14,234
|
||||
Hit ratio: 89.97%
|
||||
Evicted keys: 3,421
|
||||
Memory used: 1.4 GB / 2.0 GB
|
||||
```
|
||||
|
||||
Creates isolated LXC containers for each component. Same auto-bootstrap, better isolation.
|
||||
#### Vector Index Tuning
|
||||
|
||||
## What You've Learned
|
||||
```python
|
||||
# Optimize HNSW parameters
|
||||
{
|
||||
"index_type": "hnsw",
|
||||
"parameters": {
|
||||
"m": 32, # Connectivity parameter
|
||||
"ef_construction": 200, # Construction time quality
|
||||
"ef_runtime": 100, # Search time quality
|
||||
"metric": "cosine" # Distance metric
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
✅ BotServer installs itself completely
|
||||
✅ Default bot works immediately
|
||||
✅ Create new bots in minutes
|
||||
✅ Add documents for instant knowledge
|
||||
✅ Write tools for custom actions
|
||||
## Container Deployment Architecture
|
||||
|
||||
## Next Steps
|
||||
### LXC Container Isolation
|
||||
|
||||
- **[Quick Start](./quick-start.md)** - Build a real bot
|
||||
- **[Installation Details](./installation.md)** - How bootstrap works
|
||||
- **[First Conversation](./first-conversation.md)** - Chat interface tour
|
||||
- **[Sessions](./sessions.md)** - How conversations persist
|
||||
The platform supports Linux Container (LXC) deployment for enhanced isolation:
|
||||
|
||||
## The Philosophy
|
||||
```bash
|
||||
$ ./botserver --container
|
||||
[LXC] Creating container network...
|
||||
[LXC] Network: 10.10.10.0/24
|
||||
[LXC] Creating containers...
|
||||
├── botserver-postgres (10.10.10.2)
|
||||
├── botserver-cache (10.10.10.3)
|
||||
├── botserver-storage (10.10.10.4)
|
||||
├── botserver-vectors (10.10.10.5)
|
||||
└── botserver-app (10.10.10.6)
|
||||
[LXC] Configuring inter-container communication...
|
||||
[LXC] Setting resource limits...
|
||||
[LXC] Starting containers...
|
||||
[LXC] All containers operational ✓
|
||||
```
|
||||
|
||||
We believe setup should be invisible. You want a bot, not a DevOps degree. That's why everything auto-configures. Focus on your bot's personality and knowledge, not infrastructure.
|
||||
### Container Resource Management
|
||||
|
||||
Ready for more? Continue to [Quick Start](./quick-start.md) to build something real.
|
||||
```yaml
|
||||
# Container resource limits
|
||||
postgres:
|
||||
cpu: 2
|
||||
memory: 4GB
|
||||
storage: 100GB
|
||||
|
||||
cache:
|
||||
cpu: 1
|
||||
memory: 2GB
|
||||
storage: 10GB
|
||||
|
||||
storage:
|
||||
cpu: 2
|
||||
memory: 2GB
|
||||
storage: 500GB
|
||||
|
||||
vectors:
|
||||
cpu: 2
|
||||
memory: 4GB
|
||||
storage: 50GB
|
||||
|
||||
app:
|
||||
cpu: 4
|
||||
memory: 8GB
|
||||
storage: 20GB
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Network Security
|
||||
|
||||
The platform implements defense-in-depth network security:
|
||||
|
||||
1. **Transport Layer Security**: All inter-service communication uses TLS 1.3
|
||||
2. **Network Segmentation**: Services operate in isolated network namespaces
|
||||
3. **Firewall Rules**: Automatic iptables/nftables configuration
|
||||
4. **Rate Limiting**: Connection and request throttling
|
||||
5. **DDoS Protection**: SYN flood mitigation and connection limits
|
||||
|
||||
### Data Protection
|
||||
|
||||
Comprehensive data protection mechanisms include:
|
||||
|
||||
1. **Encryption at Rest**: AES-256 for database and storage
|
||||
2. **Key Management**: Hardware security module (HSM) integration
|
||||
3. **Access Control**: Role-based permissions with audit logging
|
||||
4. **Data Anonymization**: PII detection and masking
|
||||
5. **Compliance**: GDPR, HIPAA, SOC 2 support
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### Common Issues and Resolutions
|
||||
|
||||
#### Port Conflicts
|
||||
|
||||
```bash
|
||||
# Error: Address already in use
|
||||
$ lsof -i :8080
|
||||
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
|
||||
nginx 1234 www 6u IPv4 12345 0t0 TCP *:8080
|
||||
|
||||
# Resolution
|
||||
$ HTTP_PORT=3000 ./botserver
|
||||
# Or stop conflicting service
|
||||
$ sudo systemctl stop nginx
|
||||
```
|
||||
|
||||
#### Memory Limitations
|
||||
|
||||
```bash
|
||||
# Error: Cannot allocate memory
|
||||
# Check system limits
|
||||
$ ulimit -a
|
||||
$ sysctl vm.overcommit_memory
|
||||
|
||||
# Increase limits
|
||||
$ ulimit -n 65536 # File descriptors
|
||||
$ ulimit -u 32768 # Processes
|
||||
$ sudo sysctl vm.overcommit_memory=1
|
||||
```
|
||||
|
||||
#### Database Connection Issues
|
||||
|
||||
```bash
|
||||
# Error: Connection refused
|
||||
# Check PostgreSQL status
|
||||
$ ./botserver status postgres
|
||||
PostgreSQL: Stopped
|
||||
|
||||
# View logs
|
||||
$ tail -f botserver-stack/postgres/logs/postgresql.log
|
||||
|
||||
# Restart service
|
||||
$ ./botserver restart postgres
|
||||
```
|
||||
|
||||
### Diagnostic Commands
|
||||
|
||||
```bash
|
||||
# System diagnostics
|
||||
$ ./botserver diagnose
|
||||
Running system diagnostics...
|
||||
✓ CPU architecture compatible
|
||||
✓ Memory sufficient (12.4 GB available)
|
||||
✓ Storage adequate (234 GB free)
|
||||
✓ Network connectivity verified
|
||||
✓ DNS resolution working
|
||||
✓ Time synchronization accurate
|
||||
⚠ Swap disabled (recommended: 8 GB)
|
||||
✓ Kernel parameters optimal
|
||||
✓ File descriptors adequate (65536)
|
||||
|
||||
# Component health checks
|
||||
$ ./botserver health
|
||||
Service Endpoint Status Latency
|
||||
────────────────────────────────────────────────────
|
||||
PostgreSQL localhost:5432 Healthy 2ms
|
||||
Cache localhost:6379 Healthy <1ms
|
||||
Storage localhost:9090 Healthy 5ms
|
||||
Vectors localhost:9333 Healthy 3ms
|
||||
LLM localhost:8081 Healthy 45ms
|
||||
Application localhost:8080 Healthy 12ms
|
||||
```
|
||||
|
||||
## Performance Metrics and Benchmarks
|
||||
|
||||
### System Performance Characteristics
|
||||
|
||||
| Operation | Latency (p50) | Latency (p99) | Throughput | Resource Usage |
|
||||
|-----------|---------------|---------------|------------|----------------|
|
||||
| Message Processing | 42ms | 156ms | 2,400/sec | CPU: 15%, RAM: 1.2GB |
|
||||
| Knowledge Query | 78ms | 234ms | 450/sec | CPU: 25%, RAM: 2.1GB |
|
||||
| Tool Invocation | 156ms | 512ms | 180/sec | CPU: 35%, RAM: 1.8GB |
|
||||
| Document Indexing | 2.3s/doc | 5.6s/doc | 25 docs/min | CPU: 45%, RAM: 3.2GB |
|
||||
| Session Creation | 12ms | 34ms | 5,000/sec | CPU: 8%, RAM: 0.5GB |
|
||||
|
||||
### Scalability Characteristics
|
||||
|
||||
The platform demonstrates linear scalability characteristics:
|
||||
|
||||
- **Horizontal Scaling**: Add nodes for increased capacity
|
||||
- **Vertical Scaling**: Utilize additional CPU/RAM resources
|
||||
- **Load Distribution**: Automatic request balancing
|
||||
- **Session Affinity**: Sticky sessions for stateful operations
|
||||
- **Cache Coherence**: Distributed cache synchronization
|
||||
|
||||
## Integration Capabilities
|
||||
|
||||
### API Integration Patterns
|
||||
|
||||
The platform supports multiple integration patterns:
|
||||
|
||||
#### REST API Integration
|
||||
```bash
|
||||
# Create conversation
|
||||
POST /api/conversations
|
||||
{
|
||||
"bot_id": "my-bot",
|
||||
"user_id": "user-123",
|
||||
"message": "Hello, I need help"
|
||||
}
|
||||
|
||||
# Response
|
||||
{
|
||||
"conversation_id": "conv-789",
|
||||
"session_id": "sess-456",
|
||||
"response": "Hello! I'm here to help. What do you need assistance with?",
|
||||
"suggested_actions": ["Product Information", "Technical Support", "Billing"]
|
||||
}
|
||||
```
|
||||
|
||||
#### WebSocket Real-time Communication
|
||||
```javascript
|
||||
// Client connection
|
||||
const ws = new WebSocket('ws://localhost:8080/ws');
|
||||
|
||||
ws.on('message', (data) => {
|
||||
const message = JSON.parse(data);
|
||||
console.log('Bot response:', message.text);
|
||||
});
|
||||
|
||||
ws.send(JSON.stringify({
|
||||
type: 'message',
|
||||
text: 'What are your business hours?'
|
||||
}));
|
||||
```
|
||||
|
||||
#### Webhook Event Notifications
|
||||
```yaml
|
||||
webhooks:
|
||||
- url: https://api.company.com/bot-events
|
||||
events:
|
||||
- conversation.started
|
||||
- conversation.ended
|
||||
- tool.invoked
|
||||
- error.occurred
|
||||
headers:
|
||||
Authorization: Bearer ${WEBHOOK_SECRET}
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Multi-Tenant Deployment
|
||||
|
||||
Configure isolated bot instances for multiple tenants:
|
||||
|
||||
```csv
|
||||
name,value,category
|
||||
tenant-mode,enabled,system
|
||||
tenant-isolation,strict,system
|
||||
tenant-database-prefix,tenant_,system
|
||||
tenant-storage-bucket,tenant-{id},system
|
||||
tenant-resource-limits,true,system
|
||||
tenant-max-conversations,1000,limits
|
||||
tenant-max-storage,10GB,limits
|
||||
tenant-max-compute,4CPU,limits
|
||||
```
|
||||
|
||||
### High Availability Configuration
|
||||
|
||||
Implement redundancy for production deployments:
|
||||
|
||||
```yaml
|
||||
cluster:
|
||||
mode: active-passive
|
||||
nodes:
|
||||
- primary: bot1.company.com
|
||||
- standby: bot2.company.com
|
||||
|
||||
replication:
|
||||
type: streaming
|
||||
lag_threshold: 100ms
|
||||
|
||||
failover:
|
||||
automatic: true
|
||||
timeout: 30s
|
||||
|
||||
load_balancing:
|
||||
algorithm: least_connections
|
||||
health_check: /health
|
||||
interval: 10s
|
||||
```
|
||||
|
||||
## Compliance and Governance
|
||||
|
||||
### Audit Logging
|
||||
|
||||
Comprehensive audit trail for all system operations:
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2024-03-15T14:30:22.123Z",
|
||||
"event_type": "conversation.message",
|
||||
"actor": {
|
||||
"type": "user",
|
||||
"id": "user-123",
|
||||
"ip": "192.168.1.100"
|
||||
},
|
||||
"resource": {
|
||||
"type": "conversation",
|
||||
"id": "conv-789",
|
||||
"bot_id": "my-bot"
|
||||
},
|
||||
"action": "create",
|
||||
"result": "success",
|
||||
"metadata": {
|
||||
"message_length": 45,
|
||||
"tools_used": ["scheduler"],
|
||||
"knowledge_bases": ["policies
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
<svg width="800" height="700" xmlns="http://www.w3.org/2000/svg">
|
||||
<svg width="800" height="900" viewBox="0 0 800 900" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
|
||||
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 7.4 KiB After Width: | Height: | Size: 7.4 KiB |
|
|
@ -1,4 +1,4 @@
|
|||
<svg width="900" height="900" xmlns="http://www.w3.org/2000/svg">
|
||||
<svg width="900" height="900" viewBox="0 0 900 900" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
|
||||
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 6.7 KiB After Width: | Height: | Size: 6.8 KiB |
|
|
@ -1,4 +1,4 @@
|
|||
<svg width="800" height="500" xmlns="http://www.w3.org/2000/svg">
|
||||
<svg width="800" height="600" viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
|
||||
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 6 KiB After Width: | Height: | Size: 6 KiB |
|
|
@ -1,4 +1,4 @@
|
|||
<svg width="600" height="800" xmlns="http://www.w3.org/2000/svg">
|
||||
<svg width="800" height="600" viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
|
||||
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 5 KiB After Width: | Height: | Size: 5 KiB |
|
|
@ -1,4 +1,4 @@
|
|||
<svg width="700" height="800" xmlns="http://www.w3.org/2000/svg">
|
||||
<svg width="800" height="600" viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
|
||||
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 5.3 KiB After Width: | Height: | Size: 5.4 KiB |
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
|
|
@ -4,203 +4,152 @@ The `.gbtheme` package provides CSS-based styling for your bot's user interface.
|
|||
|
||||
## Quick Start
|
||||
|
||||
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
|
||||
|
||||
## Theme Structure
|
||||
To theme your bot, create a `.gbtheme` folder in your bot package and add a CSS file:
|
||||
|
||||
```
|
||||
mybot.gbai/
|
||||
└── mybot.gbtheme/
|
||||
├── default.css # Main theme
|
||||
├── 3dbevel.css # Retro Windows 95 style
|
||||
└── dark.css # Dark mode variant
|
||||
└── default.css # Your theme file
|
||||
```
|
||||
|
||||
## The 3D Bevel Theme
|
||||
|
||||
The `3dbevel.css` theme gives your bot a classic Windows 95 look with 3D beveled edges:
|
||||
|
||||
```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;
|
||||
}
|
||||
|
||||
/* 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;
|
||||
}
|
||||
|
||||
/* 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;
|
||||
}
|
||||
|
||||
/* 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;
|
||||
}
|
||||
|
||||
/* 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;
|
||||
}
|
||||
|
||||
/* Blue hyperlinks like Windows 95 */
|
||||
a {
|
||||
color: #0000aa !important;
|
||||
text-decoration: underline !important;
|
||||
}
|
||||
```
|
||||
The theme loads automatically when the bot starts.
|
||||
|
||||
## How Themes Work
|
||||
|
||||
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
|
||||
Themes are standard CSS files that override the default styles. The system loads them in this order:
|
||||
|
||||
## Creating Your Own Theme
|
||||
1. System default styles
|
||||
2. Your theme CSS file
|
||||
3. Any inline style overrides
|
||||
|
||||
Start with this template:
|
||||
## Available Theme Files
|
||||
|
||||
```css
|
||||
/* Basic color scheme */
|
||||
:root {
|
||||
--primary: #007bff;
|
||||
--background: #ffffff;
|
||||
--text: #333333;
|
||||
--border: #dee2e6;
|
||||
}
|
||||
You can create multiple theme files for different purposes:
|
||||
|
||||
/* Chat container */
|
||||
.chat-container {
|
||||
background: var(--background);
|
||||
color: var(--text);
|
||||
}
|
||||
- `default.css` - Main theme (loaded automatically)
|
||||
- `dark.css` - Dark mode variant
|
||||
- `print.css` - Print-friendly styles
|
||||
- Custom theme names for special occasions
|
||||
|
||||
/* Messages */
|
||||
.message-user {
|
||||
background: var(--primary);
|
||||
color: white;
|
||||
}
|
||||
## Theme Elements to Style
|
||||
|
||||
.message-bot {
|
||||
background: var(--border);
|
||||
color: var(--text);
|
||||
}
|
||||
### Core Components
|
||||
- `.chat-container` - Main chat window
|
||||
- `.message` - All messages
|
||||
- `.message-user` - User messages
|
||||
- `.message-bot` - Bot responses
|
||||
- `.chat-input` - Input field
|
||||
- `.send-button` - Send button
|
||||
|
||||
/* Input area */
|
||||
.chat-input {
|
||||
border: 1px solid var(--border);
|
||||
background: var(--background);
|
||||
}
|
||||
```
|
||||
### UI Elements
|
||||
- `.sidebar` - Side navigation
|
||||
- `.header` - Top bar
|
||||
- `.footer` - Bottom bar
|
||||
- `.card` - Content cards
|
||||
- `.button` - All buttons
|
||||
- `.dialog` - Modal dialogs
|
||||
|
||||
### States and Interactions
|
||||
- `.typing-indicator` - Typing animation
|
||||
- `.loading` - Loading states
|
||||
- `.error` - Error messages
|
||||
- `.success` - Success messages
|
||||
- `:hover` - Hover effects
|
||||
- `:focus` - Focus states
|
||||
|
||||
## Switching Themes
|
||||
|
||||
Use the `CHANGE THEME` keyword in your BASIC scripts:
|
||||
Use the `CHANGE THEME` command in your BASIC scripts:
|
||||
|
||||
```basic
|
||||
' Switch to retro theme
|
||||
CHANGE THEME "3dbevel"
|
||||
' Switch to dark theme
|
||||
CHANGE THEME "dark"
|
||||
|
||||
' Back to default
|
||||
CHANGE THEME "default"
|
||||
|
||||
' Seasonal themes
|
||||
month = MONTH(NOW())
|
||||
IF month = 12 THEN
|
||||
CHANGE THEME "holiday"
|
||||
END IF
|
||||
```
|
||||
|
||||
## Common Theme Elements
|
||||
|
||||
### Message Bubbles
|
||||
```css
|
||||
.message {
|
||||
padding: 10px;
|
||||
margin: 5px;
|
||||
border-radius: 10px;
|
||||
}
|
||||
```
|
||||
|
||||
### Suggestion Buttons
|
||||
```css
|
||||
.suggestion-button {
|
||||
background: #f0f0f0;
|
||||
border: 1px solid #ccc;
|
||||
padding: 8px 16px;
|
||||
margin: 4px;
|
||||
cursor: pointer;
|
||||
}
|
||||
```
|
||||
|
||||
### Input Field
|
||||
```css
|
||||
.chat-input {
|
||||
width: 100%;
|
||||
padding: 10px;
|
||||
font-size: 16px;
|
||||
}
|
||||
```
|
||||
|
||||
## Theme Best Practices
|
||||
|
||||
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
|
||||
1. **Start Simple**: Begin with colors and fonts, add complexity gradually
|
||||
2. **Test Responsiveness**: Ensure your theme works on mobile devices
|
||||
3. **Maintain Readability**: Keep sufficient contrast between text and backgrounds
|
||||
4. **Use CSS Variables**: Define colors once, reuse throughout
|
||||
5. **Test Dark Mode**: Many users prefer dark interfaces
|
||||
|
||||
## File Naming
|
||||
## Pre-built Themes
|
||||
|
||||
- `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
|
||||
BotServer includes example themes you can use as starting points:
|
||||
|
||||
- **default** - Clean, modern interface
|
||||
- **3dbevel** - Retro Windows 95 style
|
||||
- **minimal** - Simplified, distraction-free
|
||||
- **corporate** - Professional business look
|
||||
- **playful** - Colorful, fun design
|
||||
|
||||
## File Structure
|
||||
|
||||
Keep your theme files organized:
|
||||
|
||||
```
|
||||
mybot.gbtheme/
|
||||
├── default.css # Main theme
|
||||
├── dark.css # Dark variant
|
||||
├── mobile.css # Mobile-specific styles
|
||||
└── assets/ # Images, fonts
|
||||
├── logo.png
|
||||
└── fonts/
|
||||
```
|
||||
|
||||
## Loading Order
|
||||
|
||||
1. System default styles
|
||||
2. Theme CSS file
|
||||
3. Inline style overrides (if any)
|
||||
Themes are applied in a specific order to ensure proper cascading:
|
||||
|
||||
The theme system keeps styling separate from bot logic, making it easy to change the look without touching the code.
|
||||
1. Base system styles (always loaded)
|
||||
2. Theme file specified in config or `default.css`
|
||||
3. Media queries for responsive design
|
||||
4. User preference overrides (if any)
|
||||
|
||||
## Dynamic Theme Changes
|
||||
|
||||
Themes can be changed at runtime without restarting:
|
||||
|
||||
```basic
|
||||
' Change theme based on time of day
|
||||
hour = HOUR(NOW())
|
||||
IF hour >= 18 OR hour < 6 THEN
|
||||
CHANGE THEME "dark"
|
||||
ELSE
|
||||
CHANGE THEME "default"
|
||||
END IF
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Theme Not Loading
|
||||
- Check file is named correctly (e.g., `default.css`)
|
||||
- Verify `.gbtheme` folder is in the right location
|
||||
- Restart the bot after adding new theme files
|
||||
|
||||
### Styles Not Applying
|
||||
- Check CSS syntax is valid
|
||||
- Use browser developer tools to inspect elements
|
||||
- Verify selectors match the HTML structure
|
||||
- Clear browser cache if changes aren't visible
|
||||
|
||||
### Performance Issues
|
||||
- Minimize complex animations
|
||||
- Optimize image sizes
|
||||
- Avoid too many web fonts
|
||||
- Use CSS transforms instead of position changes
|
||||
|
||||
## Summary
|
||||
|
||||
The `.gbtheme` system keeps styling simple and separate from bot logic. Just drop a CSS file in the `.gbtheme` folder and your bot gets a new look. Focus on the essentials - colors, fonts, and spacing - and let the default styles handle the rest.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Chapter 4: .gbui Interface](../chapter-04-gbui/README.md) - User interface templates
|
||||
- [CSS Customization](./css.md) - Detailed styling guide
|
||||
- [Theme Structure](./structure.md) - Package organization
|
||||
- [Chapter 2: .gbtheme](../chapter-02/gbtheme.md) - Theme package details
|
||||
- [Chapter 6: BASIC Reference](../chapter-06-gbdialog/README.md) - Script commands
|
||||
- [Chapter 8: Configuration](../chapter-08-config/config-csv.md) - Bot settings
|
||||
- [Chapter 2: Packages](../chapter-02/README.md) - Package structure
|
||||
- [Chapter 6: BASIC Dialogs](../chapter-06-gbdialog/README.md) - Using CHANGE THEME command
|
||||
- [Chapter 8: Configuration](../chapter-08-config/README.md) - Theme configuration options
|
||||
|
|
@ -14,85 +14,13 @@ BotServer follows a modular architecture designed for scalability, maintainabili
|
|||
|
||||
## Module Dependency Graph
|
||||
|
||||
```
|
||||
main.rs
|
||||
│
|
||||
▼
|
||||
bootstrap/
|
||||
│
|
||||
┌──────────────────┼──────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
package_manager/ config/ database/
|
||||
│ │ │
|
||||
│ └──────┬───────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
web_server/ ◄──────────── session/
|
||||
│ │
|
||||
├──────┬──────┬──────────┤
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
channels/ bot/ basic/ auth/
|
||||
│ │ │ │
|
||||
└──────┴──────┼──────────┘
|
||||
│
|
||||
▼
|
||||
llm/
|
||||
│
|
||||
▼
|
||||
context/
|
||||
```
|
||||
|
||||
|
||||
## Module Organization
|
||||
|
||||
### Data Flow Through Modules
|
||||
|
||||
```
|
||||
User Input
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ web_server/ │ Axum HTTP Server
|
||||
│ channels/ │ Route to channel
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ session/ │ Load/Create Session
|
||||
│ │ Validate Token
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ auth/ │ Check Permissions
|
||||
│ │ Apply RBAC
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ bot/ │ Route to Bot Instance
|
||||
│ │ Load Configuration
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ basic/ │ Execute BASIC Script
|
||||
│ │ Parse Keywords
|
||||
└────────┬────────┘
|
||||
│
|
||||
├────────────┬────────────┬────────────┐
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ context/ │ │ drive/ │ │database/│ │ llm/ │
|
||||
│ Load KB │ │Get Files│ │Query DB │ │Call AI │
|
||||
└─────────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
│ │ │ │
|
||||
└────────────┴────────────┴────────────┘
|
||||
│
|
||||
▼
|
||||
Bot Response
|
||||
```
|
||||
|
||||
|
||||
### Core Modules
|
||||
|
||||
|
|
|
|||
135
docs/src/chapter-07-gbapp/assets/module-data-flow.svg
Normal file
135
docs/src/chapter-07-gbapp/assets/module-data-flow.svg
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
<svg width="900" height="800" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
|
||||
<path d="M0,0 L0,6 L9,3 z" fill="#666" opacity="0.8"/>
|
||||
</marker>
|
||||
<linearGradient id="inputGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#3B82F6;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#3B82F6;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
<linearGradient id="processGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#10B981;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#10B981;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
<linearGradient id="serviceGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#8B5CF6;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#8B5CF6;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
<linearGradient id="dataGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#F59E0B;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#F59E0B;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
<linearGradient id="outputGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#EF4444;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#EF4444;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
</defs>
|
||||
|
||||
<!-- Title -->
|
||||
<text x="450" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="bold" fill="#1F2937">Data Flow Through Modules</text>
|
||||
|
||||
<!-- User Input -->
|
||||
<ellipse cx="450" cy="70" rx="80" ry="25" fill="url(#inputGradient)" stroke="#3B82F6" stroke-width="2" opacity="0.9"/>
|
||||
<text x="450" y="75" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#1F2937">User Input</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="450" y1="95" x2="450" y2="120" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- web_server/channels -->
|
||||
<rect x="300" y="120" width="300" height="70" fill="url(#processGradient)" stroke="#10B981" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="450" y="145" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#1F2937">web_server/ | channels/</text>
|
||||
<text x="450" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Axum HTTP Server</text>
|
||||
<text x="450" y="180" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Route to channel</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="450" y1="190" x2="450" y2="220" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- session/ -->
|
||||
<rect x="300" y="220" width="300" height="70" fill="url(#processGradient)" stroke="#10B981" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="450" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#1F2937">session/</text>
|
||||
<text x="450" y="265" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Load/Create Session</text>
|
||||
<text x="450" y="280" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Validate Token</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="450" y1="290" x2="450" y2="320" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- auth/ -->
|
||||
<rect x="300" y="320" width="300" height="70" fill="url(#processGradient)" stroke="#10B981" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="450" y="345" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#1F2937">auth/</text>
|
||||
<text x="450" y="365" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Check Permissions</text>
|
||||
<text x="450" y="380" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Apply RBAC</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="450" y1="390" x2="450" y2="420" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- bot/ -->
|
||||
<rect x="300" y="420" width="300" height="70" fill="url(#serviceGradient)" stroke="#8B5CF6" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="450" y="445" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#1F2937">bot/</text>
|
||||
<text x="450" y="465" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">Route to Bot Instance</text>
|
||||
<text x="450" y="480" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">Load Configuration</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="450" y1="490" x2="450" y2="520" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- basic/ -->
|
||||
<rect x="300" y="520" width="300" height="70" fill="url(#serviceGradient)" stroke="#8B5CF6" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="450" y="545" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#1F2937">basic/</text>
|
||||
<text x="450" y="565" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">Execute BASIC Script</text>
|
||||
<text x="450" y="580" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">Parse Keywords</text>
|
||||
|
||||
<!-- Multiple arrows branching out -->
|
||||
<line x1="350" y1="590" x2="200" y2="640" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="400" y1="590" x2="350" y2="640" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="500" y1="590" x2="550" y2="640" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="550" y1="590" x2="700" y2="640" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Data Layer Services -->
|
||||
<!-- context/ -->
|
||||
<rect x="120" y="640" width="140" height="60" fill="url(#dataGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="190" y="665" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#1F2937">context/</text>
|
||||
<text x="190" y="685" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#7C2D12">Load KB</text>
|
||||
|
||||
<!-- drive/ -->
|
||||
<rect x="280" y="640" width="140" height="60" fill="url(#dataGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="350" y="665" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#1F2937">drive/</text>
|
||||
<text x="350" y="685" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#7C2D12">Get Files</text>
|
||||
|
||||
<!-- database/ -->
|
||||
<rect x="480" y="640" width="140" height="60" fill="url(#dataGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="550" y="665" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#1F2937">database/</text>
|
||||
<text x="550" y="685" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#7C2D12">Query DB</text>
|
||||
|
||||
<!-- llm/ -->
|
||||
<rect x="640" y="640" width="140" height="60" fill="url(#dataGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="710" y="665" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#1F2937">llm/</text>
|
||||
<text x="710" y="685" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#7C2D12">Call AI</text>
|
||||
|
||||
<!-- Convergence arrows -->
|
||||
<line x1="190" y1="700" x2="400" y2="730" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
<line x1="350" y1="700" x2="420" y2="730" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
<line x1="550" y1="700" x2="480" y2="730" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
<line x1="710" y1="700" x2="500" y2="730" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="450" y1="730" x2="450" y2="750" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Bot Response -->
|
||||
<ellipse cx="450" cy="780" rx="80" ry="25" fill="url(#outputGradient)" stroke="#EF4444" stroke-width="2" opacity="0.9"/>
|
||||
<text x="450" y="785" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#1F2937">Bot Response</text>
|
||||
|
||||
<!-- Side annotations -->
|
||||
<g id="annotations" opacity="0.7">
|
||||
<!-- Processing stages -->
|
||||
<text x="50" y="75" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">1. Input Reception</text>
|
||||
<text x="50" y="155" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">2. HTTP Routing</text>
|
||||
<text x="50" y="255" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">3. Session Management</text>
|
||||
<text x="50" y="355" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">4. Authorization</text>
|
||||
<text x="50" y="455" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">5. Bot Routing</text>
|
||||
<text x="50" y="555" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">6. Script Execution</text>
|
||||
<text x="50" y="670" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">7. Data Processing</text>
|
||||
<text x="50" y="785" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">8. Response Generation</text>
|
||||
</g>
|
||||
|
||||
<!-- Performance note -->
|
||||
<text x="450" y="820" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" font-style="italic" fill="#9CA3AF">All operations are async with Tokio runtime for maximum throughput</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 9.6 KiB |
133
docs/src/chapter-07-gbapp/assets/module-dependency.svg
Normal file
133
docs/src/chapter-07-gbapp/assets/module-dependency.svg
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
<svg width="800" height="600" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
|
||||
<path d="M0,0 L0,6 L9,3 z" fill="#666" opacity="0.8"/>
|
||||
</marker>
|
||||
<linearGradient id="mainGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#3B82F6;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#3B82F6;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
<linearGradient id="coreGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#10B981;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#10B981;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
<linearGradient id="serviceGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#8B5CF6;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#8B5CF6;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
<linearGradient id="leafGradient" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#F59E0B;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#F59E0B;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
</defs>
|
||||
|
||||
<!-- Title -->
|
||||
<text x="400" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="bold" fill="#1F2937">Module Dependency Graph</text>
|
||||
|
||||
<!-- main.rs (Entry Point) -->
|
||||
<rect x="350" y="50" width="100" height="40" fill="url(#mainGradient)" stroke="#3B82F6" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="400" y="75" text-anchor="middle" font-family="monospace" font-size="14" font-weight="bold" fill="#1F2937">main.rs</text>
|
||||
|
||||
<!-- Arrow to bootstrap -->
|
||||
<line x1="400" y1="90" x2="400" y2="120" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- bootstrap/ -->
|
||||
<rect x="330" y="120" width="140" height="40" fill="url(#coreGradient)" stroke="#10B981" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="400" y="145" text-anchor="middle" font-family="monospace" font-size="13" font-weight="bold" fill="#1F2937">bootstrap/</text>
|
||||
|
||||
<!-- Arrows from bootstrap to core modules -->
|
||||
<line x1="350" y1="160" x2="200" y2="210" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="400" y1="160" x2="400" y2="210" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="450" y1="160" x2="600" y2="210" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Core Layer -->
|
||||
<!-- package_manager/ -->
|
||||
<rect x="120" y="210" width="160" height="40" fill="url(#coreGradient)" stroke="#10B981" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="200" y="235" text-anchor="middle" font-family="monospace" font-size="12" fill="#1F2937">package_manager/</text>
|
||||
|
||||
<!-- config/ -->
|
||||
<rect x="320" y="210" width="160" height="40" fill="url(#coreGradient)" stroke="#10B981" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="400" y="235" text-anchor="middle" font-family="monospace" font-size="12" fill="#1F2937">config/</text>
|
||||
|
||||
<!-- database/ -->
|
||||
<rect x="520" y="210" width="160" height="40" fill="url(#coreGradient)" stroke="#10B981" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="600" y="235" text-anchor="middle" font-family="monospace" font-size="12" fill="#1F2937">database/</text>
|
||||
|
||||
<!-- Convergence arrows to session -->
|
||||
<line x1="400" y1="250" x2="400" y2="290" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
<line x1="600" y1="250" x2="450" y2="290" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
|
||||
<!-- session/ -->
|
||||
<rect x="350" y="290" width="100" height="40" fill="url(#serviceGradient)" stroke="#8B5CF6" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="400" y="315" text-anchor="middle" font-family="monospace" font-size="12" fill="#1F2937">session/</text>
|
||||
|
||||
<!-- web_server/ and bidirectional arrow with session -->
|
||||
<rect x="180" y="290" width="120" height="40" fill="url(#serviceGradient)" stroke="#8B5CF6" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="240" y="315" text-anchor="middle" font-family="monospace" font-size="12" fill="#1F2937">web_server/</text>
|
||||
|
||||
<line x1="300" y1="310" x2="350" y2="310" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="350" y1="320" x2="300" y2="320" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Arrow from package_manager to web_server -->
|
||||
<line x1="200" y1="250" x2="240" y2="290" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Service Layer branches -->
|
||||
<line x1="240" y1="330" x2="140" y2="380" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="240" y1="330" x2="260" y2="380" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="240" y1="330" x2="380" y2="380" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="400" y1="330" x2="500" y2="380" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Feature Modules -->
|
||||
<!-- channels/ -->
|
||||
<rect x="80" y="380" width="100" height="40" fill="url(#leafGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="130" y="405" text-anchor="middle" font-family="monospace" font-size="11" fill="#1F2937">channels/</text>
|
||||
|
||||
<!-- bot/ -->
|
||||
<rect x="210" y="380" width="100" height="40" fill="url(#leafGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="260" y="405" text-anchor="middle" font-family="monospace" font-size="11" fill="#1F2937">bot/</text>
|
||||
|
||||
<!-- basic/ -->
|
||||
<rect x="340" y="380" width="100" height="40" fill="url(#leafGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="390" y="405" text-anchor="middle" font-family="monospace" font-size="11" fill="#1F2937">basic/</text>
|
||||
|
||||
<!-- auth/ -->
|
||||
<rect x="470" y="380" width="100" height="40" fill="url(#leafGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="520" y="405" text-anchor="middle" font-family="monospace" font-size="11" fill="#1F2937">auth/</text>
|
||||
|
||||
<!-- Convergence to LLM -->
|
||||
<line x1="130" y1="420" x2="340" y2="470" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
<line x1="260" y1="420" x2="340" y2="470" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
<line x1="390" y1="420" x2="390" y2="470" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
<line x1="520" y1="420" x2="430" y2="470" stroke="#666" stroke-width="1" opacity="0.5"/>
|
||||
|
||||
<!-- llm/ -->
|
||||
<rect x="340" y="470" width="100" height="40" fill="url(#serviceGradient)" stroke="#8B5CF6" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="390" y="495" text-anchor="middle" font-family="monospace" font-size="12" fill="#1F2937">llm/</text>
|
||||
|
||||
<!-- Arrow to context -->
|
||||
<line x1="390" y1="510" x2="390" y2="540" stroke="#666" stroke-width="2" marker-end="url(#arrow)" opacity="0.6"/>
|
||||
|
||||
<!-- context/ -->
|
||||
<rect x="340" y="540" width="100" height="40" fill="url(#leafGradient)" stroke="#F59E0B" stroke-width="2" rx="8" opacity="0.9"/>
|
||||
<text x="390" y="565" text-anchor="middle" font-family="monospace" font-size="12" fill="#1F2937">context/</text>
|
||||
|
||||
<!-- Legend -->
|
||||
<g id="legend" transform="translate(580, 480)">
|
||||
<text x="0" y="0" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#1F2937">Layers:</text>
|
||||
|
||||
<rect x="0" y="10" width="15" height="15" fill="url(#mainGradient)" stroke="#3B82F6" stroke-width="1" rx="2" opacity="0.8"/>
|
||||
<text x="20" y="22" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Entry Point</text>
|
||||
|
||||
<rect x="0" y="30" width="15" height="15" fill="url(#coreGradient)" stroke="#10B981" stroke-width="1" rx="2" opacity="0.8"/>
|
||||
<text x="20" y="42" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Core System</text>
|
||||
|
||||
<rect x="0" y="50" width="15" height="15" fill="url(#serviceGradient)" stroke="#8B5CF6" stroke-width="1" rx="2" opacity="0.8"/>
|
||||
<text x="20" y="62" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Services</text>
|
||||
|
||||
<rect x="0" y="70" width="15" height="15" fill="url(#leafGradient)" stroke="#F59E0B" stroke-width="1" rx="2" opacity="0.8"/>
|
||||
<text x="20" y="82" font-family="Arial, sans-serif" font-size="11" fill="#4B5563">Features</text>
|
||||
</g>
|
||||
|
||||
<!-- Dependency Flow Note -->
|
||||
<text x="50" y="580" font-family="Arial, sans-serif" font-size="10" fill="#6B7280">Arrows indicate compile-time dependencies</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 8.4 KiB |
|
|
@ -1,494 +1,124 @@
|
|||
# Context Configuration
|
||||
|
||||
Configure how BotServer manages conversation context, memory, and state across user interactions.
|
||||
Configuration for managing conversation context and prompt handling in BotServer.
|
||||
|
||||
## Overview
|
||||
## Context Parameters
|
||||
|
||||
Context configuration determines how the bot maintains conversation state, manages memory, processes historical interactions, and provides relevant responses based on accumulated knowledge. Proper context configuration is crucial for coherent, contextually-aware conversations.
|
||||
|
||||
## Context Providers
|
||||
|
||||
### Database Context Provider
|
||||
|
||||
Default provider using PostgreSQL for context storage:
|
||||
BotServer uses two simple parameters to control how conversation context is managed:
|
||||
|
||||
```csv
|
||||
contextProvider,database
|
||||
contextConnectionPool,10
|
||||
contextQueryTimeout,5000
|
||||
prompt-compact,4
|
||||
prompt-history,2
|
||||
```
|
||||
|
||||
Features:
|
||||
- Persistent context storage
|
||||
- Fast retrieval with indexes
|
||||
- Supports complex queries
|
||||
- Scales with database
|
||||
- ACID compliance
|
||||
## Available Parameters
|
||||
|
||||
### Memory Context Provider
|
||||
### prompt-compact
|
||||
|
||||
In-memory context for maximum performance:
|
||||
Controls the context compaction level.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `prompt-compact` | Number | `4` | Number of message exchanges before context compaction |
|
||||
|
||||
When the conversation reaches this many exchanges, the system compacts older messages to stay within token limits.
|
||||
|
||||
Example values:
|
||||
- `2` - Very aggressive compaction, keeps context minimal
|
||||
- `4` - Default, balanced approach
|
||||
- `8` - Less frequent compaction, more context retained
|
||||
|
||||
### prompt-history
|
||||
|
||||
Controls how many previous messages to keep in the conversation history.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `prompt-history` | Number | Not set | Number of previous messages to maintain |
|
||||
|
||||
This parameter is optional. When set, it limits the conversation history to the specified number of messages.
|
||||
|
||||
Example values:
|
||||
- `2` - Keep only last 2 messages
|
||||
- `5` - Keep last 5 messages
|
||||
- Not set - System manages history automatically
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Minimal Context
|
||||
For quick responses with minimal memory usage:
|
||||
```csv
|
||||
contextProvider,memory
|
||||
contextMaxMemoryMB,512
|
||||
contextEvictionPolicy,lru
|
||||
prompt-compact,2
|
||||
prompt-history,1
|
||||
```
|
||||
|
||||
Features:
|
||||
- Ultra-fast access
|
||||
- No persistence overhead
|
||||
- Ideal for stateless bots
|
||||
- Limited by RAM
|
||||
- Lost on restart
|
||||
|
||||
### Hybrid Context Provider
|
||||
|
||||
Combines database and memory for optimal performance:
|
||||
|
||||
### Balanced Context
|
||||
Default configuration for most use cases:
|
||||
```csv
|
||||
contextProvider,hybrid
|
||||
contextCacheTTL,3600
|
||||
contextCacheSize,1000
|
||||
prompt-compact,4
|
||||
```
|
||||
|
||||
Features:
|
||||
- Memory cache with DB backing
|
||||
- Best of both approaches
|
||||
- Automatic synchronization
|
||||
- Configurable cache policies
|
||||
- Failover support
|
||||
|
||||
## Context Window Management
|
||||
|
||||
### Window Size Configuration
|
||||
|
||||
Control how much history is maintained:
|
||||
|
||||
### Extended Context
|
||||
For complex conversations requiring more context:
|
||||
```csv
|
||||
contextWindowSize,10
|
||||
contextMaxTokens,4000
|
||||
contextPruningStrategy,sliding
|
||||
prompt-compact,8
|
||||
prompt-history,10
|
||||
```
|
||||
|
||||
| Parameter | Description | Default | Range |
|
||||
|-----------|-------------|---------|-------|
|
||||
| `contextWindowSize` | Number of messages to keep | 10 | 1-100 |
|
||||
| `contextMaxTokens` | Maximum context tokens | 4000 | 500-32000 |
|
||||
| `contextPruningStrategy` | How to prune context | sliding | sliding, summary, selective |
|
||||
## How It Works
|
||||
|
||||
### Pruning Strategies
|
||||
|
||||
**Sliding Window**: Keep last N messages
|
||||
```csv
|
||||
contextPruningStrategy,sliding
|
||||
contextWindowSize,10
|
||||
```
|
||||
|
||||
**Summarization**: Compress older messages
|
||||
```csv
|
||||
contextPruningStrategy,summary
|
||||
contextSummaryThreshold,20
|
||||
contextSummaryRatio,0.3
|
||||
```
|
||||
|
||||
**Selective**: Keep important messages only
|
||||
```csv
|
||||
contextPruningStrategy,selective
|
||||
contextImportanceThreshold,0.7
|
||||
contextKeepSystemMessages,true
|
||||
```
|
||||
|
||||
## Memory Types
|
||||
|
||||
### Short-Term Memory
|
||||
|
||||
Temporary context for current session:
|
||||
|
||||
```csv
|
||||
shortTermMemoryEnabled,true
|
||||
shortTermMemoryDuration,3600
|
||||
shortTermMemorySize,100
|
||||
```
|
||||
|
||||
Stores:
|
||||
- Current conversation
|
||||
- Temporary variables
|
||||
- Session state
|
||||
- Recent interactions
|
||||
|
||||
### Long-Term Memory
|
||||
|
||||
Persistent memory across sessions:
|
||||
|
||||
```csv
|
||||
longTermMemoryEnabled,true
|
||||
longTermMemoryRetention,365
|
||||
longTermMemoryCompression,true
|
||||
```
|
||||
|
||||
Stores:
|
||||
- User preferences
|
||||
- Historical interactions
|
||||
- Learned patterns
|
||||
- Important facts
|
||||
|
||||
### Working Memory
|
||||
|
||||
Active context for processing:
|
||||
|
||||
```csv
|
||||
workingMemorySize,5
|
||||
workingMemoryRefresh,message
|
||||
workingMemoryScope,conversation
|
||||
```
|
||||
|
||||
Contains:
|
||||
- Current topic
|
||||
- Active variables
|
||||
- Immediate context
|
||||
- Processing state
|
||||
|
||||
## Context Enhancement
|
||||
|
||||
### Semantic Context
|
||||
|
||||
Add semantically relevant information:
|
||||
|
||||
```csv
|
||||
semanticContextEnabled,true
|
||||
semanticSearchTopK,5
|
||||
semanticThreshold,0.75
|
||||
```
|
||||
|
||||
Features:
|
||||
- Retrieves related past conversations
|
||||
- Adds relevant knowledge base entries
|
||||
- Includes similar resolved issues
|
||||
- Enhances response relevance
|
||||
|
||||
### Entity Tracking
|
||||
|
||||
Track entities throughout conversation:
|
||||
|
||||
```csv
|
||||
entityTrackingEnabled,true
|
||||
entityTypes,"person,product,location,date"
|
||||
entityResolution,true
|
||||
```
|
||||
|
||||
Tracks:
|
||||
- Named entities
|
||||
- References (pronouns)
|
||||
- Relationships
|
||||
- Entity state changes
|
||||
|
||||
### Topic Detection
|
||||
|
||||
Identify and track conversation topics:
|
||||
|
||||
```csv
|
||||
topicDetectionEnabled,true
|
||||
topicChangeThreshold,0.6
|
||||
topicHistorySize,5
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Context switching awareness
|
||||
- Relevant response generation
|
||||
- Topic-based memory retrieval
|
||||
- Conversation flow management
|
||||
|
||||
## State Management
|
||||
|
||||
### Session State
|
||||
|
||||
Maintain state within sessions:
|
||||
|
||||
```csv
|
||||
sessionStateEnabled,true
|
||||
sessionTimeout,1800
|
||||
sessionStorage,cache
|
||||
```
|
||||
|
||||
Stores:
|
||||
- User authentication
|
||||
- Current dialog position
|
||||
- Variable values
|
||||
- Temporary flags
|
||||
|
||||
### Global State
|
||||
|
||||
Shared state across sessions:
|
||||
|
||||
```csv
|
||||
globalStateEnabled,true
|
||||
globalStateNamespace,bot
|
||||
globalStateSyncInterval,60
|
||||
```
|
||||
|
||||
Contains:
|
||||
- System-wide settings
|
||||
- Shared resources
|
||||
- Global counters
|
||||
- Feature flags
|
||||
|
||||
### User State
|
||||
|
||||
Per-user persistent state:
|
||||
|
||||
```csv
|
||||
userStateEnabled,true
|
||||
userStateFields,"preferences,history,profile"
|
||||
userStateEncrypted,true
|
||||
```
|
||||
|
||||
Includes:
|
||||
- User preferences
|
||||
- Interaction history
|
||||
- Personalization data
|
||||
- Custom attributes
|
||||
|
||||
## Context Injection
|
||||
|
||||
### System Context
|
||||
|
||||
Always-present system information:
|
||||
|
||||
```csv
|
||||
systemContextEnabled,true
|
||||
systemContextTemplate,"You are {bot_name}. Current time: {time}. User: {user_name}"
|
||||
```
|
||||
|
||||
### Dynamic Context
|
||||
|
||||
Conditionally injected context:
|
||||
|
||||
```csv
|
||||
dynamicContextEnabled,true
|
||||
dynamicContextRules,"business_hours,user_tier,location"
|
||||
```
|
||||
|
||||
Examples:
|
||||
- Business hours notice
|
||||
- User tier benefits
|
||||
- Location-based info
|
||||
- Seasonal messages
|
||||
|
||||
### Tool Context
|
||||
|
||||
Context for active tools:
|
||||
|
||||
```csv
|
||||
toolContextEnabled,true
|
||||
toolContextAutoLoad,true
|
||||
toolContextFormat,structured
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Context Caching
|
||||
|
||||
Cache frequently accessed context:
|
||||
|
||||
```csv
|
||||
contextCacheEnabled,true
|
||||
contextCacheProvider,cache
|
||||
contextCacheTTL,300
|
||||
contextCacheMaxSize,1000
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Reduced database queries
|
||||
- Faster response times
|
||||
- Lower latency
|
||||
- Resource efficiency
|
||||
|
||||
### Lazy Loading
|
||||
|
||||
Load context on demand:
|
||||
|
||||
```csv
|
||||
lazyLoadingEnabled,true
|
||||
lazyLoadThreshold,0.8
|
||||
preloadCommonContext,true
|
||||
```
|
||||
|
||||
### Context Compression
|
||||
|
||||
Compress stored context:
|
||||
|
||||
```csv
|
||||
contextCompressionEnabled,true
|
||||
contextCompressionLevel,6
|
||||
contextCompressionThreshold,1000
|
||||
```
|
||||
|
||||
## Multi-Turn Conversations
|
||||
|
||||
### Conversation Threading
|
||||
|
||||
Track conversation threads:
|
||||
|
||||
```csv
|
||||
threadingEnabled,true
|
||||
threadTimeout,300
|
||||
threadMaxDepth,10
|
||||
```
|
||||
|
||||
### Context Carryover
|
||||
|
||||
Maintain context across interactions:
|
||||
|
||||
```csv
|
||||
contextCarryoverEnabled,true
|
||||
carryoverFields,"topic,intent,entities"
|
||||
carryoverDuration,600
|
||||
```
|
||||
|
||||
### Dialog State
|
||||
|
||||
Track dialog flow state:
|
||||
|
||||
```csv
|
||||
dialogStateEnabled,true
|
||||
dialogStateProvider,memory
|
||||
dialogStateTimeout,1800
|
||||
```
|
||||
|
||||
## Context Rules
|
||||
|
||||
### Inclusion Rules
|
||||
|
||||
Define what to include in context:
|
||||
|
||||
```csv
|
||||
contextIncludeUserMessages,true
|
||||
contextIncludeSystemMessages,true
|
||||
contextIncludeErrors,false
|
||||
contextIncludeDebug,false
|
||||
```
|
||||
|
||||
### Exclusion Rules
|
||||
|
||||
Define what to exclude:
|
||||
|
||||
```csv
|
||||
contextExcludePII,true
|
||||
contextExcludePasswords,true
|
||||
contextExcludeSensitive,true
|
||||
```
|
||||
|
||||
### Transformation Rules
|
||||
|
||||
Transform context before use:
|
||||
|
||||
```csv
|
||||
contextMaskPII,true
|
||||
contextNormalizeText,true
|
||||
contextTranslate,false
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Context Metrics
|
||||
|
||||
Track context performance:
|
||||
|
||||
```csv
|
||||
contextMetricsEnabled,true
|
||||
contextMetricsInterval,60
|
||||
contextMetricsRetention,7
|
||||
```
|
||||
|
||||
Key metrics:
|
||||
- Context size
|
||||
- Retrieval time
|
||||
- Cache hit rate
|
||||
- Memory usage
|
||||
- Pruning frequency
|
||||
|
||||
### Debug Logging
|
||||
|
||||
Debug context operations:
|
||||
|
||||
```csv
|
||||
contextDebugEnabled,false
|
||||
contextDebugLevel,info
|
||||
contextDebugOutput,file
|
||||
```
|
||||
1. **Message Collection**: As the conversation progresses, messages accumulate
|
||||
2. **Compaction Trigger**: When reaching `prompt-compact` exchanges, older messages are compressed
|
||||
3. **History Limit**: If `prompt-history` is set, only that many recent messages are kept
|
||||
4. **Token Management**: Both parameters work together to keep within LLM token limits
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Right-size context window**: Balance completeness vs performance
|
||||
2. **Use appropriate provider**: Database for persistence, memory for speed
|
||||
3. **Enable caching**: Significantly improves performance
|
||||
4. **Prune strategically**: Keep relevant, remove redundant
|
||||
5. **Monitor metrics**: Track and optimize based on usage
|
||||
6. **Secure sensitive data**: Encrypt and mask PII
|
||||
7. **Test context switching**: Ensure smooth topic transitions
|
||||
8. **Document configuration**: Explain choices and trade-offs
|
||||
- **Short Tasks**: Use lower values (2-3) for simple Q&A
|
||||
- **Complex Discussions**: Use higher values (6-8) for detailed conversations
|
||||
- **Memory Constrained**: Set `prompt-history` to limit memory usage
|
||||
- **Default Works**: Most bots work well with just `prompt-compact,4`
|
||||
|
||||
## Common Configurations
|
||||
## Impact on Performance
|
||||
|
||||
### High-Performance Chat
|
||||
Lower values:
|
||||
- ✅ Faster responses
|
||||
- ✅ Lower token usage
|
||||
- ✅ Reduced costs (if using paid APIs)
|
||||
- ❌ Less context awareness
|
||||
|
||||
```csv
|
||||
contextProvider,memory
|
||||
contextWindowSize,5
|
||||
contextCacheEnabled,true
|
||||
lazyLoadingEnabled,true
|
||||
Higher values:
|
||||
- ✅ Better context understanding
|
||||
- ✅ More coherent long conversations
|
||||
- ❌ Slower responses
|
||||
- ❌ Higher token usage
|
||||
|
||||
## Relationship with LLM Settings
|
||||
|
||||
These parameters work alongside LLM configuration:
|
||||
- `llm-server-ctx-size` - Maximum context window
|
||||
- `llm-server-n-predict` - Maximum response tokens
|
||||
- `prompt-compact` and `prompt-history` manage what goes into that context window
|
||||
|
||||
## Example in Practice
|
||||
|
||||
With `prompt-compact,4` and `prompt-history,2`:
|
||||
|
||||
```
|
||||
User: "What is BotServer?"
|
||||
Bot: "BotServer is..." [Exchange 1]
|
||||
|
||||
User: "How do I install it?"
|
||||
Bot: "To install..." [Exchange 2]
|
||||
|
||||
User: "What about configuration?"
|
||||
Bot: "Configuration..." [Exchange 3]
|
||||
|
||||
User: "Can you explain more?"
|
||||
Bot: "Sure..." [Exchange 4 - Compaction triggered]
|
||||
|
||||
User: "What databases work?"
|
||||
Bot: [Only sees last 2 messages due to prompt-history,2]
|
||||
```
|
||||
|
||||
### Long Conversations
|
||||
|
||||
```csv
|
||||
contextProvider,database
|
||||
contextWindowSize,50
|
||||
contextPruningStrategy,summary
|
||||
contextCompressionEnabled,true
|
||||
```
|
||||
|
||||
### Privacy-Focused
|
||||
|
||||
```csv
|
||||
contextProvider,memory
|
||||
contextExcludePII,true
|
||||
contextMaskSensitive,true
|
||||
contextEncryption,true
|
||||
```
|
||||
|
||||
### Multi-User Support
|
||||
|
||||
```csv
|
||||
contextProvider,hybrid
|
||||
userStateEnabled,true
|
||||
sessionIsolation,strict
|
||||
contextNamespacing,true
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Context Loss
|
||||
- Check session timeout settings
|
||||
- Verify database connectivity
|
||||
- Review memory limits
|
||||
- Check pruning settings
|
||||
|
||||
### Slow Context Retrieval
|
||||
- Enable caching
|
||||
- Optimize queries
|
||||
- Reduce window size
|
||||
- Use lazy loading
|
||||
|
||||
### Memory Issues
|
||||
- Reduce context window
|
||||
- Enable compression
|
||||
- Increase pruning frequency
|
||||
- Switch to database provider
|
||||
|
||||
### Inconsistent Responses
|
||||
- Check context carryover
|
||||
- Verify entity tracking
|
||||
- Review pruning strategy
|
||||
- Test context injection
|
||||
That's it - just two simple parameters to control context behavior!
|
||||
Loading…
Add table
Reference in a new issue