- Fix .svgs.
This commit is contained in:
parent
983fceca54
commit
6d18019894
37 changed files with 936 additions and 3325 deletions
|
|
@ -1,3 +1,7 @@
|
|||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="400">
|
||||
</div>
|
||||
|
||||
# General Bots Documentation
|
||||
|
||||
Welcome to the **General Bots** documentation. This guide explains how to install, configure, extend, and deploy conversational AI bots using General Bots' template-based package system and BASIC scripting language.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
## Appendix I – Database Model
|
||||
|
||||
|
||||
<img src="./assets/schema-overview.svg" alt="Database Schema Overview" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
The core database schema for GeneralBots is defined in `src/shared/models.rs`. It uses **Diesel** with PostgreSQL and includes the following primary tables:
|
||||
|
||||
|
|
@ -44,3 +44,9 @@ The core database schema for GeneralBots is defined in `src/shared/models.rs`. I
|
|||
- timestamp: Timestamp
|
||||
|
||||
The schema is automatically migrated when the server starts.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -14,12 +14,12 @@ The database schema follows these design principles:
|
|||
|
||||
## Entity Relationship Overview
|
||||
|
||||
|
||||
<img src="./assets/schema-overview.svg" alt="Database Schema Overview" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
### Core Tables Structure
|
||||
## Detailed Schema
|
||||
|
||||
|
||||
<img src="./assets/schema-detailed.svg" alt="Database Entity Details" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
## Schema Categories
|
||||
|
||||
|
|
@ -57,12 +57,12 @@ The database schema follows these design principles:
|
|||
### Session Management Flow
|
||||
### Session Flow
|
||||
|
||||
|
||||
<img src="./assets/session-flow.svg" alt="Session Flow Diagram" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
### Knowledge Base Access Pattern
|
||||
### Knowledge Base Access
|
||||
|
||||
|
||||
<img src="./assets/kb-access.svg" alt="Knowledge Base Access" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
### Primary Relationships
|
||||
|
||||
|
|
|
|||
|
|
@ -1,833 +1,44 @@
|
|||
# Chapter 01: Run and Talk - System Bootstrap and Initial Configuration
|
||||
# Chapter 01: Run and Talk
|
||||
|
||||
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.
|
||||
Get General Bots running in 5 minutes.
|
||||
|
||||
## Executive Summary
|
||||
## What You'll Learn
|
||||
|
||||
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.
|
||||
- How to start General Bots
|
||||
- Your first conversation
|
||||
- How sessions work
|
||||
- Basic bot interaction
|
||||
|
||||
### Key Architectural Principles
|
||||
|
||||
The system adheres to four fundamental design principles that govern its implementation:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
## Quick Start
|
||||
|
||||
Download and run:
|
||||
```bash
|
||||
$ ./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 ✓
|
||||
./botserver
|
||||
```
|
||||
|
||||
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
|
||||
That's it. Everything installs automatically on first run.
|
||||
|
||||
### Phase 2: Component Provisioning
|
||||
## What Happens
|
||||
|
||||
The system provisions infrastructure components in a carefully orchestrated sequence that respects inter-service dependencies:
|
||||
1. **Auto-Bootstrap**: Installs PostgreSQL, cache, storage, and LLM
|
||||
2. **Load Bots**: Finds `.gbai` folders and loads them
|
||||
3. **Start Server**: Opens on `http://localhost:8080`
|
||||
4. **Ready**: Talk to your bot
|
||||
|
||||
#### Database Layer Initialization
|
||||
## First Conversation
|
||||
|
||||
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
|
||||
Open browser, type a message, get a response. Simple.
|
||||
|
||||
```
|
||||
[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 ✓
|
||||
```
|
||||
## Topics Covered
|
||||
|
||||
#### Caching Layer Deployment
|
||||
- [Overview](./overview.md) - What General Bots does
|
||||
- [Quick Start](./quick-start.md) - Get running fast
|
||||
- [Installation](./installation.md) - Detailed setup options
|
||||
- [First Conversation](./first-conversation.md) - Using your bot
|
||||
- [Sessions](./sessions.md) - How conversations are managed
|
||||
|
||||
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
|
||||
---
|
||||
|
||||
```
|
||||
[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/
|
||||
└── 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
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### 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
|
||||
# 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
|
||||
```
|
||||
|
||||
### Backup and Recovery
|
||||
|
||||
The system implements comprehensive backup strategies:
|
||||
|
||||
#### Automated Backups
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
#### Disaster Recovery
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
#### Database Tuning
|
||||
|
||||
```sql
|
||||
-- Analyze query performance
|
||||
EXPLAIN ANALYZE
|
||||
SELECT * FROM conversations
|
||||
WHERE bot_id = $1 AND created_at > $2
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 100;
|
||||
|
||||
-- Create optimized indexes
|
||||
CREATE INDEX idx_conversations_bot_created
|
||||
ON conversations(bot_id, created_at DESC);
|
||||
|
||||
-- Update statistics
|
||||
ANALYZE conversations;
|
||||
```
|
||||
|
||||
#### Cache Optimization
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
#### Vector Index Tuning
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Container Deployment Architecture
|
||||
|
||||
### LXC Container Isolation
|
||||
|
||||
The platform supports Linux Container (LXC) deployment for enhanced isolation:
|
||||
|
||||
```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 ✓
|
||||
```
|
||||
|
||||
### Container Resource Management
|
||||
|
||||
```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
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
@ -4,7 +4,7 @@ BotServer installs itself automatically through the bootstrap process. No manual
|
|||
|
||||
## Bootstrap Flow Diagram
|
||||
|
||||
|
||||
<img src="./assets/bootstrap-process.svg" alt="Auto-Bootstrap Process" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
## System Requirements
|
||||
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ Start chatting with your bot!
|
|||
|
||||
### Bootstrap Flow
|
||||
|
||||
|
||||
<img src="./assets/quick-start-bootstrap.svg" alt="Bootstrap Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
The **automatic bootstrap** process:
|
||||
|
||||
|
|
@ -79,7 +79,7 @@ DRIVE_SECRET=my-secret-key
|
|||
|
||||
### How Tools Work
|
||||
|
||||
|
||||
<img src="./assets/tool-execution-flow.svg" alt="Tool Execution Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
Tools are just `.bas` files. Create `enrollment.bas`:
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ curl -H "Authorization: Bearer secret-token" \
|
|||
## Session Lifecycle
|
||||
|
||||
```
|
||||
|
||||
<img src="./assets/session-states.svg" alt="Session State Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
```
|
||||
|
||||
### Timeouts
|
||||
|
|
@ -82,7 +82,7 @@ session:uuid:last_activity
|
|||
### Data Flow Diagram
|
||||
|
||||
```
|
||||
|
||||
<img src="./assets/session-manager.svg" alt="Session Manager Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
```
|
||||
|
||||
## Session Variables
|
||||
|
|
|
|||
|
|
@ -1,942 +1,76 @@
|
|||
# Chapter 02: Package System Architecture and Component Reference
|
||||
# Chapter 02: About Packages
|
||||
|
||||
The General Bots package system implements a modular, template-based architecture for organizing and deploying conversational AI applications. This chapter provides comprehensive technical documentation on package structure, component types, lifecycle management, and best practices for enterprise deployment.
|
||||
How bots are organized in General Bots.
|
||||
|
||||
## System Overview and Design Philosophy
|
||||
## What You'll Learn
|
||||
|
||||
### Architectural Principles
|
||||
- Package structure (`.gbai` folders)
|
||||
- Dialog scripts in BASIC
|
||||
- Knowledge bases
|
||||
- Configuration basics
|
||||
- How packages load
|
||||
|
||||
The package system adheres to fundamental design principles that ensure scalability, maintainability, and operational efficiency:
|
||||
## Package Structure
|
||||
|
||||
1. **Convention over Configuration**: Packages follow strict naming conventions and directory structures, eliminating configuration overhead while maintaining flexibility for customization.
|
||||
|
||||
2. **Component Isolation**: Each package component operates independently with well-defined interfaces, enabling parallel development and testing workflows.
|
||||
|
||||
3. **Resource Virtualization**: Package resources are abstracted from physical storage, allowing transparent migration between development, staging, and production environments.
|
||||
|
||||
4. **Lazy Loading**: Components load on-demand to optimize memory utilization and reduce startup latency.
|
||||
|
||||
5. **Immutable Deployments**: Package deployments are versioned and immutable, ensuring reproducible behavior and simplified rollback procedures.
|
||||
|
||||
### Package Architecture Layers
|
||||
|
||||
The system implements a multi-layered architecture for package management:
|
||||
A bot is just a folder ending in `.gbai`:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (Bot Logic, Conversations, UI) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Package Layer │
|
||||
│ (.gbai, .gbdialog, .gbkb, .gbot, .gbtheme) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Resource Manager Layer │
|
||||
│ (File System, Object Storage, Vector Database) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Infrastructure Layer │
|
||||
│ (Database, Cache, Message Queue, Search) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
my-bot.gbai/
|
||||
├── my-bot.gbdialog/ # BASIC scripts
|
||||
├── my-bot.gbkb/ # Documents
|
||||
├── my-bot.gbot/ # Configuration
|
||||
├── my-bot.gbtheme/ # Optional styling
|
||||
└── my-bot.gbdrive/ # Optional storage
|
||||
```
|
||||
|
||||
## Package Component Types - Detailed Specification
|
||||
Drop the folder in `templates/`, it loads automatically.
|
||||
|
||||
### Component Type Matrix
|
||||
## Key Concepts
|
||||
|
||||
| Component | Extension | Primary Function | Storage Location | Processing Model | Caching Strategy |
|
||||
|-----------|-----------|-----------------|------------------|------------------|------------------|
|
||||
| Application Interface | `.gbai` | Package container and metadata management | File system + Database | Synchronous initialization | Metadata cached indefinitely |
|
||||
| Dialog Scripts | `.gbdialog` | Conversation flow orchestration | Object storage | Interpreted at runtime | Script AST cached per session |
|
||||
| Knowledge Bases | `.gbkb` | Document storage and semantic search | Vector DB + Object storage | Asynchronous indexing | Embeddings cached permanently |
|
||||
| Bot Configuration | `.gbot` | Runtime parameters and settings | Database | Loaded at startup | Configuration cached until restart |
|
||||
| UI Themes | `.gbtheme` | Visual styling and branding | Object storage | Loaded per request | CSS cached with ETags |
|
||||
| File Storage | `.gbdrive` | General-purpose file management | Object storage | On-demand access | Files cached based on LRU policy |
|
||||
### Dialogs (.gbdialog)
|
||||
- BASIC scripts that control conversation
|
||||
- Must have `start.bas` as entry point
|
||||
- Simple commands like TALK and HEAR
|
||||
|
||||
### Component Specifications
|
||||
### Knowledge Base (.gbkb)
|
||||
- Put PDFs and documents in folders
|
||||
- Automatically becomes searchable
|
||||
- Bot can answer questions from documents
|
||||
|
||||
#### .gbai - Application Interface Container
|
||||
### Configuration (.gbot)
|
||||
- Single `config.csv` file
|
||||
- Simple name,value pairs
|
||||
- Missing values use defaults
|
||||
|
||||
The `.gbai` directory serves as the root container for all bot resources:
|
||||
### Themes (.gbtheme)
|
||||
- Optional CSS styling
|
||||
- Most bots don't need this
|
||||
|
||||
```
|
||||
Technical Specifications:
|
||||
├── Format: Directory with .gbai extension
|
||||
├── Naming: Lowercase alphanumeric with hyphens
|
||||
├── Location: templates/ directory
|
||||
├── Discovery: Automatic during bootstrap
|
||||
├── Validation: Checked for required subdirectories
|
||||
└── Metadata: Stored in database with UUID
|
||||
```
|
||||
### Storage (.gbdrive)
|
||||
- Links to S3-compatible storage
|
||||
- For large files and uploads
|
||||
|
||||
**Directory Structure Requirements:**
|
||||
```
|
||||
bot-name.gbai/ # Root container (required)
|
||||
├── bot-name.gbdialog/ # Dialog scripts (required)
|
||||
│ └── start.bas # Entry point (required)
|
||||
├── bot-name.gbkb/ # Knowledge base (optional)
|
||||
│ └── [collection-name]/ # Document collections
|
||||
├── bot-name.gbot/ # Configuration (optional)
|
||||
│ └── config.csv # Settings file
|
||||
├── bot-name.gbtheme/ # Theming (optional)
|
||||
│ └── default.css # Style definitions
|
||||
└── bot-name.gbdrive/ # File storage (optional)
|
||||
└── [arbitrary structure] # User-defined organization
|
||||
```
|
||||
## How It Works
|
||||
|
||||
#### .gbdialog - BASIC Script Processing Engine
|
||||
1. **Discovery**: Finds `.gbai` folders
|
||||
2. **Loading**: Reads all components
|
||||
3. **Indexing**: Processes documents
|
||||
4. **Activation**: Bot is ready
|
||||
|
||||
Dialog components implement conversation logic through BASIC scripts:
|
||||
No build process. No compilation. Just folders and files.
|
||||
|
||||
```
|
||||
Processing Pipeline:
|
||||
1. Script Discovery → File system scan for *.bas files
|
||||
2. Syntax Validation → Parser verification of BASIC syntax
|
||||
3. AST Generation → Abstract syntax tree construction
|
||||
4. Optimization → Dead code elimination, constant folding
|
||||
5. Registration → Script registration in execution context
|
||||
6. Execution → Runtime interpretation with context injection
|
||||
```
|
||||
## Topics Covered
|
||||
|
||||
**Script File Specifications:**
|
||||
```basic
|
||||
' File: example.bas
|
||||
' Encoding: UTF-8
|
||||
' Line endings: LF (Unix) or CRLF (Windows)
|
||||
' Maximum file size: 1 MB
|
||||
' Maximum line length: 1024 characters
|
||||
' Maximum script complexity: 10,000 AST nodes
|
||||
- [.gbai Architecture](./gbai.md) - Package details
|
||||
- [.gbdialog Dialogs](./gbdialog.md) - BASIC scripting
|
||||
- [.gbkb Knowledge Base](./gbkb.md) - Document management
|
||||
- [.gbot Configuration](./gbot.md) - Settings
|
||||
- [.gbtheme UI Theming](./gbtheme.md) - Styling
|
||||
- [.gbdrive File Storage](./gbdrive.md) - Storage integration
|
||||
- [Bot Templates](./templates.md) - Example bots
|
||||
|
||||
' Metadata declarations (optional)
|
||||
META AUTHOR "Engineering Team"
|
||||
META VERSION "1.0.0"
|
||||
META DESCRIPTION "Customer service dialog"
|
||||
---
|
||||
|
||||
' Parameter declarations for tools
|
||||
PARAM customer_id AS STRING
|
||||
PARAM issue_type AS STRING
|
||||
|
||||
' Main script body
|
||||
MAIN:
|
||||
' Script implementation
|
||||
TALK "Processing customer request..."
|
||||
```
|
||||
|
||||
#### .gbkb - Knowledge Base and Vector Search System
|
||||
|
||||
Knowledge base packages implement semantic document search capabilities:
|
||||
|
||||
```
|
||||
Document Processing Workflow:
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Document │────▶│ Chunking │────▶│ Embedding │
|
||||
│ Ingestion │ │ Pipeline │ │ Generation │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Metadata │ │ Index │ │ Vector │
|
||||
│ Extraction │ │ Building │ │ Storage │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**Collection Configuration:**
|
||||
```yaml
|
||||
# Collection metadata (auto-generated)
|
||||
collection_name: technical_documentation
|
||||
document_count: 1,247
|
||||
total_chunks: 15,823
|
||||
embedding_model: all-MiniLM-L6-v2
|
||||
vector_dimensions: 384
|
||||
index_type: HNSW
|
||||
distance_metric: cosine
|
||||
chunk_size: 512
|
||||
chunk_overlap: 50
|
||||
```
|
||||
|
||||
**Supported Document Formats and Processing:**
|
||||
|
||||
| Format | MIME Type | Parser | Max Size | Features |
|
||||
|--------|-----------|--------|----------|----------|
|
||||
| PDF | application/pdf | Apache PDFBox | 100 MB | Text, images, metadata |
|
||||
| Word | application/vnd.openxmlformats | Apache POI | 50 MB | Formatted text, tables |
|
||||
| Excel | application/vnd.ms-excel | Apache POI | 25 MB | Sheets, formulas |
|
||||
| PowerPoint | application/vnd.ms-powerpoint | Apache POI | 50 MB | Slides, notes |
|
||||
| Text | text/plain | Native | 10 MB | Plain text |
|
||||
| Markdown | text/markdown | CommonMark | 10 MB | Formatted text |
|
||||
| HTML | text/html | JSoup | 10 MB | Structured content |
|
||||
| CSV | text/csv | Apache Commons | 100 MB | Tabular data |
|
||||
| JSON | application/json | Jackson | 10 MB | Structured data |
|
||||
| XML | application/xml | JAXB | 10 MB | Structured data |
|
||||
|
||||
#### .gbot - Configuration Management System
|
||||
|
||||
The configuration system uses a simple CSV format with name-value pairs:
|
||||
|
||||
```csv
|
||||
# config.csv - Actual Bot Configuration Format
|
||||
# Simple name,value pairs with optional empty rows for visual grouping
|
||||
|
||||
name,value
|
||||
|
||||
# Server Configuration
|
||||
server-host,0.0.0.0
|
||||
server-port,8080
|
||||
sites-root,/tmp
|
||||
|
||||
# LLM Configuration
|
||||
llm-key,none
|
||||
llm-url,http://localhost:8081
|
||||
llm-model,../../../../data/llm/DeepSeek-R1-Distill-Qwen-1.5B-Q3_K_M.gguf
|
||||
|
||||
# LLM Cache Settings
|
||||
llm-cache,false
|
||||
llm-cache-ttl,3600
|
||||
llm-cache-semantic,true
|
||||
llm-cache-threshold,0.95
|
||||
|
||||
# Prompt Configuration
|
||||
prompt-compact,4
|
||||
|
||||
# MCP Server
|
||||
mcp-server,false
|
||||
|
||||
# Embedding Configuration
|
||||
embedding-url,http://localhost:8082
|
||||
embedding-model,../../../../data/llm/bge-small-en-v1.5-f32.gguf
|
||||
|
||||
# LLM Server Settings (when running embedded)
|
||||
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
|
||||
llm-server-mlock,false
|
||||
llm-server-no-mmap,false
|
||||
|
||||
# Email Configuration
|
||||
email-from,from@domain.com
|
||||
email-server,mail.domain.com
|
||||
email-port,587
|
||||
email-user,user@domain.com
|
||||
email-pass,
|
||||
|
||||
# Custom Database Configuration
|
||||
custom-server,localhost
|
||||
custom-port,5432
|
||||
custom-database,mycustomdb
|
||||
custom-username,
|
||||
custom-password,
|
||||
```
|
||||
|
||||
**Key Configuration Parameters:**
|
||||
|
||||
| Category | Parameter | Description | Default Value |
|
||||
|----------|-----------|-------------|---------------|
|
||||
| **Server** | server-host | Binding address for web interface | 0.0.0.0 |
|
||||
| | server-port | HTTP port for web interface | 8080 |
|
||||
| | sites-root | Directory for generated sites | /tmp |
|
||||
| **LLM** | llm-url | LLM server endpoint | http://localhost:8081 |
|
||||
| | llm-model | Path to GGUF model file | Relative path to model |
|
||||
| | llm-cache | Enable response caching | false |
|
||||
| | prompt-compact | Context compaction level (1-5) | 4 |
|
||||
| **Embeddings** | embedding-url | Embedding server endpoint | http://localhost:8082 |
|
||||
| | embedding-model | Path to embedding model | Relative path to model |
|
||||
| **Email** | email-server | SMTP server address | mail.domain.com |
|
||||
| | email-port | SMTP port | 587 |
|
||||
| | email-from | Sender email address | from@domain.com |
|
||||
|
||||
Note: Empty values are acceptable for optional settings. The system uses sensible defaults when values are not provided.
|
||||
|
||||
#### .gbtheme - UI Styling and Branding System
|
||||
|
||||
Theme packages provide comprehensive visual customization:
|
||||
|
||||
```css
|
||||
/* default.css - Theme Specification Template */
|
||||
|
||||
/* ============================================
|
||||
Color System - CSS Custom Properties
|
||||
============================================ */
|
||||
:root {
|
||||
/* Primary Palette */
|
||||
--color-primary: #007bff;
|
||||
--color-primary-light: #4da3ff;
|
||||
--color-primary-dark: #0056b3;
|
||||
|
||||
/* Neutral Palette */
|
||||
--color-background: #ffffff;
|
||||
--color-surface: #f8f9fa;
|
||||
--color-border: #dee2e6;
|
||||
--color-text: #212529;
|
||||
--color-text-secondary: #6c757d;
|
||||
|
||||
/* Semantic Colors */
|
||||
--color-success: #28a745;
|
||||
--color-warning: #ffc107;
|
||||
--color-error: #dc3545;
|
||||
--color-info: #17a2b8;
|
||||
|
||||
/* Typography System */
|
||||
--font-family-base: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto;
|
||||
--font-family-mono: "SF Mono", Monaco, "Cascadia Code", monospace;
|
||||
--font-size-base: 16px;
|
||||
--font-weight-normal: 400;
|
||||
--font-weight-bold: 600;
|
||||
--line-height-base: 1.5;
|
||||
|
||||
/* Spacing System (8px grid) */
|
||||
--spacing-xs: 4px;
|
||||
--spacing-sm: 8px;
|
||||
--spacing-md: 16px;
|
||||
--spacing-lg: 24px;
|
||||
--spacing-xl: 32px;
|
||||
--spacing-xxl: 48px;
|
||||
|
||||
/* Layout Breakpoints */
|
||||
--breakpoint-sm: 576px;
|
||||
--breakpoint-md: 768px;
|
||||
--breakpoint-lg: 992px;
|
||||
--breakpoint-xl: 1200px;
|
||||
|
||||
/* Animation System */
|
||||
--transition-base: all 0.2s ease-in-out;
|
||||
--animation-fade-in: fadeIn 0.3s ease-in;
|
||||
--animation-slide-up: slideUp 0.3s ease-out;
|
||||
}
|
||||
|
||||
/* ============================================
|
||||
Component Styling
|
||||
============================================ */
|
||||
|
||||
/* Chat Container */
|
||||
.chat-container {
|
||||
background: var(--color-background);
|
||||
border: 1px solid var(--color-border);
|
||||
border-radius: 8px;
|
||||
height: calc(100vh - var(--spacing-xxl));
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
font-family: var(--font-family-base);
|
||||
}
|
||||
|
||||
/* Message Bubbles */
|
||||
.message {
|
||||
padding: var(--spacing-md);
|
||||
margin: var(--spacing-sm);
|
||||
border-radius: 12px;
|
||||
max-width: 70%;
|
||||
word-wrap: break-word;
|
||||
animation: var(--animation-fade-in);
|
||||
}
|
||||
|
||||
.message-user {
|
||||
background: var(--color-primary);
|
||||
color: white;
|
||||
align-self: flex-end;
|
||||
margin-left: auto;
|
||||
border-bottom-right-radius: 4px;
|
||||
}
|
||||
|
||||
.message-bot {
|
||||
background: var(--color-surface);
|
||||
color: var(--color-text);
|
||||
align-self: flex-start;
|
||||
border-bottom-left-radius: 4px;
|
||||
border: 1px solid var(--color-border);
|
||||
}
|
||||
|
||||
/* Input Area */
|
||||
.input-container {
|
||||
display: flex;
|
||||
padding: var(--spacing-md);
|
||||
border-top: 1px solid var(--color-border);
|
||||
background: var(--color-surface);
|
||||
}
|
||||
|
||||
.chat-input {
|
||||
flex: 1;
|
||||
padding: var(--spacing-sm) var(--spacing-md);
|
||||
border: 1px solid var(--color-border);
|
||||
border-radius: 24px;
|
||||
font-size: var(--font-size-base);
|
||||
transition: var(--transition-base);
|
||||
}
|
||||
|
||||
.chat-input:focus {
|
||||
outline: none;
|
||||
border-color: var(--color-primary);
|
||||
box-shadow: 0 0 0 3px rgba(0, 123, 255, 0.1);
|
||||
}
|
||||
|
||||
/* Responsive Design */
|
||||
@media (max-width: 768px) {
|
||||
.message {
|
||||
max-width: 85%;
|
||||
}
|
||||
|
||||
.chat-container {
|
||||
border-radius: 0;
|
||||
height: 100vh;
|
||||
}
|
||||
}
|
||||
|
||||
/* Dark Mode Support */
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root {
|
||||
--color-background: #1a1a1a;
|
||||
--color-surface: #2d2d2d;
|
||||
--color-border: #404040;
|
||||
--color-text: #e0e0e0;
|
||||
--color-text-secondary: #a0a0a0;
|
||||
}
|
||||
}
|
||||
|
||||
/* Print Styles */
|
||||
@media print {
|
||||
.input-container,
|
||||
.sidebar,
|
||||
.toolbar {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.message {
|
||||
break-inside: avoid;
|
||||
max-width: 100%;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### .gbdrive - File Storage and Management System
|
||||
|
||||
Drive packages provide structured file storage with versioning:
|
||||
|
||||
```
|
||||
Storage Architecture:
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (File Operations API) │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Abstraction Layer │
|
||||
│ (Virtual File System Interface) │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Storage Backend │
|
||||
│ (S3-Compatible Object Storage) │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**File Operations and Metadata:**
|
||||
```json
|
||||
{
|
||||
"file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
|
||||
"path": "/templates/invoice-template.docx",
|
||||
"name": "invoice-template.docx",
|
||||
"size": 45678,
|
||||
"mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||||
"created_at": "2024-03-15T10:30:00Z",
|
||||
"modified_at": "2024-03-15T14:45:30Z",
|
||||
"version": 3,
|
||||
"checksum": "sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
|
||||
"metadata": {
|
||||
"author": "Finance Team",
|
||||
"tags": ["template", "invoice", "finance"],
|
||||
"permissions": {
|
||||
"owner": "user:finance-admin",
|
||||
"read": ["group:finance", "group:accounting"],
|
||||
"write": ["user:finance-admin", "group:finance-managers"]
|
||||
}
|
||||
},
|
||||
"versions": [
|
||||
{
|
||||
"version": 1,
|
||||
"created_at": "2024-03-01T09:00:00Z",
|
||||
"size": 44567,
|
||||
"checksum": "sha256:b665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae2"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"created_at": "2024-03-10T11:30:00Z",
|
||||
"size": 45123,
|
||||
"checksum": "sha256:c665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae4"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Package Lifecycle Management
|
||||
|
||||
### Lifecycle Phases
|
||||
|
||||
The package system implements a comprehensive lifecycle management framework:
|
||||
|
||||
```
|
||||
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
|
||||
│Development │───▶│ Build │───▶│ Deploy │───▶│ Runtime │
|
||||
└────────────┘ └────────────┘ └────────────┘ └────────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ Edit │ │ Validate │ │ Upload │ │ Execute │
|
||||
│ Test │ │ Package │ │ Index │ │ Monitor │
|
||||
│ Debug │ │ Optimize │ │ Cache │ │ Update │
|
||||
└──────────┘ └──────────┘ └──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
### Development Phase
|
||||
|
||||
During development, packages undergo iterative refinement:
|
||||
|
||||
```bash
|
||||
# Development workflow
|
||||
$ botserver dev --package my-bot
|
||||
[Dev] Starting development server...
|
||||
[Dev] Watching: templates/my-bot.gbai/
|
||||
[Dev] Hot reload enabled
|
||||
[Dev] Debugger listening on port 9229
|
||||
[Dev] Development UI: http://localhost:3000
|
||||
|
||||
# File change detected
|
||||
[Dev] Change detected: my-bot.gbdialog/handler.bas
|
||||
[Dev] Reloading dialog scripts...
|
||||
[Dev] Validation passed ✓
|
||||
[Dev] Scripts reloaded in 127ms
|
||||
```
|
||||
|
||||
### Build Phase
|
||||
|
||||
The build process validates and optimizes package components:
|
||||
|
||||
```bash
|
||||
# Package build process
|
||||
$ botserver build --package my-bot
|
||||
[Build] Validating package structure...
|
||||
├── Checking required directories... ✓
|
||||
├── Validating dialog scripts... ✓
|
||||
├── Verifying configuration... ✓
|
||||
└── Scanning knowledge base... ✓
|
||||
|
||||
[Build] Optimizing resources...
|
||||
├── Minifying CSS (saved 2.3 KB)... ✓
|
||||
├── Compressing images (saved 156 KB)... ✓
|
||||
├── Optimizing documents (saved 1.2 MB)... ✓
|
||||
└── Generating manifest... ✓
|
||||
|
||||
[Build] Package built successfully
|
||||
Output: dist/my-bot.gbai.tar.gz (3.4 MB)
|
||||
```
|
||||
|
||||
### Deployment Phase
|
||||
|
||||
Deployment transfers packages to the runtime environment:
|
||||
|
||||
```bash
|
||||
# Deployment process
|
||||
$ botserver deploy my-bot.gbai.tar.gz
|
||||
[Deploy] Uploading package...
|
||||
├── Transferring archive (3.4 MB)... ✓
|
||||
├── Extracting contents... ✓
|
||||
├── Validating integrity... ✓
|
||||
└── Updating registry... ✓
|
||||
|
||||
[Deploy] Processing components...
|
||||
├── Indexing knowledge base (1,247 documents)... ✓
|
||||
├── Compiling dialog scripts (23 files)... ✓
|
||||
├── Loading configuration... ✓
|
||||
├── Applying theme... ✓
|
||||
└── Initializing storage... ✓
|
||||
|
||||
[Deploy] Creating bot instance...
|
||||
├── Bot ID: bot-f47ac10b-58cc
|
||||
├── Endpoint: https://bot.company.com/my-bot
|
||||
├── Status: Active
|
||||
└── Version: 1.2.3
|
||||
|
||||
[Deploy] Deployment completed successfully
|
||||
```
|
||||
|
||||
### Runtime Phase
|
||||
|
||||
At runtime, packages are loaded and executed on demand:
|
||||
|
||||
```
|
||||
Runtime Execution Model:
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Request Handler │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Package Resolution (by bot_id) │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Component Loading │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Scripts │ │ Knowledge │ │
|
||||
│ │ (Cached) │ │ (Indexed) │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Execution Context │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Session │ │ Memory │ │
|
||||
│ │ State │ │ Storage │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Response Generation │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Package Storage Architecture
|
||||
|
||||
### Storage Hierarchy
|
||||
|
||||
Packages utilize a multi-tier storage architecture:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Hot Tier (Memory) │
|
||||
│ Active Scripts, Session Data │
|
||||
│ Latency: <1ms │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Warm Tier (SSD) │
|
||||
│ Frequently Accessed Documents │
|
||||
│ Latency: 5-10ms │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Cold Tier (HDD/Object) │
|
||||
│ Archives, Backups, Large Files │
|
||||
│ Latency: 50-200ms │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Storage Distribution
|
||||
|
||||
Package components are distributed across storage systems:
|
||||
|
||||
| Component | Primary Storage | Secondary Storage | Cache Strategy | Retention Policy |
|
||||
|-----------|----------------|-------------------|----------------|------------------|
|
||||
| Scripts | Object Storage | Memory Cache | LRU with 1h TTL | Versioned, Permanent |
|
||||
| Configuration | Database | Memory Cache | Invalidate on Change | Versioned, Permanent |
|
||||
| Documents | Vector DB + Object | Disk Cache | LRU with 24h TTL | Permanent |
|
||||
| Themes | Object Storage | Browser Cache | ETag Validation | Versioned, Permanent |
|
||||
| User Files | Object Storage | None | On-Demand | User-Defined |
|
||||
| Session Data | Cache | Database | TTL-Based | Configurable TTL |
|
||||
|
||||
## Multi-Bot Architecture
|
||||
|
||||
### Tenant Isolation
|
||||
|
||||
The system supports complete isolation between bot instances:
|
||||
|
||||
```
|
||||
Isolation Boundaries:
|
||||
┌──────────────────────────────────┐
|
||||
│ Bot Instance A │
|
||||
│ ┌────────────┬────────────┐ │
|
||||
│ │ Database │ Storage │ │
|
||||
│ │ Schema A │ Bucket A │ │
|
||||
│ └────────────┴────────────┘ │
|
||||
│ ┌────────────┬────────────┐ │
|
||||
│ │ Cache │ Vectors │ │
|
||||
│ │ Namespace A│ Collection A│ │
|
||||
│ └────────────┴────────────┘ │
|
||||
└──────────────────────────────────┘
|
||||
|
||||
┌──────────────────────────────────┐
|
||||
│ Bot Instance B │
|
||||
│ ┌────────────┬────────────┐ │
|
||||
│ │ Database │ Storage │ │
|
||||
│ │ Schema B │ Bucket B │ │
|
||||
│ └────────────┴────────────┘ │
|
||||
│ ┌────────────┬────────────┐ │
|
||||
│ │ Cache │ Vectors │ │
|
||||
│ │ Namespace B│ Collection B│ │
|
||||
│ └────────────┴────────────┘ │
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Resource Sharing
|
||||
|
||||
While maintaining isolation, bots can share infrastructure:
|
||||
|
||||
```yaml
|
||||
resource_sharing:
|
||||
compute:
|
||||
type: shared_pool
|
||||
allocation: fair_share
|
||||
limits:
|
||||
cpu: 4_cores_per_bot
|
||||
memory: 8GB_per_bot
|
||||
|
||||
storage:
|
||||
type: quota_based
|
||||
limits:
|
||||
database: 10GB_per_bot
|
||||
objects: 100GB_per_bot
|
||||
vectors: 1M_documents_per_bot
|
||||
|
||||
network:
|
||||
type: bandwidth_limited
|
||||
limits:
|
||||
ingress: 100Mbps_per_bot
|
||||
egress: 100Mbps_per_bot
|
||||
```
|
||||
|
||||
## Migration Strategies
|
||||
|
||||
### From Legacy Bot Platforms
|
||||
|
||||
Migration from traditional bot platforms requires paradigm shift:
|
||||
|
||||
#### Traditional Approach (Complex)
|
||||
```javascript
|
||||
// Legacy: 500+ lines of intent matching
|
||||
const intents = {
|
||||
'book_meeting': {
|
||||
patterns: [
|
||||
'schedule a meeting',
|
||||
'book an appointment',
|
||||
'set up a call'
|
||||
],
|
||||
entities: ['person', 'date', 'time'],
|
||||
handler: async (context) => {
|
||||
// Complex state machine logic
|
||||
if (!context.state.person) {
|
||||
return askForPerson(context);
|
||||
}
|
||||
if (!context.state.date) {
|
||||
return askForDate(context);
|
||||
}
|
||||
// ... 100 more lines
|
||||
}
|
||||
}
|
||||
// ... 50 more intents
|
||||
};
|
||||
```
|
||||
|
||||
#### General Bots Approach (Simple)
|
||||
```basic
|
||||
' Modern: 10 lines with LLM intelligence
|
||||
USE TOOL "scheduler"
|
||||
TALK "I can help you schedule meetings."
|
||||
|
||||
' The LLM handles:
|
||||
' - Intent recognition
|
||||
' - Entity extraction
|
||||
' - Context management
|
||||
' - Error handling
|
||||
' - Natural conversation flow
|
||||
```
|
||||
|
||||
### Migration Checklist
|
||||
|
||||
Pre-migration assessment and planning:
|
||||
|
||||
```markdown
|
||||
## Migration Readiness Assessment
|
||||
|
||||
### Data Inventory
|
||||
- [ ] Identify all conversation flows
|
||||
- [ ] Catalog knowledge documents
|
||||
- [ ] List integration points
|
||||
- [ ] Document user personas
|
||||
- [ ] Map data dependencies
|
||||
|
||||
### Technical Evaluation
|
||||
- [ ] Review dialog complexity
|
||||
- [ ] Assess integration requirements
|
||||
- [ ] Evaluate performance needs
|
||||
- [ ] Identify security requirements
|
||||
- [ ] Plan testing strategy
|
||||
|
||||
### Migration Approach
|
||||
- [ ] Choose phased or big-bang migration
|
||||
- [ ] Define success criteria
|
||||
- [ ] Establish rollback plan
|
||||
- [ ] Schedule downtime windows
|
||||
- [ ] Prepare user communication
|
||||
|
||||
### Post-Migration Validation
|
||||
- [ ] Verify conversation flows
|
||||
- [ ] Test knowledge retrieval
|
||||
- [ ] Validate integrations
|
||||
- [ ] Measure performance metrics
|
||||
- [ ] Conduct user acceptance testing
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Package Loading Optimization
|
||||
|
||||
Techniques for optimizing package load times:
|
||||
|
||||
```python
|
||||
# Lazy loading strategy
|
||||
class PackageLoader:
|
||||
def __init__(self):
|
||||
self.loaded_components = {}
|
||||
self.loading_queue = PriorityQueue()
|
||||
|
||||
def load_package(self, package_id: str):
|
||||
# Load critical components immediately
|
||||
self.load_critical_components(package_id)
|
||||
|
||||
# Queue non-critical components for background loading
|
||||
self.queue_background_loading(package_id)
|
||||
|
||||
def load_critical_components(self, package_id: str):
|
||||
# Load only what's needed for first response
|
||||
components = [
|
||||
'configuration',
|
||||
'start_script',
|
||||
'theme_css'
|
||||
]
|
||||
for component in components:
|
||||
self.load_component(package_id, component)
|
||||
|
||||
def queue_background_loading(self, package_id: str):
|
||||
# Load remaining components asynchronously
|
||||
components = [
|
||||
'knowledge_base',
|
||||
'additional_scripts',
|
||||
'drive_files'
|
||||
]
|
||||
for component in components:
|
||||
priority = self.calculate_priority(component)
|
||||
self.loading_queue.put((priority, package_id, component))
|
||||
```
|
||||
|
||||
### Caching Strategies
|
||||
|
||||
Multi-level caching for optimal performance:
|
||||
|
||||
```yaml
|
||||
caching_configuration:
|
||||
l1_cache: # CPU Cache
|
||||
type: in_process
|
||||
size: 100MB
|
||||
ttl: 60s
|
||||
items:
|
||||
- compiled_scripts
|
||||
- hot_configuration
|
||||
|
||||
l2_cache: # Application Cache
|
||||
type: memory
|
||||
size: 1GB
|
||||
ttl: 3600s
|
||||
items:
|
||||
- script_ast
|
||||
- user_sessions
|
||||
- embeddings
|
||||
|
||||
l3_cache: # Distributed Cache
|
||||
type: redis_cluster
|
||||
size: 10GB
|
||||
ttl: 86400s
|
||||
items:
|
||||
- knowledge_chunks
|
||||
- document_metadata
|
||||
- search_results
|
||||
|
||||
l4_cache: # CDN/Edge Cache
|
||||
type: cloudflare
|
||||
ttl: 604800s
|
||||
items:
|
||||
- static_assets
|
||||
- theme_files
|
||||
- public_documents
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Package Validation
|
||||
|
||||
Comprehensive security validation for packages:
|
||||
|
||||
```python
|
||||
class PackageValidator:
|
||||
def validate(self, package_path: str) -> ValidationResult:
|
||||
validations = [
|
||||
self.check_structure(),
|
||||
self.scan_for_malware(),
|
||||
self.validate_scripts(),
|
||||
self.check_permissions(),
|
||||
self.verify_signatures()
|
||||
]
|
||||
|
||||
return ValidationResult(all(validations))
|
||||
|
||||
def validate_scripts(self, scripts: List[str]) -> bool:
|
||||
"""Validate BASIC scripts for security issues"""
|
||||
for script in scripts:
|
||||
# Check for dangerous operations
|
||||
if self.contains_dangerous_operations(script):
|
||||
return False
|
||||
|
||||
# Validate syntax
|
||||
if not self.valid_syntax(script):
|
||||
return False
|
||||
|
||||
# Check resource limits
|
||||
if self.exceeds_complexity_limit(script):
|
||||
return False
|
||||
|
||||
return True
|
||||
```
|
||||
|
||||
### Access Control
|
||||
|
||||
Role-based access control for package resources:
|
||||
|
||||
```yaml
|
||||
access_control:
|
||||
roles:
|
||||
admin:
|
||||
permissions:
|
||||
- package:create
|
||||
- package:read
|
||||
- package:update
|
||||
- package:delete
|
||||
- package:deploy
|
||||
|
||||
developer:
|
||||
permissions:
|
||||
- package:create
|
||||
- package:read
|
||||
- package:update
|
||||
- package:test
|
||||
|
||||
operator:
|
||||
permissions:
|
||||
- package:read
|
||||
- package:deploy
|
||||
- package:monitor
|
||||
|
||||
user:
|
||||
permissions:
|
||||
- package:use
|
||||
- conversation:create
|
||||
- file:read
|
||||
```
|
||||
|
||||
## Monitoring and Diagnostics
|
||||
|
||||
### Package Metrics
|
||||
|
||||
Real-time monitoring of package performance:
|
||||
|
||||
```json
|
||||
{
|
||||
"package_id": "customer-service-bot",
|
||||
"timestamp": "2024-03-15T14:30:00Z",
|
||||
"metrics": {
|
||||
"performance": {
|
||||
"script_execution_time_p50": 45,
|
||||
"script_execution_time_p99": 234,
|
||||
"knowledge_query_time_p50": 78,
|
||||
"knowledge_query_time_p99": 345,
|
||||
"response_generation_time_p50": 123,
|
||||
"response_generation_time_p99": 567
|
||||
},
|
||||
"usage": {
|
||||
"total_conversations": 1247,
|
||||
"active_sessions": 34,
|
||||
"messages_processed": 15823,
|
||||
"knowledge
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
@ -17,7 +17,7 @@ That's it. No manifests, no build files, no dependencies. Copy the folder to dep
|
|||
### Visual Architecture
|
||||
### Architecture
|
||||
|
||||
|
||||
<img src="./assets/package-structure.svg" alt="Package Structure" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
## How Bootstrap Finds Bots
|
||||
|
||||
|
|
@ -224,7 +224,7 @@ templates/
|
|||
When BotServer starts:
|
||||
|
||||
```
|
||||
|
||||
<img src="./assets/template-deployment-flow.svg" alt="Template Deployment Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
```
|
||||
|
||||
Takes about 5-10 seconds per bot.
|
||||
|
|
|
|||
|
|
@ -12,82 +12,11 @@ The knowledge base system transforms unstructured documents into queryable seman
|
|||
|
||||
The knowledge base architecture implements a multi-stage pipeline for document processing and retrieval:
|
||||
|
||||
<svg width="800" height="600" viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
|
||||
<!-- Title -->
|
||||
<text x="400" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="bold" fill="currentColor">Knowledge Base Architecture Pipeline</text>
|
||||
|
||||
<!-- Document Ingestion Layer -->
|
||||
<rect x="100" y="60" width="600" height="60" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="400" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">Document Ingestion Layer</text>
|
||||
<text x="400" y="105" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor" opacity="0.8">(PDF, Word, Excel, Text, HTML, Markdown)</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 120 L 400 140" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowhead)" opacity="0.7"/>
|
||||
|
||||
<!-- Preprocessing Pipeline -->
|
||||
<rect x="100" y="140" width="600" height="60" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="400" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">Preprocessing Pipeline</text>
|
||||
<text x="400" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor" opacity="0.8">(Extraction, Cleaning, Normalization, Validation)</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 200 L 400 220" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowhead)" opacity="0.7"/>
|
||||
|
||||
<!-- Chunking Engine -->
|
||||
<rect x="100" y="220" width="600" height="60" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="400" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">Chunking Engine</text>
|
||||
<text x="400" y="265" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor" opacity="0.8">(Semantic Segmentation, Overlap Management, Metadata)</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 280 L 400 300" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowhead)" opacity="0.7"/>
|
||||
|
||||
<!-- Embedding Generation -->
|
||||
<rect x="100" y="300" width="600" height="60" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="400" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">Embedding Generation</text>
|
||||
<text x="400" y="345" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor" opacity="0.8">(Transformer Models, Dimensionality Reduction)</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 360 L 400 380" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowhead)" opacity="0.7"/>
|
||||
|
||||
<!-- Vector Index Layer -->
|
||||
<rect x="100" y="380" width="600" height="60" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="400" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">Vector Index Layer</text>
|
||||
<text x="400" y="425" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor" opacity="0.8">(HNSW Index, Quantization, Sharding)</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 440 L 400 460" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowhead)" opacity="0.7"/>
|
||||
|
||||
<!-- Retrieval Engine -->
|
||||
<rect x="100" y="460" width="600" height="60" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="400" y="485" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">Retrieval Engine</text>
|
||||
<text x="400" y="505" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor" opacity="0.8">(Semantic Search, Hybrid Retrieval, Re-ranking)</text>
|
||||
|
||||
<!-- Side annotations -->
|
||||
<text x="50" y="95" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.7" transform="rotate(-90 50 95)">Input</text>
|
||||
<text x="50" y="495" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.7" transform="rotate(-90 50 495)">Output</text>
|
||||
|
||||
<!-- Data flow indicators on the right -->
|
||||
<text x="750" y="95" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.6">Raw Docs</text>
|
||||
<text x="750" y="175" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.6">Clean Text</text>
|
||||
<text x="750" y="255" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.6">Chunks</text>
|
||||
<text x="750" y="335" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.6">Vectors</text>
|
||||
<text x="750" y="415" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.6">Index</text>
|
||||
<text x="750" y="495" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.6">Results</text>
|
||||
|
||||
<!-- Arrow marker definition -->
|
||||
<defs>
|
||||
<marker id="arrowhead" markerWidth="10" markerHeight="10" refX="5" refY="5" orient="auto">
|
||||
<polygon points="0 0, 10 5, 0 10" fill="currentColor"/>
|
||||
</marker>
|
||||
</defs>
|
||||
|
||||
<!-- Performance metrics box -->
|
||||
<rect x="100" y="540" width="600" height="40" fill="none" stroke="currentColor" stroke-width="1" stroke-dasharray="5,5" rx="3" opacity="0.5"/>
|
||||
<text x="400" y="565" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="currentColor" font-style="italic" opacity="0.7">Pipeline processes ~1000 documents/minute with <50ms query latency (p99)</text>
|
||||
</svg>
|
||||
<img src="./assets/kb-architecture-pipeline.svg" alt="Knowledge Base Architecture Pipeline" style="max-height: 600px; width: 100%; object-fit: contain;">
|
||||
|
||||
### Technical Specifications
|
||||
|
||||
<svg width="900" height="450" viewBox="0 0 900 450" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
|
||||
<img src="./assets/technical-specs.svg" alt="Technical Specifications" style="max-height: 450px; width: 100%; object-fit: contain;">
|
||||
<!-- Title -->
|
||||
<text x="450" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="currentColor">System Technical Specifications</text>
|
||||
|
||||
|
|
@ -178,7 +107,7 @@ The system implements format-specific extractors for comprehensive document supp
|
|||
|
||||
#### The Storage Multiplication Factor
|
||||
|
||||
<svg width="900" height="500" viewBox="0 0 900 500" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
|
||||
<img src="./assets/context-window.svg" alt="Context Window Optimization" style="max-height: 500px; width: 100%; object-fit: contain;">
|
||||
<!-- Title -->
|
||||
<text x="450" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="currentColor">Vector Database Storage Requirements: The Real Mathematics</text>
|
||||
|
||||
|
|
@ -291,7 +220,7 @@ Where:
|
|||
|
||||
#### Detailed Storage Breakdown by Component
|
||||
|
||||
<svg width="900" height="400" viewBox="0 0 900 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
|
||||
<img src="./assets/storage-multiplication.svg" alt="Storage Multiplication Factor" style="max-height: 350px; width: 100%; object-fit: contain;">
|
||||
<!-- Title -->
|
||||
<text x="450" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="currentColor">Storage Components per 1TB of Documents</text>
|
||||
|
||||
|
|
@ -519,7 +448,7 @@ Advanced re-ranking for improved precision:
|
|||
|
||||
### Context Window Optimization
|
||||
|
||||
<svg width="900" height="500" viewBox="0 0 900 500" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
|
||||
<img src="./assets/storage-breakdown.svg" alt="Storage Breakdown by Component" style="max-height: 250px; width: 100%; object-fit: contain;">
|
||||
<!-- Title -->
|
||||
<text x="450" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="currentColor">LLM Context Compression Strategies</text>
|
||||
|
||||
|
|
@ -804,4 +733,9 @@ Real-time monitoring dashboard tracks:
|
|||
|
||||
## Conclusion
|
||||
|
||||
The General Bots Knowledge Base system provides a robust, scalable foundation for semantic search and retrieval. Through careful architectural decisions, optimization strategies, and comprehensive monitoring, the system delivers high-performance information retrieval while maintaining quality and reliability. The integration with modern LLM systems enables powerful retrieval-augmented generation capabilities, enhancing the overall intelligence and responsiveness of the bot platform.
|
||||
The General Bots Knowledge Base system provides a robust, scalable foundation for semantic search and retrieval. Through careful architectural decisions, optimization strategies, and comprehensive monitoring, the system delivers high-performance information retrieval while maintaining quality and reliability. The integration with modern LLM systems enables powerful retrieval-augmented generation capabilities, enhancing the overall intelligence and responsiveness of the bot platform.
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
173
docs/src/chapter-03/assets/caching-architecture.svg
Normal file
173
docs/src/chapter-03/assets/caching-architecture.svg
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
<svg width="750" height="400" viewBox="0 0 750 400" xmlns="http://www.w3.org/2000/svg">
|
||||
<!-- Define gradients and effects -->
|
||||
<defs>
|
||||
<!-- Beautiful gradients with vibrant colors -->
|
||||
<linearGradient id="userQueryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#667eea;stop-opacity:0.3" />
|
||||
<stop offset="100%" style="stop-color:#764ba2;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="keyGenGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#f093fb;stop-opacity:0.3" />
|
||||
<stop offset="100%" style="stop-color:#f5576c;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="valkeyGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#ff6b6b;stop-opacity:0.3" />
|
||||
<stop offset="100%" style="stop-color:#ee5a24;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="embedGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#4facfe;stop-opacity:0.3" />
|
||||
<stop offset="100%" style="stop-color:#00f2fe;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="semanticGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#43e97b;stop-opacity:0.3" />
|
||||
<stop offset="100%" style="stop-color:#38f9d7;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="generateGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#fa709a;stop-opacity:0.3" />
|
||||
<stop offset="100%" style="stop-color:#fee140;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="storeGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#30cfd0;stop-opacity:0.3" />
|
||||
<stop offset="100%" style="stop-color:#330867;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Hit path gradient -->
|
||||
<linearGradient id="hitPathGrad" x1="0%" y1="0%" x2="100%" y2="0%">
|
||||
<stop offset="0%" style="stop-color:#10b981;stop-opacity:0.8" />
|
||||
<stop offset="100%" style="stop-color:#34d399;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Miss path gradient -->
|
||||
<linearGradient id="missPathGrad" x1="0%" y1="0%" x2="100%" y2="0%">
|
||||
<stop offset="0%" style="stop-color:#f59e0b;stop-opacity:0.8" />
|
||||
<stop offset="100%" style="stop-color:#fbbf24;stop-opacity:0.4" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Improved arrow marker with color -->
|
||||
<marker id="arrowCache" markerWidth="12" markerHeight="12" refX="11" refY="6" orient="auto">
|
||||
<path d="M 0 0 L 12 6 L 0 12 L 3 6 Z" fill="#4a5568" opacity="0.8"/>
|
||||
</marker>
|
||||
|
||||
<marker id="arrowHit" markerWidth="12" markerHeight="12" refX="11" refY="6" orient="auto">
|
||||
<path d="M 0 0 L 12 6 L 0 12 L 3 6 Z" fill="#10b981" opacity="0.9"/>
|
||||
</marker>
|
||||
|
||||
<marker id="arrowMiss" markerWidth="12" markerHeight="12" refX="11" refY="6" orient="auto">
|
||||
<path d="M 0 0 L 12 6 L 0 12 L 3 6 Z" fill="#f59e0b" opacity="0.9"/>
|
||||
</marker>
|
||||
|
||||
<!-- Drop shadow effect -->
|
||||
<filter id="shadow" x="-50%" y="-50%" width="200%" height="200%">
|
||||
<feGaussianBlur in="SourceAlpha" stdDeviation="3"/>
|
||||
<feOffset dx="0" dy="3" result="offsetblur"/>
|
||||
<feComponentTransfer>
|
||||
<feFuncA type="linear" slope="0.2"/>
|
||||
</feComponentTransfer>
|
||||
<feMerge>
|
||||
<feMergeNode/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
|
||||
<!-- Glow effect for decision diamond -->
|
||||
<filter id="glowEffect" x="-50%" y="-50%" width="200%" height="200%">
|
||||
<feGaussianBlur stdDeviation="4" result="coloredBlur"/>
|
||||
<feMerge>
|
||||
<feMergeNode in="coloredBlur"/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<!-- Background -->
|
||||
<rect x="0" y="0" width="750" height="400" fill="#fafafa"/>
|
||||
|
||||
<!-- Title with better padding -->
|
||||
<rect x="200" y="10" width="350" height="35" fill="rgba(99, 102, 241, 0.05)" rx="8"/>
|
||||
<text x="375" y="33" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="600" fill="#1e293b">
|
||||
Semantic Caching Architecture
|
||||
</text>
|
||||
|
||||
<!-- User Query -->
|
||||
<rect x="50" y="70" width="130" height="45" fill="url(#userQueryGrad)" stroke="#667eea" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="115" y="95" text-anchor="middle" font-family="system-ui" sans-serif" font-size="13" font-weight="600" fill="#1e293b">User Query</text>
|
||||
<text x="115" y="108" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">"What's the policy?"</text>
|
||||
|
||||
<!-- Arrow to Generate Key -->
|
||||
<path d="M 180 92 L 220 92" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrowCache)" opacity="0.7"/>
|
||||
|
||||
<!-- Generate Key -->
|
||||
<rect x="220" y="70" width="130" height="45" fill="url(#keyGenGrad)" stroke="#f5576c" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="285" y="95" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#1e293b">Generate Key</text>
|
||||
<text x="285" y="108" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">Hash + Embed</text>
|
||||
|
||||
<!-- Arrow to Check Valkey -->
|
||||
<path d="M 350 92 L 390 92" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrowCache)" opacity="0.7"/>
|
||||
|
||||
<!-- Check Valkey -->
|
||||
<rect x="390" y="70" width="130" height="45" fill="url(#valkeyGrad)" stroke="#ee5a24" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="455" y="95" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#1e293b">Check Valkey</text>
|
||||
<text x="455" y="108" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">Memory Store</text>
|
||||
|
||||
<!-- Arrow to Decision -->
|
||||
<path d="M 520 92 L 560 92" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrowCache)" opacity="0.7"/>
|
||||
|
||||
<!-- Hit/Miss Decision Diamond with glow -->
|
||||
<g filter="url(#glowEffect)">
|
||||
<path d="M 610 70 L 650 92 L 610 114 L 570 92 Z" fill="rgba(139, 92, 246, 0.2)" stroke="#8b5cf6" stroke-width="2.5"/>
|
||||
<text x="610" y="97" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#1e293b">Hit?</text>
|
||||
</g>
|
||||
|
||||
<!-- Arrow down from Generate Key to Embedding -->
|
||||
<path d="M 285 115 L 285 160" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrowCache)" opacity="0.7"/>
|
||||
|
||||
<!-- Embedding Hash -->
|
||||
<rect x="210" y="160" width="150" height="45" fill="url(#embedGrad)" stroke="#00f2fe" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="285" y="185" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#1e293b">Embedding Hash</text>
|
||||
<text x="285" y="198" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">384D Vector</text>
|
||||
|
||||
<!-- Arrow down from Embedding Hash -->
|
||||
<path d="M 285 205 L 285 250" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrowCache)" opacity="0.7"/>
|
||||
|
||||
<!-- Semantic Search -->
|
||||
<rect x="210" y="250" width="150" height="45" fill="url(#semanticGrad)" stroke="#38f9d7" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="285" y="275" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#1e293b">Semantic Search</text>
|
||||
<text x="285" y="288" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">Similarity > 0.95</text>
|
||||
|
||||
<!-- Cache Hit path (success) -->
|
||||
<path d="M 610 70 L 610 40 L 455 40" stroke="url(#hitPathGrad)" stroke-width="3" fill="none" opacity="0.8" stroke-linecap="round"/>
|
||||
<rect x="330" y="25" width="125" height="30" fill="rgba(16, 185, 129, 0.1)" stroke="#10b981" stroke-width="1.5" stroke-dasharray="4,2" rx="6"/>
|
||||
<text x="392" y="44" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="500" fill="#047857">✓ Cache Hit</text>
|
||||
|
||||
<!-- Miss path -->
|
||||
<path d="M 610 114 L 610 160" stroke="url(#missPathGrad)" stroke-width="3" fill="none" marker-end="url(#arrowMiss)" opacity="0.8" stroke-linecap="round"/>
|
||||
<text x="630" y="140" text-anchor="start" font-family="system-ui, sans-serif" font-size="10" font-weight="500" fill="#d97706">Miss</text>
|
||||
|
||||
<!-- Generate New Response -->
|
||||
<rect x="530" y="160" width="150" height="45" fill="url(#generateGrad)" stroke="#fa709a" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="605" y="185" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#1e293b">Generate New</text>
|
||||
<text x="605" y="198" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">LLM Response</text>
|
||||
|
||||
<!-- Arrow down from Generate New -->
|
||||
<path d="M 605 205 L 605 250" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrowCache)" opacity="0.7"/>
|
||||
|
||||
<!-- Store in Valkey -->
|
||||
<rect x="510" y="250" width="190" height="45" fill="url(#storeGrad)" stroke="#330867" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="605" y="270" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="600" fill="#1e293b">Store in Valkey</text>
|
||||
<text x="605" y="285" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">TTL: 3600s</text>
|
||||
|
||||
<!-- Performance Metrics Box -->
|
||||
<rect x="50" y="320" width="650" height="60" fill="rgba(99, 102, 241, 0.05)" stroke="#8b5cf6" stroke-width="1" stroke-dasharray="6,3" rx="8"/>
|
||||
<text x="375" y="343" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="500" fill="#1e293b">
|
||||
Performance Metrics
|
||||
</text>
|
||||
<text x="200" y="365" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">Hit Rate: ~85%</text>
|
||||
<text x="375" y="365" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">Latency: <50ms</text>
|
||||
<text x="550" y="365" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">Cost Reduction: 95%</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 9.9 KiB |
150
docs/src/chapter-03/assets/kb-architecture-pipeline.svg
Normal file
150
docs/src/chapter-03/assets/kb-architecture-pipeline.svg
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
<svg width="800" height="600" viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg">
|
||||
<!-- Define gradients and filters -->
|
||||
<defs>
|
||||
<!-- Gradient for input layer -->
|
||||
<linearGradient id="inputGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#667eea;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#764ba2;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Gradient for processing layers -->
|
||||
<linearGradient id="processGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#06ffa5;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#00d2ff;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Gradient for embedding layer -->
|
||||
<linearGradient id="embedGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#f093fb;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#f5576c;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Gradient for index layer -->
|
||||
<linearGradient id="indexGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#fa709a;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#fee140;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Gradient for retrieval layer -->
|
||||
<linearGradient id="retrievalGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#30cfd0;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#330867;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Arrow marker -->
|
||||
<marker id="arrowhead" markerWidth="12" markerHeight="12" refX="11" refY="6" orient="auto">
|
||||
<path d="M 0 0 L 12 6 L 0 12 L 3 6 Z" fill="#4a5568" opacity="0.8"/>
|
||||
</marker>
|
||||
|
||||
<!-- Drop shadow filter -->
|
||||
<filter id="shadow" x="-50%" y="-50%" width="200%" height="200%">
|
||||
<feGaussianBlur in="SourceAlpha" stdDeviation="2"/>
|
||||
<feOffset dx="0" dy="2" result="offsetblur"/>
|
||||
<feComponentTransfer>
|
||||
<feFuncA type="linear" slope="0.2"/>
|
||||
</feComponentTransfer>
|
||||
<feMerge>
|
||||
<feMergeNode/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<!-- Background -->
|
||||
<rect x="0" y="0" width="800" height="600" fill="#ffffff"/>
|
||||
|
||||
<!-- Title -->
|
||||
<text x="400" y="30" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="22" font-weight="600" fill="#1a202c">
|
||||
Knowledge Base Architecture Pipeline
|
||||
</text>
|
||||
|
||||
<!-- Document Ingestion Layer -->
|
||||
<rect x="100" y="60" width="600" height="60" fill="url(#inputGrad)" stroke="#667eea" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="400" y="85" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#2d3748">
|
||||
Document Ingestion Layer
|
||||
</text>
|
||||
<text x="400" y="105" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#4a5568">
|
||||
PDF • Word • Excel • Text • HTML • Markdown
|
||||
</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 120 L 400 140" stroke="#4a5568" stroke-width="3" fill="none" marker-end="url(#arrowhead)" opacity="0.6"/>
|
||||
|
||||
<!-- Preprocessing Pipeline -->
|
||||
<rect x="100" y="140" width="600" height="60" fill="url(#processGrad)" stroke="#00d2ff" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="400" y="165" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#2d3748">
|
||||
Preprocessing Pipeline
|
||||
</text>
|
||||
<text x="400" y="185" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#4a5568">
|
||||
Extraction • Cleaning • Normalization • Validation
|
||||
</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 200 L 400 220" stroke="#4a5568" stroke-width="3" fill="none" marker-end="url(#arrowhead)" opacity="0.6"/>
|
||||
|
||||
<!-- Chunking Engine -->
|
||||
<rect x="100" y="220" width="600" height="60" fill="url(#processGrad)" stroke="#06ffa5" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="400" y="245" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#2d3748">
|
||||
Intelligent Chunking Engine
|
||||
</text>
|
||||
<text x="400" y="265" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#4a5568">
|
||||
Semantic Segmentation • Overlap Management • Metadata Preservation
|
||||
</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 280 L 400 300" stroke="#4a5568" stroke-width="3" fill="none" marker-end="url(#arrowhead)" opacity="0.6"/>
|
||||
|
||||
<!-- Embedding Generation -->
|
||||
<rect x="100" y="300" width="600" height="60" fill="url(#embedGrad)" stroke="#f5576c" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="400" y="325" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#2d3748">
|
||||
Embedding Generation
|
||||
</text>
|
||||
<text x="400" y="345" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#4a5568">
|
||||
BGE Models • Transformer Architecture • Dimensionality: 384/768
|
||||
</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 360 L 400 380" stroke="#4a5568" stroke-width="3" fill="none" marker-end="url(#arrowhead)" opacity="0.6"/>
|
||||
|
||||
<!-- Vector Index Layer -->
|
||||
<rect x="100" y="380" width="600" height="60" fill="url(#indexGrad)" stroke="#fa709a" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="400" y="405" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#2d3748">
|
||||
Vector Index Layer
|
||||
</text>
|
||||
<text x="400" y="425" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#4a5568">
|
||||
HNSW Algorithm • Quantization • Distributed Sharding
|
||||
</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<path d="M 400 440 L 400 460" stroke="#4a5568" stroke-width="3" fill="none" marker-end="url(#arrowhead)" opacity="0.6"/>
|
||||
|
||||
<!-- Retrieval Engine -->
|
||||
<rect x="100" y="460" width="600" height="60" fill="url(#retrievalGrad)" stroke="#30cfd0" stroke-width="2" rx="8" filter="url(#shadow)"/>
|
||||
<text x="400" y="485" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="600" fill="#2d3748">
|
||||
Semantic Retrieval Engine
|
||||
</text>
|
||||
<text x="400" y="505" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#4a5568">
|
||||
Cosine Similarity • Hybrid Search • Re-ranking • Context Injection
|
||||
</text>
|
||||
|
||||
<!-- Side labels -->
|
||||
<g transform="translate(50, 290)">
|
||||
<text x="0" y="0" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#718096" transform="rotate(-90)">
|
||||
Data Flow Direction
|
||||
</text>
|
||||
</g>
|
||||
|
||||
<!-- Stage indicators on the right -->
|
||||
<text x="730" y="95" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#718096">Raw Docs</text>
|
||||
<text x="730" y="175" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#718096">Clean Text</text>
|
||||
<text x="730" y="255" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#718096">Chunks</text>
|
||||
<text x="730" y="335" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#718096">Vectors</text>
|
||||
<text x="730" y="415" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#718096">Index</text>
|
||||
<text x="730" y="495" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#718096">Results</text>
|
||||
|
||||
<!-- Performance metrics -->
|
||||
<rect x="100" y="540" width="600" height="40" fill="#f7fafc" stroke="#cbd5e0" stroke-width="1" stroke-dasharray="5,5" rx="4"/>
|
||||
<text x="400" y="565" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="#4a5568" font-style="italic">
|
||||
Pipeline processes ~1000 documents/minute • Query latency <50ms (p99) • 95% semantic accuracy
|
||||
</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 7.6 KiB |
165
docs/src/chapter-03/assets/search-pipeline.svg
Normal file
165
docs/src/chapter-03/assets/search-pipeline.svg
Normal file
|
|
@ -0,0 +1,165 @@
|
|||
<svg width="900" height="500" viewBox="0 0 900 500" xmlns="http://www.w3.org/2000/svg">
|
||||
<!-- Define gradients and effects -->
|
||||
<defs>
|
||||
<!-- Gradient for query stage -->
|
||||
<linearGradient id="queryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#667eea;stop-opacity:0.25" />
|
||||
<stop offset="100%" style="stop-color:#764ba2;stop-opacity:0.35" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Gradient for embedding stage -->
|
||||
<linearGradient id="embedSearchGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#f093fb;stop-opacity:0.25" />
|
||||
<stop offset="100%" style="stop-color:#f5576c;stop-opacity:0.35" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Gradient for search stage -->
|
||||
<linearGradient id="searchGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#4facfe;stop-opacity:0.25" />
|
||||
<stop offset="100%" style="stop-color:#00f2fe;stop-opacity:0.35" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Gradient for ranking stage -->
|
||||
<linearGradient id="rankGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#43e97b;stop-opacity:0.25" />
|
||||
<stop offset="100%" style="stop-color:#38f9d7;stop-opacity:0.35" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Gradient for result stage -->
|
||||
<linearGradient id="resultGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#fa709a;stop-opacity:0.25" />
|
||||
<stop offset="100%" style="stop-color:#fee140;stop-opacity:0.35" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Arrow marker -->
|
||||
<marker id="searchArrow" markerWidth="12" markerHeight="12" refX="11" refY="6" orient="auto">
|
||||
<path d="M 0 0 L 12 6 L 0 12 L 3 6 Z" fill="#4a5568" opacity="0.7"/>
|
||||
</marker>
|
||||
|
||||
<!-- Glow effect -->
|
||||
<filter id="glow">
|
||||
<feGaussianBlur stdDeviation="3" result="coloredBlur"/>
|
||||
<feMerge>
|
||||
<feMergeNode in="coloredBlur"/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
|
||||
<!-- Drop shadow -->
|
||||
<filter id="dropShadow" x="-50%" y="-50%" width="200%" height="200%">
|
||||
<feGaussianBlur in="SourceAlpha" stdDeviation="3"/>
|
||||
<feOffset dx="0" dy="3" result="offsetblur"/>
|
||||
<feComponentTransfer>
|
||||
<feFuncA type="linear" slope="0.15"/>
|
||||
</feComponentTransfer>
|
||||
<feMerge>
|
||||
<feMergeNode/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<!-- Background with subtle gradient -->
|
||||
<rect x="0" y="0" width="900" height="500" fill="url(#bgGrad)"/>
|
||||
<defs>
|
||||
<linearGradient id="bgGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#ffffff;stop-opacity:1" />
|
||||
<stop offset="100%" style="stop-color:#f8f9fa;stop-opacity:1" />
|
||||
</linearGradient>
|
||||
</defs>
|
||||
|
||||
<!-- Title -->
|
||||
<text x="450" y="35" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="24" font-weight="600" fill="#1a202c">
|
||||
Semantic Search Pipeline
|
||||
</text>
|
||||
|
||||
<!-- Main flow container -->
|
||||
<g transform="translate(0, 70)">
|
||||
|
||||
<!-- Stage 1: User Query -->
|
||||
<g transform="translate(50, 0)">
|
||||
<rect x="0" y="0" width="160" height="80" fill="url(#queryGrad)" stroke="#667eea" stroke-width="2" rx="10" filter="url(#dropShadow)"/>
|
||||
<text x="80" y="30" text-anchor="middle" font-family="system-ui" font-size="14" font-weight="600" fill="#2d3748">User Query</text>
|
||||
<text x="80" y="50" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">"What's the return</text>
|
||||
<text x="80" y="65" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">policy?"</text>
|
||||
</g>
|
||||
|
||||
<!-- Arrow 1 -->
|
||||
<path d="M 210 40 L 250 40" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#searchArrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Stage 2: Query Embedding -->
|
||||
<g transform="translate(250, 0)">
|
||||
<rect x="0" y="0" width="160" height="80" fill="url(#embedSearchGrad)" stroke="#f5576c" stroke-width="2" rx="10" filter="url(#dropShadow)"/>
|
||||
<text x="80" y="30" text-anchor="middle" font-family="system-ui" font-size="14" font-weight="600" fill="#2d3748">Embedding</text>
|
||||
<text x="80" y="50" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">Transform to</text>
|
||||
<text x="80" y="65" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">384D vector</text>
|
||||
</g>
|
||||
|
||||
<!-- Arrow 2 -->
|
||||
<path d="M 410 40 L 450 40" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#searchArrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Stage 3: Vector Search -->
|
||||
<g transform="translate(450, 0)">
|
||||
<rect x="0" y="0" width="180" height="80" fill="url(#searchGrad)" stroke="#00f2fe" stroke-width="2" rx="10" filter="url(#dropShadow)"/>
|
||||
<text x="90" y="30" text-anchor="middle" font-family="system-ui" font-size="14" font-weight="600" fill="#2d3748">Vector Search</text>
|
||||
<text x="90" y="50" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">Cosine similarity</text>
|
||||
<text x="90" y="65" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">in vector space</text>
|
||||
</g>
|
||||
|
||||
<!-- Arrow 3 -->
|
||||
<path d="M 630 40 L 670 40" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#searchArrow)" opacity="0.6"/>
|
||||
|
||||
<!-- Stage 4: Ranking -->
|
||||
<g transform="translate(670, 0)">
|
||||
<rect x="0" y="0" width="160" height="80" fill="url(#rankGrad)" stroke="#38f9d7" stroke-width="2" rx="10" filter="url(#dropShadow)"/>
|
||||
<text x="80" y="30" text-anchor="middle" font-family="system-ui" font-size="14" font-weight="600" fill="#2d3748">Re-ranking</text>
|
||||
<text x="80" y="50" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">Score & sort</text>
|
||||
<text x="80" y="65" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">by relevance</text>
|
||||
</g>
|
||||
|
||||
<!-- Collections being searched (below main flow) -->
|
||||
<g transform="translate(450, 140)">
|
||||
<rect x="0" y="0" width="180" height="60" fill="rgba(79, 172, 254, 0.1)" stroke="#4facfe" stroke-width="1.5" stroke-dasharray="5,5" rx="8"/>
|
||||
<text x="90" y="25" text-anchor="middle" font-family="system-ui" font-size="12" font-weight="500" fill="#2d3748">Active Collections</text>
|
||||
<text x="90" y="45" text-anchor="middle" font-family="system-ui" font-size="10" fill="#4a5568">policies • procedures • faq</text>
|
||||
</g>
|
||||
|
||||
<!-- Arrow from Vector Search to Collections -->
|
||||
<path d="M 540 80 L 540 140" stroke="#4facfe" stroke-width="2" stroke-dasharray="4,4" fill="none" marker-end="url(#searchArrow)" opacity="0.4"/>
|
||||
|
||||
<!-- Results -->
|
||||
<g transform="translate(350, 250)">
|
||||
<rect x="0" y="0" width="380" height="100" fill="url(#resultGrad)" stroke="#fa709a" stroke-width="2" rx="10" filter="url(#dropShadow)"/>
|
||||
<text x="190" y="30" text-anchor="middle" font-family="system-ui" font-size="14" font-weight="600" fill="#2d3748">Retrieved Context</text>
|
||||
<text x="60" y="55" text-anchor="start" font-family="system-ui" font-size="11" fill="#4a5568">1. "Refund policy: 30 days..." (0.92)</text>
|
||||
<text x="60" y="75" text-anchor="start" font-family="system-ui" font-size="11" fill="#4a5568">2. "Return procedures..." (0.87)</text>
|
||||
<text x="60" y="95" text-anchor="start" font-family="system-ui" font-size="11" fill="#4a5568">3. "Warranty information..." (0.81)</text>
|
||||
</g>
|
||||
|
||||
<!-- Arrow to Results -->
|
||||
<path d="M 750 80 L 750 120 L 540 120 L 540 250" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#searchArrow)" opacity="0.6"/>
|
||||
|
||||
<!-- LLM Integration -->
|
||||
<g transform="translate(350, 370)">
|
||||
<rect x="0" y="0" width="380" height="60" fill="rgba(102, 126, 234, 0.1)" stroke="#667eea" stroke-width="2" stroke-dasharray="8,4" rx="10"/>
|
||||
<text x="190" y="25" text-anchor="middle" font-family="system-ui" font-size="13" font-weight="600" fill="#2d3748">Context Injection to LLM</text>
|
||||
<text x="190" y="45" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568">Retrieved chunks provided as context for response generation</text>
|
||||
</g>
|
||||
|
||||
<!-- Arrow to LLM -->
|
||||
<path d="M 540 350 L 540 370" stroke="#667eea" stroke-width="2.5" fill="none" marker-end="url(#searchArrow)" opacity="0.6"/>
|
||||
|
||||
</g>
|
||||
|
||||
<!-- Side annotations -->
|
||||
<g transform="translate(40, 180)">
|
||||
<text x="0" y="0" text-anchor="start" font-family="system-ui" font-size="10" fill="#718096" font-style="italic">Automatic</text>
|
||||
<text x="0" y="15" text-anchor="start" font-family="system-ui" font-size="10" fill="#718096" font-style="italic">Process</text>
|
||||
</g>
|
||||
|
||||
<!-- Performance metrics -->
|
||||
<rect x="50" y="450" width="800" height="35" fill="rgba(203, 213, 224, 0.1)" stroke="#cbd5e0" stroke-width="1" stroke-dasharray="5,5" rx="6"/>
|
||||
<text x="450" y="472" text-anchor="middle" font-family="system-ui" font-size="11" fill="#4a5568" font-style="italic">
|
||||
Search latency: ~20ms • Embedding: BGE-small (384D) • Similarity threshold: 0.7 • Top-K: 5 chunks
|
||||
</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 8.9 KiB |
|
|
@ -70,82 +70,7 @@ prompt-compact,4 # Compact conversation after N exchanges
|
|||
|
||||
### Architecture
|
||||
|
||||
<svg width="700" height="350" viewBox="0 0 700 350" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
|
||||
<!-- Title -->
|
||||
<text x="350" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="currentColor">Caching Architecture Flow</text>
|
||||
|
||||
<!-- User Query -->
|
||||
<rect x="50" y="50" width="120" height="40" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="110" y="75" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor">User Query</text>
|
||||
|
||||
<!-- Arrow to Generate Key -->
|
||||
<path d="M 170 70 L 220 70" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowcache)" opacity="0.7"/>
|
||||
|
||||
<!-- Generate Key -->
|
||||
<rect x="220" y="50" width="120" height="40" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="280" y="75" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor">Generate Key</text>
|
||||
|
||||
<!-- Arrow to Check Valkey -->
|
||||
<path d="M 340 70 L 390 70" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowcache)" opacity="0.7"/>
|
||||
|
||||
<!-- Check Valkey -->
|
||||
<rect x="390" y="50" width="120" height="40" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="450" y="75" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor">Check Valkey</text>
|
||||
|
||||
<!-- Arrow to Decision -->
|
||||
<path d="M 510 70 L 560 70" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowcache)" opacity="0.7"/>
|
||||
|
||||
<!-- Hit/Miss Decision Diamond -->
|
||||
<path d="M 600 50 L 640 70 L 600 90 L 560 70 Z" fill="none" stroke="currentColor" stroke-width="2"/>
|
||||
<text x="600" y="75" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="currentColor">Hit?</text>
|
||||
|
||||
<!-- Arrow down from Generate Key -->
|
||||
<path d="M 280 90 L 280 140" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowcache)" opacity="0.7"/>
|
||||
|
||||
<!-- Embedding Hash -->
|
||||
<rect x="210" y="140" width="140" height="40" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="280" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor">Embedding Hash</text>
|
||||
|
||||
<!-- Arrow down from Embedding Hash -->
|
||||
<path d="M 280 180 L 280 230" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowcache)" opacity="0.7"/>
|
||||
|
||||
<!-- Semantic Search -->
|
||||
<rect x="210" y="230" width="140" height="40" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="280" y="255" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor">Semantic Search</text>
|
||||
|
||||
<!-- Hit path (upward) -->
|
||||
<path d="M 600 50 L 600 20 L 450 20" stroke="currentColor" stroke-width="2" fill="none" opacity="0.7"/>
|
||||
<text x="520" y="15" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.7">Cache Hit</text>
|
||||
<rect x="330" y="5" width="120" height="30" fill="none" stroke="currentColor" stroke-width="1" stroke-dasharray="3,2" opacity="0.8"/>
|
||||
<text x="390" y="24" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="currentColor">Return Cached</text>
|
||||
|
||||
<!-- Miss path (downward) -->
|
||||
<path d="M 600 90 L 600 140" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowcache)" opacity="0.7"/>
|
||||
<text x="620" y="115" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.7">Miss</text>
|
||||
|
||||
<!-- Generate New -->
|
||||
<rect x="530" y="140" width="140" height="40" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="600" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor">Generate New</text>
|
||||
|
||||
<!-- Arrow down from Generate New -->
|
||||
<path d="M 600 180 L 600 230" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arrowcache)" opacity="0.7"/>
|
||||
|
||||
<!-- Store in Valkey -->
|
||||
<rect x="510" y="230" width="180" height="40" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
|
||||
<text x="600" y="250" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="currentColor">Store in Valkey</text>
|
||||
<text x="600" y="265" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="currentColor" opacity="0.7">with TTL</text>
|
||||
|
||||
<!-- Configuration notes -->
|
||||
<rect x="50" y="290" width="640" height="40" fill="none" stroke="currentColor" stroke-width="1" stroke-dasharray="5,5" rx="3" opacity="0.5"/>
|
||||
<text x="370" y="315" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="currentColor" font-style="italic" opacity="0.7">TTL: 3600 seconds | Semantic Threshold: 0.95 | Cache: Valkey In-Memory Store</text>
|
||||
|
||||
<!-- Arrow marker definition -->
|
||||
<defs>
|
||||
<marker id="arrowcache" markerWidth="10" markerHeight="10" refX="5" refY="5" orient="auto">
|
||||
<polygon points="0 0, 10 5, 0 10" fill="currentColor"/>
|
||||
</marker>
|
||||
</defs>
|
||||
</svg>
|
||||
<img src="./assets/caching-architecture.svg" alt="Caching Architecture Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
### Cache Key Structure
|
||||
|
||||
|
|
|
|||
|
|
@ -2,6 +2,10 @@
|
|||
|
||||
Semantic search in BotServer happens automatically when you use `USE KB`. The system searches for relevant information based on meaning, not just keywords, and makes it available to the system AI during conversations.
|
||||
|
||||
## Search Pipeline
|
||||
|
||||
<img src="./assets/search-pipeline.svg" alt="Semantic Search Pipeline" style="max-height: 500px; width: 100%; object-fit: contain;">
|
||||
|
||||
## How It Works Automatically
|
||||
|
||||
1. **User asks a question** - Natural language input
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
|
|
@ -15,21 +15,21 @@ The console displays real-time information about your running BotServer instance
|
|||
|
||||
```
|
||||
╔════════════════════════════════════════════════════════════╗
|
||||
║ BotServer Console ║
|
||||
║ BotServer Console ║
|
||||
╠════════════════════════════════════════════════════════════╣
|
||||
║ Status: Running ║
|
||||
║ Status: Running ║
|
||||
║ Uptime: 2h 34m 12s ║
|
||||
║ Port: 8080 ║
|
||||
║ ║
|
||||
║ Components: ║
|
||||
║ PostgreSQL: ✓ Connected ║
|
||||
║ Valkey: ✓ Connected ║
|
||||
║ Storage: ✓ Connected ║
|
||||
║ Vectors: ✓ Connected ║
|
||||
║ ║
|
||||
║ Active Sessions: 12 ║
|
||||
║ Messages Today: 1,234 ║
|
||||
║ ║
|
||||
║ Port: 8080 ║
|
||||
║ ║
|
||||
║ Components: ║
|
||||
║ PostgreSQL: ✓ Connected ║
|
||||
║ Valkey: ✓ Connected ║
|
||||
║ Storage: ✓ Connected ║
|
||||
║ Vectors: ✓ Connected ║
|
||||
║ ║
|
||||
║ Active Sessions: 12 ║
|
||||
║ Messages Today: 1,234 ║
|
||||
║ ║
|
||||
║ Press 'q' to quit, 'r' to refresh ║
|
||||
╚════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
|
@ -127,4 +127,4 @@ Console mode provides basic monitoring only. For detailed analytics:
|
|||
|
||||
## Summary
|
||||
|
||||
Console mode provides a simple, lightweight way to monitor BotServer status without needing a web browser. It's ideal for quick checks and basic monitoring, but for full functionality, use the web interface.
|
||||
Console mode provides a simple, lightweight way to monitor BotServer status without needing a web browser. It's ideal for quick checks and basic monitoring, but for full functionality, use the web interface.
|
||||
|
|
|
|||
|
|
@ -192,4 +192,9 @@ For deeper customization, extend the `.gbui` package or build your own UI framew
|
|||
- [Chapter 4: .gbui Interface](../chapter-04-gbui/README.md) - User interface templates
|
||||
- [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
|
||||
- [Chapter 8: Configuration](../chapter-08-config/README.md) - Theme configuration options
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -327,8 +327,15 @@ The question is: what will you create?
|
|||
|
||||
**Start writing. The world is waiting for your bot.**
|
||||
|
||||
---
|
||||
|
||||
*"The beauty of BASIC lies not in what it can do, but in who it enables to do it."*
|
||||
|
||||
Continue to [BASIC Keywords Reference](./keywords.md) when you're ready for the complete reference.
|
||||
## Next Step
|
||||
|
||||
Continue to [BASIC Keywords Reference](./keywords.md) when you're ready for the complete reference.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1,99 +1,175 @@
|
|||
<svg width="700" height="500" xmlns="http://www.w3.org/2000/svg">
|
||||
<svg width="800" height="420" viewBox="0 0 800 420" xmlns="http://www.w3.org/2000/svg">
|
||||
<!-- Define gradients and filters -->
|
||||
<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"/>
|
||||
<!-- Soft glow filter -->
|
||||
<filter id="glow">
|
||||
<feGaussianBlur stdDeviation="3" result="coloredBlur"/>
|
||||
<feMerge>
|
||||
<feMergeNode in="coloredBlur"/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
|
||||
<!-- Beautiful gradients with colors -->
|
||||
<linearGradient id="userGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#667eea;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#764ba2;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="llmGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#06ffa5;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#00d2ff;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="toolGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#ffa500;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#ff6b6b;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="responseGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#4facfe;stop-opacity:0.2" />
|
||||
<stop offset="100%" style="stop-color:#00f2fe;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="memoryGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#f093fb;stop-opacity:0.1" />
|
||||
<stop offset="100%" style="stop-color:#f5576c;stop-opacity:0.2" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="directPathGrad" x1="0%" y1="0%" x2="100%" y2="0%">
|
||||
<stop offset="0%" style="stop-color:#10b981;stop-opacity:0.8" />
|
||||
<stop offset="100%" style="stop-color:#34d399;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="toolPathGrad" x1="0%" y1="0%" x2="100%" y2="0%">
|
||||
<stop offset="0%" style="stop-color:#f59e0b;stop-opacity:0.8" />
|
||||
<stop offset="100%" style="stop-color:#fbbf24;stop-opacity:0.3" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Arrow markers -->
|
||||
<marker id="arrow" markerWidth="15" markerHeight="15" refX="14" refY="7.5" orient="auto">
|
||||
<path d="M 0 0 L 15 7.5 L 0 15 L 5 7.5 Z" fill="#4a5568" opacity="0.7"/>
|
||||
</marker>
|
||||
|
||||
<marker id="arrowGreen" markerWidth="15" markerHeight="15" refX="14" refY="7.5" orient="auto">
|
||||
<path d="M 0 0 L 15 7.5 L 0 15 L 5 7.5 Z" fill="#10b981" opacity="0.8"/>
|
||||
</marker>
|
||||
|
||||
<marker id="arrowOrange" markerWidth="15" markerHeight="15" refX="14" refY="7.5" orient="auto">
|
||||
<path d="M 0 0 L 15 7.5 L 0 15 L 5 7.5 Z" fill="#f59e0b" opacity="0.8"/>
|
||||
</marker>
|
||||
|
||||
<!-- Drop shadow effect -->
|
||||
<filter id="shadow" x="-50%" y="-50%" width="200%" height="200%">
|
||||
<feGaussianBlur in="SourceAlpha" stdDeviation="3"/>
|
||||
<feOffset dx="0" dy="2" result="offsetblur"/>
|
||||
<feComponentTransfer>
|
||||
<feFuncA type="linear" slope="0.15"/>
|
||||
</feComponentTransfer>
|
||||
<feMerge>
|
||||
<feMergeNode/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<!-- Title -->
|
||||
<text x="350" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">BASIC Script Execution Flow</text>
|
||||
<!-- Background -->
|
||||
<rect x="0" y="0" width="800" height="420" fill="#fafafa"/>
|
||||
|
||||
<!-- start.bas (Raw Text) -->
|
||||
<rect x="250" y="40" width="200" height="40" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
|
||||
<text x="350" y="55" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#90CDF4">start.bas</text>
|
||||
<text x="350" y="70" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#CBD5E0">(Raw Text)</text>
|
||||
<!-- Background accent circles for depth -->
|
||||
<circle cx="120" cy="90" r="45" fill="#667eea" opacity="0.04"/>
|
||||
<circle cx="400" cy="90" r="65" fill="#00d2ff" opacity="0.04"/>
|
||||
<circle cx="650" cy="90" r="40" fill="#ffa500" opacity="0.04"/>
|
||||
<circle cx="650" cy="230" r="50" fill="#ff6b6b" opacity="0.04"/>
|
||||
<circle cx="400" cy="330" r="55" fill="#4facfe" opacity="0.04"/>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="350" y1="60" x2="350" y2="90" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
|
||||
<!-- Title with background -->
|
||||
<rect x="250" y="15" width="300" height="35" fill="rgba(99, 102, 241, 0.05)" rx="8"/>
|
||||
<text x="400" y="38" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="19" font-weight="600" fill="#1e293b">
|
||||
BASIC LLM Tool Execution Flow
|
||||
</text>
|
||||
|
||||
<!-- Tokenizer -->
|
||||
<rect x="200" y="90" width="300" height="60" fill="none" stroke="#F6AD55" stroke-width="2" rx="8"/>
|
||||
<text x="350" y="110" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBD38D">Tokenizer (Rhai)</text>
|
||||
<text x="350" y="130" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FED7AA">• Split into tokens</text>
|
||||
<text x="350" y="145" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FED7AA">• Identify keywords</text>
|
||||
<!-- Stage 1: User Input -->
|
||||
<rect x="50" y="70" width="140" height="55" fill="url(#userGrad)" stroke="#667eea" stroke-width="2" rx="10" filter="url(#shadow)"/>
|
||||
<text x="120" y="95" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#1e293b">USER</text>
|
||||
<text x="120" y="112" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#475569">"What's the policy?"</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="350" y1="150" x2="350" y2="160" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
|
||||
<!-- Elegant flow arrow 1 -->
|
||||
<path d="M 190 97 C 220 97, 230 97, 260 97" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrow)" opacity="0.7" stroke-linecap="round"/>
|
||||
|
||||
<!-- Parser -->
|
||||
<rect x="200" y="160" width="300" height="80" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
|
||||
<text x="350" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">Parser (AST)</text>
|
||||
<text x="350" y="205" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">• Build syntax tree</text>
|
||||
<text x="350" y="220" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">• Validate structure</text>
|
||||
<!-- Stage 2: LLM Processing -->
|
||||
<rect x="260" y="70" width="280" height="55" fill="url(#llmGrad)" stroke="#00d2ff" stroke-width="2" rx="10" filter="url(#shadow)"/>
|
||||
<text x="400" y="95" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#1e293b">LLM + CONTEXT</text>
|
||||
<text x="400" y="112" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#475569">Understands intent + loaded KBs</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="350" y1="240" x2="350" y2="270" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
|
||||
<!-- Elegant flow arrow 2 -->
|
||||
<path d="M 540 97 C 560 97, 580 97, 600 97" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrow)" opacity="0.7" stroke-linecap="round"/>
|
||||
|
||||
<!-- Keyword Mapping -->
|
||||
<rect x="200" y="270" width="300" height="80" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
|
||||
<text x="350" y="295" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">Keyword Mapping</text>
|
||||
<text x="350" y="315" text-anchor="middle" font-family="monospace" font-size="10" fill="#9AE6B4">TALK → talk_handler</text>
|
||||
<text x="350" y="330" text-anchor="middle" font-family="monospace" font-size="10" fill="#9AE6B4">HEAR → hear_handler</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="350" y1="350" x2="350" y2="380" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
|
||||
|
||||
<!-- Runtime Execution -->
|
||||
<rect x="100" y="380" width="500" height="150" fill="none" stroke="#4A5568" stroke-width="2" rx="10" stroke-dasharray="5,5" opacity="0.6"/>
|
||||
<text x="350" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#A0AEC0">Runtime Execution</text>
|
||||
|
||||
<!-- Execution boxes inside -->
|
||||
<g id="execution-flow">
|
||||
<!-- Line 1: TALK -->
|
||||
<rect x="140" y="430" width="100" height="40" fill="none" stroke="#63B3ED" stroke-width="1" rx="5"/>
|
||||
<text x="190" y="445" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#90CDF4">Line 1</text>
|
||||
<text x="190" y="460" text-anchor="middle" font-family="monospace" font-size="10" fill="#CBD5E0">TALK</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<line x1="240" y1="450" x2="280" y2="450" stroke="#888" stroke-width="1" marker-end="url(#arrow)"/>
|
||||
|
||||
<!-- Line 2: HEAR -->
|
||||
<rect x="280" y="430" width="100" height="40" fill="none" stroke="#F6AD55" stroke-width="1" rx="5"/>
|
||||
<text x="330" y="445" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FBD38D">Line 2</text>
|
||||
<text x="330" y="460" text-anchor="middle" font-family="monospace" font-size="10" fill="#CBD5E0">HEAR</text>
|
||||
|
||||
<!-- Arrow down -->
|
||||
<line x1="330" y1="470" x2="330" y2="480" stroke="#888" stroke-width="1" marker-end="url(#arrow)"/>
|
||||
|
||||
<!-- Line 3: IF/THEN -->
|
||||
<rect x="280" y="480" width="100" height="40" fill="none" stroke="#B794F4" stroke-width="1" rx="5"/>
|
||||
<text x="330" y="495" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#D6BCFA">Line 3</text>
|
||||
<text x="330" y="510" text-anchor="middle" font-family="monospace" font-size="10" fill="#CBD5E0">IF/THEN</text>
|
||||
|
||||
<!-- Arrow -->
|
||||
<line x1="380" y1="500" x2="420" y2="500" stroke="#888" stroke-width="1" marker-end="url(#arrow)"/>
|
||||
|
||||
<!-- Line 4: Action -->
|
||||
<rect x="420" y="480" width="100" height="40" fill="none" stroke="#48BB78" stroke-width="1" rx="5"/>
|
||||
<text x="470" y="495" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">Line 4</text>
|
||||
<text x="470" y="510" text-anchor="middle" font-family="monospace" font-size="10" fill="#CBD5E0">Action</text>
|
||||
<!-- Stage 3: Decision Diamond -->
|
||||
<g filter="url(#glow)">
|
||||
<path d="M 650 70 L 700 97 L 650 124 L 600 97 Z" fill="rgba(139, 92, 246, 0.15)" stroke="#8b5cf6" stroke-width="2.5"/>
|
||||
<circle cx="650" cy="97" r="10" fill="#8b5cf6" opacity="0.3"/>
|
||||
<text x="650" y="102" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#1e293b">Tool?</text>
|
||||
</g>
|
||||
|
||||
<!-- Arrow down from Runtime -->
|
||||
<line x1="350" y1="530" x2="350" y2="560" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
|
||||
<!-- Direct Response Path - graceful curve -->
|
||||
<path d="M 650 70 C 650 40, 500 40, 400 40 C 280 40, 140 40, 140 170"
|
||||
stroke="url(#directPathGrad)" stroke-width="2.5" fill="none" marker-end="url(#arrowGreen)"
|
||||
stroke-dasharray="8,4" opacity="0.6" stroke-linecap="round"/>
|
||||
|
||||
<!-- User Response -->
|
||||
<rect x="250" y="560" width="200" height="60" fill="none" stroke="#FC8181" stroke-width="2" rx="8"/>
|
||||
<text x="350" y="585" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">User Response</text>
|
||||
<text x="350" y="605" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FEB2B2">Output/Interaction</text>
|
||||
<!-- Label for direct path -->
|
||||
<rect x="350" y="25" width="100" height="22" fill="rgba(16, 185, 129, 0.1)" rx="5"/>
|
||||
<text x="400" y="40" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="500" fill="#047857">Direct Answer</text>
|
||||
|
||||
<!-- Process steps on the side -->
|
||||
<g id="process-steps" font-family="Arial, sans-serif" font-size="12" fill="#718096">
|
||||
<text x="50" y="60" text-anchor="end">1. Source</text>
|
||||
<text x="50" y="120" text-anchor="end">2. Tokenize</text>
|
||||
<text x="50" y="200" text-anchor="end">3. Parse</text>
|
||||
<text x="50" y="310" text-anchor="end">4. Map</text>
|
||||
<text x="50" y="450" text-anchor="end">5. Execute</text>
|
||||
<text x="50" y="580" text-anchor="end">6. Output</text>
|
||||
<!-- Tool Path - smooth descent -->
|
||||
<path d="M 650 124 C 650 160, 650 170, 650 200" stroke="url(#toolPathGrad)" stroke-width="3" fill="none" marker-end="url(#arrowOrange)" opacity="0.8" stroke-linecap="round"/>
|
||||
|
||||
<!-- Label for tool path -->
|
||||
<text x="670" y="165" text-anchor="start" font-family="system-ui, sans-serif" font-size="10" font-weight="500" fill="#d97706">Call Tool</text>
|
||||
|
||||
<!-- Stage 4: BASIC Tool -->
|
||||
<rect x="560" y="200" width="180" height="75" fill="url(#toolGrad)" stroke="#ff6b6b" stroke-width="2" rx="10" filter="url(#shadow)"/>
|
||||
<text x="650" y="225" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#1e293b">BASIC TOOL</text>
|
||||
<text x="650" y="245" text-anchor="middle" font-family="system-ui, monospace" font-size="10" fill="#475569">enrollment.bas</text>
|
||||
<text x="650" y="260" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">PARAM name, course</text>
|
||||
|
||||
<!-- Tool Return Path - smooth curve -->
|
||||
<path d="M 560 237 C 490 237, 430 220, 400 195" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrow)" opacity="0.6" stroke-linecap="round"/>
|
||||
|
||||
<!-- Stage 5: Response Generation -->
|
||||
<rect x="310" y="170" width="180" height="55" fill="url(#responseGrad)" stroke="#4facfe" stroke-width="2" rx="10" filter="url(#shadow)"/>
|
||||
<text x="400" y="195" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#1e293b">RESPONSE</text>
|
||||
<text x="400" y="212" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#475569">Generate natural answer</text>
|
||||
|
||||
<!-- Final Arrow -->
|
||||
<path d="M 310 197 C 280 197, 240 197, 210 197" stroke="#4a5568" stroke-width="2.5" fill="none" marker-end="url(#arrow)" opacity="0.7" stroke-linecap="round"/>
|
||||
|
||||
<!-- Stage 6: Bot Output -->
|
||||
<rect x="50" y="170" width="140" height="55" fill="url(#userGrad)" stroke="#764ba2" stroke-width="2" rx="10" filter="url(#shadow)"/>
|
||||
<text x="120" y="195" text-anchor="middle" font-family="system-ui, sans-serif" font-size="14" font-weight="600" fill="#1e293b">BOT</text>
|
||||
<text x="120" y="212" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#475569">"30-day return..."</text>
|
||||
|
||||
<!-- Memory Store - elegant and subtle -->
|
||||
<rect x="350" y="290" width="320" height="55" fill="url(#memoryGrad)" stroke="#f5576c" stroke-width="1.5" stroke-dasharray="6,3" rx="10" opacity="0.8"/>
|
||||
<text x="510" y="315" text-anchor="middle" font-family="system-ui, sans-serif" font-size="13" font-weight="500" fill="#1e293b">MEMORY STORE</text>
|
||||
<text x="510" y="332" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" fill="#475569">BOT_MEMORY • Session State • Context</text>
|
||||
|
||||
<!-- Memory connection - delicate -->
|
||||
<path d="M 650 275 L 650 290" stroke="#f5576c" stroke-width="1.5" stroke-dasharray="4,4" fill="none" opacity="0.4"/>
|
||||
<path d="M 400 225 L 400 290" stroke="#4facfe" stroke-width="1.5" stroke-dasharray="4,4" fill="none" opacity="0.4"/>
|
||||
|
||||
<!-- Performance metrics -->
|
||||
<rect x="50" y="370" width="700" height="35" fill="rgba(99, 102, 241, 0.05)" stroke="#8b5cf6" stroke-width="1" stroke-dasharray="6,3" rx="8"/>
|
||||
<text x="400" y="392" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#475569" font-style="italic">
|
||||
LLM decides tool calls • Zero IF/THEN logic • Natural conversation flow • Context-aware responses
|
||||
</text>
|
||||
|
||||
<!-- Legend -->
|
||||
<g transform="translate(50, 260)">
|
||||
<text x="0" y="0" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#1e293b">Legend:</text>
|
||||
<circle cx="10" cy="15" r="4" fill="#10b981"/>
|
||||
<text x="20" y="19" font-family="system-ui, sans-serif" font-size="9" fill="#475569">Direct response</text>
|
||||
<circle cx="10" cy="30" r="4" fill="#f59e0b"/>
|
||||
<text x="20" y="34" font-family="system-ui, sans-serif" font-size="9" fill="#475569">Tool invocation</text>
|
||||
</g>
|
||||
</svg>
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 6.1 KiB After Width: | Height: | Size: 10 KiB |
|
|
@ -53,108 +53,7 @@ TALK summary
|
|||
|
||||
## Execution Flow
|
||||
|
||||
<svg width="800" height="380" viewBox="0 0 800 380" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
|
||||
<!-- Title -->
|
||||
<text x="400" y="25" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="300" fill="currentColor" opacity="0.9">BASIC LLM Tool Execution Flow</text>
|
||||
|
||||
<!-- Define gradients and filters -->
|
||||
<defs>
|
||||
<!-- Soft glow filter -->
|
||||
<filter id="glow">
|
||||
<feGaussianBlur stdDeviation="3" result="coloredBlur"/>
|
||||
<feMerge>
|
||||
<feMergeNode in="coloredBlur"/>
|
||||
<feMergeNode in="SourceGraphic"/>
|
||||
</feMerge>
|
||||
</filter>
|
||||
|
||||
<!-- Beautiful gradients with colors -->
|
||||
<linearGradient id="userGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#667eea;stop-opacity:0.15" />
|
||||
<stop offset="100%" style="stop-color:#764ba2;stop-opacity:0.25" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="llmGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#06ffa5;stop-opacity:0.15" />
|
||||
<stop offset="100%" style="stop-color:#00d2ff;stop-opacity:0.25" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="toolGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#ffa500;stop-opacity:0.15" />
|
||||
<stop offset="100%" style="stop-color:#ff6b6b;stop-opacity:0.25" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="responseGrad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" style="stop-color:#4facfe;stop-opacity:0.15" />
|
||||
<stop offset="100%" style="stop-color:#00f2fe;stop-opacity:0.25" />
|
||||
</linearGradient>
|
||||
|
||||
<!-- Arrow markers -->
|
||||
<marker id="arrow" markerWidth="15" markerHeight="15" refX="14" refY="7.5" orient="auto">
|
||||
<path d="M 0 0 L 15 7.5 L 0 15 L 5 7.5 Z" fill="currentColor" opacity="0.6"/>
|
||||
</marker>
|
||||
</defs>
|
||||
|
||||
<!-- Background accent circles for depth -->
|
||||
<circle cx="110" cy="85" r="40" fill="#667eea" opacity="0.05"/>
|
||||
<circle cx="380" cy="85" r="60" fill="#00d2ff" opacity="0.05"/>
|
||||
<circle cx="630" cy="85" r="35" fill="#ffa500" opacity="0.05"/>
|
||||
<circle cx="630" cy="215" r="45" fill="#ff6b6b" opacity="0.05"/>
|
||||
|
||||
<!-- Stage 1: User Input -->
|
||||
<rect x="50" y="60" width="120" height="50" fill="url(#userGrad)" stroke="#667eea" stroke-width="1.5" rx="12" opacity="0.9"/>
|
||||
<text x="110" y="90" text-anchor="middle" font-family="system-ui" font-size="13" font-weight="500" fill="currentColor">USER</text>
|
||||
|
||||
<!-- Elegant flow arrow 1 -->
|
||||
<path d="M 170 85 C 200 85, 210 85, 240 85" stroke="url(#llmGrad)" stroke-width="2.5" fill="none" marker-end="url(#arrow)" opacity="0.7" stroke-linecap="round"/>
|
||||
|
||||
<!-- Stage 2: LLM Processing -->
|
||||
<rect x="240" y="60" width="280" height="50" fill="url(#llmGrad)" stroke="#00d2ff" stroke-width="1.5" rx="12" opacity="0.9"/>
|
||||
<text x="380" y="90" text-anchor="middle" font-family="system-ui" font-size="13" font-weight="500" fill="currentColor">LLM + CONTEXT</text>
|
||||
|
||||
<!-- Elegant flow arrow 2 -->
|
||||
<path d="M 520 85 C 540 85, 560 85, 580 85" stroke="url(#toolGrad)" stroke-width="2.5" fill="none" marker-end="url(#arrow)" opacity="0.7" stroke-linecap="round"/>
|
||||
|
||||
<!-- Stage 3: Decision Diamond -->
|
||||
<path d="M 630 60 L 680 85 L 630 110 L 580 85 Z" fill="rgba(255,165,0,0.1)" stroke="#ffa500" stroke-width="1.5" opacity="0.9"/>
|
||||
<circle cx="630" cy="85" r="8" fill="#ffa500" opacity="0.4"/>
|
||||
|
||||
<!-- Direct Path - graceful curve -->
|
||||
<path d="M 630 60 C 630 35, 500 35, 380 35 C 260 35, 130 35, 130 150"
|
||||
stroke="#4facfe" stroke-width="2" fill="none" marker-end="url(#arrow)"
|
||||
stroke-dasharray="6,3" opacity="0.4" stroke-linecap="round"/>
|
||||
|
||||
<!-- Tool Path - smooth descent -->
|
||||
<path d="M 630 110 C 630 140, 630 150, 630 180" stroke="#ff6b6b" stroke-width="3" fill="none" marker-end="url(#arrow)" opacity="0.8" stroke-linecap="round"/>
|
||||
|
||||
<!-- Stage 4: BASIC Tool -->
|
||||
<rect x="550" y="180" width="160" height="70" fill="url(#toolGrad)" stroke="#ff6b6b" stroke-width="1.5" rx="12" opacity="0.9"/>
|
||||
<text x="630" y="220" text-anchor="middle" font-family="system-ui" font-size="13" font-weight="500" fill="currentColor">BASIC TOOL</text>
|
||||
|
||||
<!-- Tool Return Path - smooth curve -->
|
||||
<path d="M 550 215 C 480 215, 420 200, 380 180" stroke="#4facfe" stroke-width="2.5" fill="none" marker-end="url(#arrow)" opacity="0.6" stroke-linecap="round"/>
|
||||
|
||||
<!-- Stage 5: Response Generation -->
|
||||
<rect x="300" y="150" width="160" height="50" fill="url(#responseGrad)" stroke="#4facfe" stroke-width="1.5" rx="12" opacity="0.9"/>
|
||||
<text x="380" y="180" text-anchor="middle" font-family="system-ui" font-size="13" font-weight="500" fill="currentColor">RESPONSE</text>
|
||||
|
||||
<!-- Final Arrow -->
|
||||
<path d="M 300 175 C 270 175, 230 175, 200 175" stroke="url(#userGrad)" stroke-width="2.5" fill="none" marker-end="url(#arrow)" opacity="0.7" stroke-linecap="round"/>
|
||||
|
||||
<!-- Stage 6: Bot Output -->
|
||||
<rect x="50" y="150" width="120" height="50" fill="url(#userGrad)" stroke="#764ba2" stroke-width="1.5" rx="12" opacity="0.9"/>
|
||||
<text x="110" y="180" text-anchor="middle" font-family="system-ui" font-size="13" font-weight="500" fill="currentColor">BOT</text>
|
||||
|
||||
<!-- Memory Store - elegant and subtle -->
|
||||
<rect x="350" y="270" width="300" height="50" fill="rgba(150,150,150,0.05)" stroke="currentColor" stroke-width="1" stroke-dasharray="6,3" rx="12" opacity="0.3"/>
|
||||
<text x="500" y="300" text-anchor="middle" font-family="system-ui" font-size="11" font-weight="300" fill="currentColor" opacity="0.5">MEMORY</text>
|
||||
|
||||
<!-- Memory connection - delicate -->
|
||||
<path d="M 630 250 L 630 270" stroke="currentColor" stroke-width="1" stroke-dasharray="3,3" fill="none" opacity="0.2"/>
|
||||
|
||||
<!-- Bottom padding for complete view -->
|
||||
<rect x="0" y="350" width="800" height="30" fill="transparent"/>
|
||||
</svg>
|
||||
<img src="./assets/basic-execution-flow.svg" alt="BASIC LLM Tool Execution Flow" style="max-height: 420px; width: 100%; object-fit: contain;">
|
||||
|
||||
## Key Differences from Traditional Chatbots
|
||||
|
||||
|
|
|
|||
|
|
@ -377,3 +377,9 @@ Each directory in `src/` is effectively a gbapp - contribute by adding your own!
|
|||
- [Services](./services.md) - Core services
|
||||
- [Chapter 6: BASIC Reference](../chapter-06-gbdialog/README.md) - BASIC language
|
||||
- [Chapter 9: API](../chapter-09-api/README.md) - API documentation
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -6,21 +6,21 @@ BotServer follows a modular architecture designed for scalability, maintainabili
|
|||
|
||||
### Data Flow Architecture
|
||||
|
||||
|
||||
<img src="./assets/data-flow.svg" alt="BotServer Data Flow Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
### System Architecture
|
||||
|
||||
|
||||
<img src="./assets/system-architecture.svg" alt="BotServer System Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
## Module Dependency Graph
|
||||
|
||||
|
||||
<img src="./assets/module-dependency.svg" alt="Module Dependency Graph" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
## Module Organization
|
||||
|
||||
### Data Flow Through Modules
|
||||
|
||||
|
||||
<img src="./assets/module-data-flow.svg" alt="Data Flow Through Modules" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
### Core Modules
|
||||
|
||||
|
|
|
|||
|
|
@ -108,4 +108,9 @@ theme-title,Company Assistant
|
|||
|
||||
- [config.csv Format](./config-csv.md) - Complete reference
|
||||
- [LLM Configuration](./llm-config.md) - Language model settings
|
||||
- [Parameters](./parameters.md) - All available parameters
|
||||
- [Parameters](./parameters.md) - All available parameters
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -194,4 +194,9 @@ The future of API integration isn't about writing more code - it's about providi
|
|||
|
||||
- [Tool Definition](./tool-definition.md) - Deep dive into creating tools
|
||||
- [External APIs](./external-apis.md) - Connect to any web service
|
||||
- [PARAM Declaration](./param-declaration.md) - Master parameter definitions
|
||||
- [PARAM Declaration](./param-declaration.md) - Master parameter definitions
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -381,4 +381,9 @@ Always test endpoints in your development environment and check the source code
|
|||
- [Chapter 5: BASIC Reference](../chapter-05/README.md) - Script commands
|
||||
- [Chapter 8: Integrations](../chapter-08/README.md) - External service integration
|
||||
- [Chapter 9: Advanced Topics](../chapter-09/README.md) - Advanced API usage
|
||||
- [Chapter 11: Infrastructure](../chapter-11/README.md) - Deployment and hosting
|
||||
- [Chapter 11: Infrastructure](../chapter-11/README.md) - Deployment and hosting
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1 +1,7 @@
|
|||
# Chapter 11: Feature Reference
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1 +1,7 @@
|
|||
# Chapter 13: Contributing
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -31,3 +31,9 @@ This table maps major features of GeneralBots to the chapters and keywords that
|
|||
- [Chapter 8: Integrations](../chapter-08/README.md) - External integrations
|
||||
- [Chapter 10: Development](../chapter-10/README.md) - Development tools
|
||||
- [Chapter 12: Web API](../chapter-12/README.md) - REST and WebSocket APIs
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1 +1,7 @@
|
|||
# Chapter 11: Authentication
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -83,3 +83,9 @@ RETURN true
|
|||
- [Chapter 9: Storage](../chapter-09/storage.md) - Storage architecture
|
||||
- [Chapter 10: Development](../chapter-10/README.md) - Development environment
|
||||
- [Chapter 12: Web API](../chapter-12/README.md) - API endpoints
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1 +1,7 @@
|
|||
# Chapter 12: REST API Reference
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1 +1,7 @@
|
|||
# Chapter 10: REST API Reference
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -312,4 +312,9 @@ Welcome to the community!
|
|||
- [Chapter 6: Extensions](../chapter-06/README.md) - Extending BotServer
|
||||
- [Chapter 9: Advanced Topics](../chapter-09/README.md) - Advanced features
|
||||
- [Chapter 11: Infrastructure](../chapter-11/README.md) - Deployment and infrastructure
|
||||
- [Chapter 12: Web API](../chapter-12/README.md) - REST and WebSocket APIs
|
||||
- [Chapter 12: Web API](../chapter-12/README.md) - REST and WebSocket APIs
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -58,4 +58,10 @@ General Bots is open source and we welcome contributions:
|
|||
---
|
||||
|
||||
*General Bots® - Enterprise conversational AI platform*
|
||||
*Copyright © 2016-2025 Pragmatismo Inovações Ltda.*
|
||||
*Copyright © 2016-2025 Pragmatismo Inovações Ltda.*
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
@ -238,4 +238,10 @@ Quick lookup for General Bots terms. If you're lost, start here.
|
|||
|
||||
**"Can I use TypeScript/Python/etc?"** - BASIC is used for conversation logic. However, you can integrate with any language through APIs. See [API documentation](./chapter-10-api/README.md) for REST endpoints and integration options.
|
||||
|
||||
**"Is it production-ready?"** - Yes. Used in production since 2016 (earlier versions), current Rust version since 2023.
|
||||
**"Is it production-ready?"** - Yes. Used in production since 2016 (earlier versions), current Rust version since 2023.
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
@ -31,7 +31,7 @@ Bot: Welcome to Computer Science, Sarah!
|
|||
|
||||
### The Flow
|
||||
|
||||
|
||||
<img src="./assets/conversation-flow.svg" alt="Conversation Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
The AI handles everything else - understanding intent, collecting information, executing tools, answering from documents. Zero configuration.
|
||||
|
||||
|
|
@ -64,7 +64,7 @@ Create `.bas` files that the AI discovers and calls automatically. Need to save
|
|||
|
||||
General Bots is a single binary that includes everything:
|
||||
|
||||
|
||||
<img src="./assets/architecture.svg" alt="General Bots Architecture" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
One process, one port, one command to run. Deploy anywhere - laptop, server, container.
|
||||
|
||||
|
|
@ -115,7 +115,7 @@ my-bot.gbai/ # Package root
|
|||
|
||||
### How It Works
|
||||
|
||||
|
||||
<img src="./assets/package-system-flow.svg" alt="Package System Flow" style="max-height: 400px; width: 100%; object-fit: contain;">
|
||||
|
||||
That's it. No XML, no JSON schemas, no build process. Copy the folder to deploy.
|
||||
|
||||
|
|
@ -170,4 +170,9 @@ General Bots is open source (AGPL-3.0) developed by Pragmatismo.com.br and contr
|
|||
- **Version**: 6.0.8
|
||||
- **Status**: Production Ready
|
||||
|
||||
Ready to build your bot? Turn to [Chapter 01](./chapter-01/README.md) and let's go!
|
||||
Ready to build your bot? Turn to [Chapter 01](./chapter-01/README.md) and let's go!
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<img src="https://pragmatismo.com.br/icons/general-bots-text.svg" alt="General Bots" width="200">
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue