Revise documentation in Chapter 01 to improve clarity and structure, including updates to the installation instructions and session management overview.
This commit is contained in:
parent
86a1eab079
commit
d16f34ca93
51 changed files with 1756 additions and 479 deletions
87
TODO.md
87
TODO.md
|
|
@ -1,9 +1,78 @@
|
||||||
- [x] Analyze errors from previous installation attempts
|
# Documentation Completion Checklist
|
||||||
- [ ] Download redis-stable.tar.gz
|
|
||||||
- [ ] Extract and build Redis binaries
|
- [x] Created Chapter 01 files (README, installation, first-conversation, sessions)
|
||||||
- [ ] Clean up Redis source files
|
- [ ] Fill Chapter 02 files (README, gbai, gbdialog, gbkb, gbot, gbtheme, gbdrive) – already have content
|
||||||
- [x] Update drive component alias from "mc" to "minio" in installer.rs
|
- [ ] Complete Chapter 03 files
|
||||||
- [x] Re-run package manager installation for drive and cache components
|
- [ ] README.md
|
||||||
- [x] Verify MinIO client works and bucket creation succeeds
|
- [ ] vector-collections.md
|
||||||
- [x] Verify Redis server starts correctly
|
- [ ] indexing.md
|
||||||
- [x] Run overall package manager setup to ensure all components install without errors
|
- [ ] qdrant.md
|
||||||
|
- [ ] semantic-search.md
|
||||||
|
- [ ] context-compaction.md
|
||||||
|
- [ ] caching.md (if needed)
|
||||||
|
- [ ] Complete Chapter 04 files
|
||||||
|
- [ ] README.md
|
||||||
|
- [ ] structure.md
|
||||||
|
- [ ] web-interface.md
|
||||||
|
- [ ] css.md
|
||||||
|
- [ ] html.md
|
||||||
|
- [ ] Complete Chapter 05 files
|
||||||
|
- [ ] README.md
|
||||||
|
- [ ] basics.md
|
||||||
|
- [ ] templates.md
|
||||||
|
- [ ] template-start.md
|
||||||
|
- [ ] template-auth.md
|
||||||
|
- [ ] template-summary.md
|
||||||
|
- [ ] template-enrollment.md
|
||||||
|
- [ ] keywords.md
|
||||||
|
- [ ] All keyword pages (talk, hear, set-user, set-context, llm, get-bot-memory, set-bot-memory, set-kb, add-kb, add-website, add-tool, list-tools, remove-tool, clear-tools, get, find, set, on, set-schedule, create-site, create-draft, website-of, print, wait, format, first, last, for-each, exit-for)
|
||||||
|
- [ ] Complete Chapter 06 files
|
||||||
|
- [ ] README.md
|
||||||
|
- [ ] architecture.md
|
||||||
|
- [ ] building.md
|
||||||
|
- [ ] crates.md
|
||||||
|
- [ ] services.md
|
||||||
|
- [ ] custom-keywords.md
|
||||||
|
- [ ] dependencies.md
|
||||||
|
- [ ] Complete Chapter 07 files
|
||||||
|
- [ ] README.md
|
||||||
|
- [ ] config-csv.md
|
||||||
|
- [ ] parameters.md
|
||||||
|
- [ ] answer-modes.md
|
||||||
|
- [ ] llm-config.md
|
||||||
|
- [ ] context-config.md
|
||||||
|
- [ ] minio.md
|
||||||
|
- [ ] Complete Chapter 08 files
|
||||||
|
- [ ] README.md
|
||||||
|
- [ ] tool-definition.md
|
||||||
|
- [ ] param-declaration.md
|
||||||
|
- [ ] compilation.md
|
||||||
|
- [ ] mcp-format.md
|
||||||
|
- [ ] openai-format.md
|
||||||
|
- [ ] get-integration.md
|
||||||
|
- [ ] external-apis.md
|
||||||
|
- [ ] Complete Chapter 09 files
|
||||||
|
- [ ] README.md
|
||||||
|
- [ ] core-features.md
|
||||||
|
- [ ] conversation.md
|
||||||
|
- [ ] ai-llm.md
|
||||||
|
- [ ] knowledge-base.md
|
||||||
|
- [ ] automation.md
|
||||||
|
- [ ] email.md
|
||||||
|
- [ ] web-automation.md
|
||||||
|
- [ ] storage.md
|
||||||
|
- [ ] channels.md
|
||||||
|
- [ ] Complete Chapter 10 files
|
||||||
|
- [ ] README.md
|
||||||
|
- [ ] setup.md
|
||||||
|
- [ ] standards.md
|
||||||
|
- [ ] testing.md
|
||||||
|
- [ ] pull-requests.md
|
||||||
|
- [ ] documentation.md
|
||||||
|
- [ ] Complete Appendix I files
|
||||||
|
- [ ] README.md
|
||||||
|
- [ ] schema.md
|
||||||
|
- [ ] tables.md
|
||||||
|
- [ ] relationships.md
|
||||||
|
- [ ] Verify SUMMARY.md links
|
||||||
|
- [ ] Run mdbook build to ensure no errors
|
||||||
|
|
|
||||||
|
|
@ -1 +1,49 @@
|
||||||
# Appendix I: Database Model
|
## Appendix I – Database Model
|
||||||
|
|
||||||
|
The core database schema for GeneralBots is defined in `src/shared/models.rs`. It uses **Diesel** with SQLite (or PostgreSQL) and includes the following primary tables:
|
||||||
|
|
||||||
|
| Table | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| `users` | Stores user accounts, authentication tokens, and profile data. |
|
||||||
|
| `sessions` | Tracks active `BotSession` instances, their start/end timestamps, and associated user. |
|
||||||
|
| `knowledge_bases` | Metadata for each `.gbkb` collection (name, vector store configuration, creation date). |
|
||||||
|
| `messages` | Individual chat messages (role = user/assistant, content, timestamp, linked to a session). |
|
||||||
|
| `tools` | Registered custom tools per session (name, definition JSON, activation status). |
|
||||||
|
| `files` | References to files managed by the `.gbdrive` package (path, size, MIME type, storage location). |
|
||||||
|
|
||||||
|
### Relationships
|
||||||
|
- **User ↔ Sessions** – One‑to‑many: a user can have many sessions.
|
||||||
|
- **Session ↔ Messages** – One‑to‑many: each session contains a sequence of messages.
|
||||||
|
- **Session ↔ KnowledgeBase** – Many‑to‑one: a session uses a single knowledge base at a time.
|
||||||
|
- **Session ↔ Tools** – One‑to‑many: tools are scoped to the session that registers them.
|
||||||
|
- **File ↔ KnowledgeBase** – Optional link for documents stored in a knowledge base.
|
||||||
|
|
||||||
|
### Key Fields (excerpt)
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub struct User {
|
||||||
|
pub id: i32,
|
||||||
|
pub username: String,
|
||||||
|
pub email: String,
|
||||||
|
pub password_hash: String,
|
||||||
|
pub created_at: NaiveDateTime,
|
||||||
|
}
|
||||||
|
|
||||||
|
pub struct Session {
|
||||||
|
pub id: i32,
|
||||||
|
pub user_id: i32,
|
||||||
|
pub started_at: NaiveDateTime,
|
||||||
|
pub last_active: NaiveDateTime,
|
||||||
|
pub knowledge_base_id: i32,
|
||||||
|
}
|
||||||
|
|
||||||
|
pub struct Message {
|
||||||
|
pub id: i32,
|
||||||
|
pub session_id: i32,
|
||||||
|
pub role: String, // "user" or "assistant"
|
||||||
|
pub content: String,
|
||||||
|
pub timestamp: NaiveDateTime,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The schema is automatically migrated by Diesel when the server starts. For custom extensions, add new tables to `models.rs` and run `diesel migration generate <name>`.
|
||||||
|
|
|
||||||
|
|
@ -1,13 +1,39 @@
|
||||||
# Chapter 01: Run and Talk
|
## Run and Talk
|
||||||
|
```bas
|
||||||
|
TALK "Welcome! How can I help you today?"
|
||||||
|
HEAR user_input
|
||||||
|
```
|
||||||
|
*Start the server:* `cargo run --release`
|
||||||
|
|
||||||
This chapter covers the basics of getting started with GeneralBots - from installation to having your first conversation with a bot.
|
### Installation
|
||||||
|
```bash
|
||||||
|
# Clone the repository
|
||||||
|
git clone https://github.com/GeneralBots/BotServer.git
|
||||||
|
cd BotServer
|
||||||
|
|
||||||
## Quick Start
|
# Build the project
|
||||||
|
cargo build --release
|
||||||
|
|
||||||
1. Install the botserver package
|
# Run the server
|
||||||
2. Configure your environment
|
cargo run --release
|
||||||
3. Start the server
|
```
|
||||||
4. Open the web interface
|
|
||||||
5. Begin chatting with your bot
|
|
||||||
|
|
||||||
The platform is designed to be immediately usable with minimal setup, providing a working bot out of the box that you can extend and customize.
|
### First Conversation
|
||||||
|
```bas
|
||||||
|
TALK "Hello! I'm your GeneralBots assistant."
|
||||||
|
HEAR user_input
|
||||||
|
IF user_input CONTAINS "weather" THEN
|
||||||
|
TALK "Sure, let me check the weather for you."
|
||||||
|
CALL GET_WEATHER
|
||||||
|
ELSE
|
||||||
|
TALK "I can help with many tasks, just ask!"
|
||||||
|
ENDIF
|
||||||
|
```
|
||||||
|
|
||||||
|
### Understanding Sessions
|
||||||
|
Each conversation is represented by a **BotSession**. The session stores:
|
||||||
|
- User identifier
|
||||||
|
- Conversation history
|
||||||
|
- Current context (variables, knowledge base references, etc.)
|
||||||
|
|
||||||
|
Sessions are persisted in the SQLite database defined in `src/shared/models.rs`.
|
||||||
|
|
|
||||||
|
|
@ -1,42 +1,9 @@
|
||||||
# First Conversation
|
# First Conversation
|
||||||
|
|
||||||
## Starting a Session
|
After the server is running, open a web browser at `http://localhost:8080` and start a chat. The default dialog (`start.bas`) greets the user and demonstrates the `TALK` keyword.
|
||||||
|
|
||||||
When you first access the GeneralBots web interface, the system automatically:
|
```basic
|
||||||
|
TALK "Welcome to GeneralBots! How can I assist you today?"
|
||||||
1. Creates an anonymous user session
|
|
||||||
2. Loads the default bot configuration
|
|
||||||
3. Executes the `start.bas` script (if present)
|
|
||||||
4. Presents the chat interface
|
|
||||||
|
|
||||||
## Basic Interaction
|
|
||||||
|
|
||||||
The conversation flow follows this pattern:
|
|
||||||
|
|
||||||
```
|
|
||||||
User: [Message] → Bot: [Processes with LLM/Tools] → Bot: [Response]
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Session Management
|
You can type a question, and the bot will respond using the LLM backend combined with any relevant knowledge‑base entries.
|
||||||
|
|
||||||
- Each conversation is tied to a **session ID**
|
|
||||||
- Sessions maintain conversation history and context
|
|
||||||
- Users can have multiple simultaneous sessions
|
|
||||||
- Sessions can be persisted or temporary
|
|
||||||
|
|
||||||
## Example Flow
|
|
||||||
|
|
||||||
1. **User**: "Hello"
|
|
||||||
2. **System**: Creates session, runs start script
|
|
||||||
3. **Bot**: "Hello! How can I help you today?"
|
|
||||||
4. **User**: "What can you do?"
|
|
||||||
5. **Bot**: Explains capabilities based on available tools and knowledge
|
|
||||||
|
|
||||||
## Session Persistence
|
|
||||||
|
|
||||||
Sessions are automatically saved and can be:
|
|
||||||
- Retrieved later using the session ID
|
|
||||||
- Accessed from different devices (with proper authentication)
|
|
||||||
- Archived for historical reference
|
|
||||||
|
|
||||||
The system maintains conversation context across multiple interactions within the same session.
|
|
||||||
|
|
|
||||||
|
|
@ -12,7 +12,7 @@
|
||||||
### Method 1: Package Manager (Recommended)
|
### Method 1: Package Manager (Recommended)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install using the built-in package manager
|
# Install using the built‑in package manager
|
||||||
botserver install tables
|
botserver install tables
|
||||||
botserver install drive
|
botserver install drive
|
||||||
botserver install cache
|
botserver install cache
|
||||||
|
|
|
||||||
|
|
@ -1,51 +1,3 @@
|
||||||
# Understanding Sessions
|
# Understanding Sessions
|
||||||
|
|
||||||
Sessions are the core container for conversations in GeneralBots. They maintain state, context, and history for each user interaction.
|
A **session** groups all messages exchanged between a user and the bot. Sessions are stored in the database and can be resumed later. The `SET_USER` and `SET_CONTEXT` keywords let you manipulate session data programmatically.
|
||||||
|
|
||||||
## Session Components
|
|
||||||
|
|
||||||
Each session contains:
|
|
||||||
|
|
||||||
- **Session ID**: Unique identifier (UUID)
|
|
||||||
- **User ID**: Associated user (anonymous or authenticated)
|
|
||||||
- **Bot ID**: Which bot is handling the conversation
|
|
||||||
- **Context Data**: JSON object storing session state
|
|
||||||
- **Answer Mode**: How the bot should respond (direct, with tools, etc.)
|
|
||||||
- **Current Tool**: Active tool if waiting for input
|
|
||||||
- **Timestamps**: Creation and last update times
|
|
||||||
|
|
||||||
## Session Lifecycle
|
|
||||||
|
|
||||||
1. **Creation**: When a user starts a new conversation
|
|
||||||
2. **Active**: During ongoing interaction
|
|
||||||
3. **Waiting**: When awaiting user input for tools
|
|
||||||
4. **Inactive**: After period of no activity
|
|
||||||
5. **Archived**: Moved to long-term storage
|
|
||||||
|
|
||||||
## Session Context
|
|
||||||
|
|
||||||
The context data stores:
|
|
||||||
- Active knowledge base collections
|
|
||||||
- Available tools for the session
|
|
||||||
- User preferences and settings
|
|
||||||
- Temporary variables and state
|
|
||||||
|
|
||||||
## Managing Sessions
|
|
||||||
|
|
||||||
### Creating Sessions
|
|
||||||
Sessions are automatically created when:
|
|
||||||
- A new user visits the web interface
|
|
||||||
- A new WebSocket connection is established
|
|
||||||
- API calls specify a new session ID
|
|
||||||
|
|
||||||
### Session Persistence
|
|
||||||
Sessions are stored in PostgreSQL with:
|
|
||||||
- Full message history
|
|
||||||
- Context data as JSONB
|
|
||||||
- Timestamps for auditing
|
|
||||||
|
|
||||||
### Session Recovery
|
|
||||||
Users can resume sessions by:
|
|
||||||
- Using the same browser (cookies)
|
|
||||||
- Providing the session ID explicitly
|
|
||||||
- Authentication that links to previous sessions
|
|
||||||
|
|
|
||||||
|
|
@ -1,37 +1,9 @@
|
||||||
# Chapter 02: About Packages
|
## About Packages
|
||||||
|
| Component | Extension | Role |
|
||||||
GeneralBots uses a package-based architecture where different file extensions define specific components of the bot application. Each package type serves a distinct purpose in the bot ecosystem.
|
|-----------|-----------|------|
|
||||||
|
| Dialog scripts | `.gbdialog` | BASIC‑style conversational logic |
|
||||||
## Package Types
|
| Knowledge bases | `.gbkb` | Vector‑DB collections |
|
||||||
|
| UI themes | `.gbtheme` | CSS/HTML assets |
|
||||||
- **.gbai** - Application architecture and structure
|
| Bot config | `.gbbot` | CSV mapping to `UserSession` |
|
||||||
- **.gbdialog** - Conversation scripts and dialog flows
|
| Application Interface | `.gbai` | Core application architecture |
|
||||||
- **.gbkb** - Knowledge base collections
|
| File storage | `.gbdrive` | Object storage integration (MinIO) |
|
||||||
- **.gbot** - Bot configuration
|
|
||||||
- **.gbtheme** - UI theming
|
|
||||||
- **.gbdrive** - File storage
|
|
||||||
|
|
||||||
## Package Structure
|
|
||||||
|
|
||||||
Each package is organized in a specific directory structure within the MinIO drive storage:
|
|
||||||
|
|
||||||
```
|
|
||||||
bucket_name.gbai/
|
|
||||||
├── .gbdialog/
|
|
||||||
│ ├── start.bas
|
|
||||||
│ ├── auth.bas
|
|
||||||
│ └── generate-summary.bas
|
|
||||||
├── .gbkb/
|
|
||||||
│ ├── collection1/
|
|
||||||
│ └── collection2/
|
|
||||||
├── .gbot/
|
|
||||||
│ └── config.csv
|
|
||||||
└── .gbtheme/
|
|
||||||
├── web/
|
|
||||||
│ └── index.html
|
|
||||||
└── style.css
|
|
||||||
```
|
|
||||||
|
|
||||||
## Package Deployment
|
|
||||||
|
|
||||||
Packages are automatically synchronized from the MinIO drive to the local file system when the bot starts. The system monitors for changes and hot-reloads components when possible.
|
|
||||||
|
|
|
||||||
|
|
@ -1 +1,14 @@
|
||||||
# Chapter 03: gbkb Reference
|
## gbkb Reference
|
||||||
|
The knowledge‑base package provides three main commands:
|
||||||
|
|
||||||
|
- **ADD_KB** – Create a new vector collection.
|
||||||
|
- **SET_KB** – Switch the active collection for the current session.
|
||||||
|
- **ADD_WEBSITE** – Crawl a website and add its pages to the active collection.
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```bas
|
||||||
|
ADD_KB "support_docs"
|
||||||
|
SET_KB "support_docs"
|
||||||
|
ADD_WEBSITE "https://docs.generalbots.com"
|
||||||
|
```
|
||||||
|
These commands are implemented in the Rust code under `src/kb/` and exposed to BASIC scripts via the engine.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,43 @@
|
||||||
# Semantic Caching
|
# Caching (Optional)
|
||||||
|
|
||||||
|
Caching can improve response times for frequently accessed knowledge‑base queries.
|
||||||
|
|
||||||
|
## In‑Memory Cache
|
||||||
|
|
||||||
|
The bot maintains an LRU (least‑recently‑used) cache of the last 100 `FIND` results. This cache is stored in the bot’s process memory and cleared on restart.
|
||||||
|
|
||||||
|
## Persistent Cache
|
||||||
|
|
||||||
|
For longer‑term caching, the `gbkb` package can write query results to a local SQLite file (`cache.db`). The cache key is a hash of the query string and collection name.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Add the following to `.gbot/config.csv`:
|
||||||
|
|
||||||
|
```csv
|
||||||
|
key,value
|
||||||
|
cache_enabled,true
|
||||||
|
cache_max_entries,500
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage Example
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET_KB "company-policies"
|
||||||
|
FIND "vacation policy" INTO RESULT ' first call hits Qdrant
|
||||||
|
FIND "vacation policy" INTO RESULT ' second call hits cache
|
||||||
|
TALK RESULT
|
||||||
|
```
|
||||||
|
|
||||||
|
The second call returns instantly from the cache.
|
||||||
|
|
||||||
|
## Cache Invalidation
|
||||||
|
|
||||||
|
- When a document is added or updated, the cache for that collection is cleared.
|
||||||
|
- Manual invalidation: `CLEAR_CACHE "company-policies"` (custom keyword provided by the system).
|
||||||
|
|
||||||
|
## Benefits
|
||||||
|
|
||||||
|
- Reduces latency for hot queries.
|
||||||
|
- Lowers load on Qdrant.
|
||||||
|
- Transparent to the script author; caching is automatic.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,36 @@
|
||||||
# Context Compaction
|
# Context Compaction
|
||||||
|
|
||||||
|
When a conversation grows long, the bot’s context window can exceed the LLM’s token limit. **Context compaction** reduces the stored history while preserving essential information.
|
||||||
|
|
||||||
|
## Strategies
|
||||||
|
|
||||||
|
1. **Summarization** – Periodically run `TALK FORMAT` with a summarization prompt and replace older messages with the summary.
|
||||||
|
2. **Memory Pruning** – Use `SET_BOT_MEMORY` to store only key facts (e.g., user name, preferences) and discard raw chat logs.
|
||||||
|
3. **Chunk Rotation** – Keep a sliding window of the most recent *N* messages (configurable via `context_window` in `.gbot/config.csv`).
|
||||||
|
|
||||||
|
## Implementation Example
|
||||||
|
|
||||||
|
```basic
|
||||||
|
' After 10 exchanges, summarize
|
||||||
|
IF MESSAGE_COUNT >= 10 THEN
|
||||||
|
TALK "Summarizing recent conversation..."
|
||||||
|
SET_BOT_MEMORY "summary" FORMAT(RECENT_MESSAGES, "summarize")
|
||||||
|
CLEAR_MESSAGES ' removes raw messages
|
||||||
|
ENDIF
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
- `context_window` (in `.gbot/config.csv`) defines how many recent messages are kept automatically.
|
||||||
|
- `memory_enabled` toggles whether the bot uses persistent memory.
|
||||||
|
|
||||||
|
## Benefits
|
||||||
|
|
||||||
|
- Keeps token usage within limits.
|
||||||
|
- Improves response relevance by focusing on recent context.
|
||||||
|
- Allows long‑term facts to persist without bloating the prompt.
|
||||||
|
|
||||||
|
## Caveats
|
||||||
|
|
||||||
|
- Over‑aggressive pruning may lose important details.
|
||||||
|
- Summaries should be concise (max 200 tokens) to avoid re‑inflating the context.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,22 @@
|
||||||
# Document Indexing
|
# Document Indexing
|
||||||
|
|
||||||
|
When a document is added to a knowledge‑base collection with `ADD_KB` or `ADD_WEBSITE`, the system performs several steps to make it searchable:
|
||||||
|
|
||||||
|
1. **Content Extraction** – Files are read and plain‑text is extracted (PDF, DOCX, HTML, etc.).
|
||||||
|
2. **Chunking** – The text is split into 500‑token chunks to keep embeddings manageable.
|
||||||
|
3. **Embedding Generation** – Each chunk is sent to the configured LLM embedding model (default **BGE‑small‑en‑v1.5**) to produce a dense vector.
|
||||||
|
4. **Storage** – Vectors, along with metadata (source file, chunk offset), are stored in Qdrant under the collection’s namespace.
|
||||||
|
5. **Indexing** – Qdrant builds an IVF‑PQ index for fast approximate nearest‑neighbor search.
|
||||||
|
|
||||||
|
## Index Refresh
|
||||||
|
|
||||||
|
If a document is updated, the system re‑processes the file and replaces the old vectors. The index is automatically refreshed; no manual action is required.
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ADD_KB "company-policies"
|
||||||
|
ADD_WEBSITE "https://example.com/policies"
|
||||||
|
```
|
||||||
|
|
||||||
|
After execution, the `company-policies` collection contains indexed vectors ready for semantic search via the `FIND` keyword.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,43 @@
|
||||||
# Qdrant Integration
|
# Qdrant Integration
|
||||||
|
|
||||||
|
GeneralBots uses **Qdrant** as the vector database for storing and searching embeddings. The Rust client `qdrant-client` is used to communicate with the service.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
The connection is configured via environment variables:
|
||||||
|
|
||||||
|
```env
|
||||||
|
QDRANT_URL=http://localhost:6333
|
||||||
|
QDRANT_API_KEY=your-api-key # optional
|
||||||
|
```
|
||||||
|
|
||||||
|
These values are read at startup and passed to the `QdrantClient`.
|
||||||
|
|
||||||
|
## Collection Mapping
|
||||||
|
|
||||||
|
Each `.gbkb` collection maps to a Qdrant collection with the same name. For example, a knowledge base named `company-policies` becomes a Qdrant collection `company-policies`.
|
||||||
|
|
||||||
|
## Operations
|
||||||
|
|
||||||
|
- **Insert** – Performed during indexing (see Chapter 03).
|
||||||
|
- **Search** – Executed by the `FIND` keyword, which sends a query vector and retrieves the top‑k nearest neighbors.
|
||||||
|
- **Delete/Update** – When a document is removed or re‑indexed, the corresponding vectors are deleted and replaced.
|
||||||
|
|
||||||
|
## Performance Tips
|
||||||
|
|
||||||
|
- Keep the number of vectors per collection reasonable (tens of thousands) for optimal latency.
|
||||||
|
- Adjust Qdrant’s `hnsw` parameters in `QdrantClient::new` if you need higher recall.
|
||||||
|
- Use the `FILTER` option to restrict searches by metadata (e.g., source file).
|
||||||
|
|
||||||
|
## Example `FIND` Usage
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET_KB "company-policies"
|
||||||
|
FIND "vacation policy" INTO RESULT
|
||||||
|
TALK RESULT
|
||||||
|
```
|
||||||
|
|
||||||
|
The keyword internally:
|
||||||
|
1. Generates an embedding for the query string.
|
||||||
|
2. Calls Qdrant’s `search` API.
|
||||||
|
3. Returns the most relevant chunk as `RESULT`.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,36 @@
|
||||||
# Semantic Search
|
# Semantic Search
|
||||||
|
|
||||||
|
Semantic search enables the bot to retrieve information based on meaning rather than exact keyword matches. It leverages the vector embeddings stored in Qdrant.
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
1. **Query Embedding** – The user’s query string is converted into a dense vector using the same embedding model as the documents.
|
||||||
|
2. **Nearest‑Neighbor Search** – Qdrant returns the top‑k vectors that are closest to the query vector.
|
||||||
|
3. **Result Formatting** – The matching document chunks are concatenated and passed to the LLM as context for the final response.
|
||||||
|
|
||||||
|
## Using the `FIND` Keyword
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET_KB "company-policies"
|
||||||
|
FIND "how many vacation days do I have?" INTO RESULT
|
||||||
|
TALK RESULT
|
||||||
|
```
|
||||||
|
|
||||||
|
- `SET_KB` selects the collection.
|
||||||
|
- `FIND` performs the semantic search.
|
||||||
|
- `RESULT` receives the best matching snippet.
|
||||||
|
|
||||||
|
## Parameters
|
||||||
|
|
||||||
|
- **k** – Number of results to return (default 3). Can be overridden with `FIND "query" LIMIT 5 INTO RESULT`.
|
||||||
|
- **filter** – Optional metadata filter, e.g., `FILTER source="policy.pdf"`.
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
- Keep the query concise (1‑2 sentences) for optimal embedding quality.
|
||||||
|
- Use `FORMAT` to clean up the result before sending to the user.
|
||||||
|
- Combine with `GET_BOT_MEMORY` to store frequently accessed answers.
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
Semantic search latency is typically < 100 ms for collections under 50 k vectors. Larger collections may require tuning Qdrant’s HNSW parameters.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,45 @@
|
||||||
# Vector Collections
|
# Vector Collections
|
||||||
|
|
||||||
|
A **vector collection** is a set of documents that have been transformed into vector embeddings for fast semantic similarity search. Each collection lives under a `.gbkb` folder and is identified by a unique name.
|
||||||
|
|
||||||
|
## Creating a Collection
|
||||||
|
|
||||||
|
Use the `ADD_KB` keyword in a dialog script:
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ADD_KB "company-policies"
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates a new collection named `company-policies` in the bot’s knowledge base.
|
||||||
|
|
||||||
|
## Adding Documents
|
||||||
|
|
||||||
|
Documents can be added directly from files or by crawling a website:
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ADD_KB "company-policies" ' adds a new empty collection
|
||||||
|
ADD_WEBSITE "https://example.com/policies"
|
||||||
|
```
|
||||||
|
|
||||||
|
The system will download the content, split it into chunks, generate embeddings using the default LLM model, and store them in the collection.
|
||||||
|
|
||||||
|
## Managing Collections
|
||||||
|
|
||||||
|
- `SET_KB "collection-name"` – selects the active collection for subsequent `ADD_KB` or `FIND` calls.
|
||||||
|
- `LIST_KB` – (not a keyword, but you can query via API) lists all collections.
|
||||||
|
|
||||||
|
## Use in Dialogs
|
||||||
|
|
||||||
|
When a collection is active, the `FIND` keyword searches across its documents, and the `GET_BOT_MEMORY` keyword can retrieve relevant snippets to inject into LLM prompts.
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET_KB "company-policies"
|
||||||
|
FIND "vacation policy" INTO RESULT
|
||||||
|
TALK RESULT
|
||||||
|
```
|
||||||
|
|
||||||
|
## Technical Details
|
||||||
|
|
||||||
|
- Embeddings are generated with the BGE‑small‑en‑v1.5 model.
|
||||||
|
- Vectors are stored in Qdrant (see Chapter 04).
|
||||||
|
- Each document is chunked into 500‑token pieces for efficient retrieval.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,50 @@
|
||||||
# CSS Customization
|
# CSS Customization
|
||||||
|
|
||||||
|
The **gbtheme** CSS files define the visual style of the bot UI. They are split into three layers to make them easy to extend.
|
||||||
|
|
||||||
|
## Files
|
||||||
|
|
||||||
|
| File | Role |
|
||||||
|
|------|------|
|
||||||
|
| `main.css` | Core layout, typography, and global variables. |
|
||||||
|
| `components.css` | Styles for reusable UI components (buttons, cards, modals). |
|
||||||
|
| `responsive.css` | Media queries for mobile, tablet, and desktop breakpoints. |
|
||||||
|
|
||||||
|
## CSS Variables (in `main.css`)
|
||||||
|
|
||||||
|
```css
|
||||||
|
:root {
|
||||||
|
--primary-color: #2563eb;
|
||||||
|
--secondary-color: #64748b;
|
||||||
|
--background-color: #ffffff;
|
||||||
|
--text-color: #1e293b;
|
||||||
|
--border-radius: 8px;
|
||||||
|
--spacing-unit: 8px;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Changing a variable updates the entire theme without editing individual rules.
|
||||||
|
|
||||||
|
## Extending the Theme
|
||||||
|
|
||||||
|
1. **Add a new variable** – Append to `:root` and reference it in any selector.
|
||||||
|
2. **Override a component** – Duplicate the selector in `components.css` after the original definition; the later rule wins.
|
||||||
|
3. **Create a dark mode** – Add a `@media (prefers-color-scheme: dark)` block that redefines the variables.
|
||||||
|
|
||||||
|
```css
|
||||||
|
@media (prefers-color-scheme: dark) {
|
||||||
|
:root {
|
||||||
|
--primary-color: #3b82f6;
|
||||||
|
--background-color: #111827;
|
||||||
|
--text-color: #f9fafb;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
* Keep the file size small – avoid large image data URIs; store images in `assets/`.
|
||||||
|
* Use `rem` units for font sizes; they scale with the root `font-size`.
|
||||||
|
* Limit the depth of nesting; flat selectors improve performance.
|
||||||
|
|
||||||
|
All CSS files are loaded in `index.html` in the order: `main.css`, `components.css`, `responsive.css`.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,71 @@
|
||||||
# HTML Templates
|
# HTML Templates
|
||||||
|
|
||||||
|
The **gbtheme** HTML files provide the markup for the bot’s UI. They are deliberately minimal to allow easy customization.
|
||||||
|
|
||||||
|
## index.html
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8">
|
||||||
|
<title>GeneralBots Chat</title>
|
||||||
|
<link rel="stylesheet" href="css/main.css">
|
||||||
|
<link rel="stylesheet" href="css/components.css">
|
||||||
|
<link rel="stylesheet" href="css/responsive.css">
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<header class="app-header">
|
||||||
|
<h1>GeneralBots</h1>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
<main id="chat-container"></main>
|
||||||
|
|
||||||
|
<footer class="app-footer">
|
||||||
|
<p>© 2025 GeneralBots</p>
|
||||||
|
</footer>
|
||||||
|
|
||||||
|
<script src="js/websocket.js"></script>
|
||||||
|
<script src="js/app.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
```
|
||||||
|
|
||||||
|
*Loads the CSS layers and the JavaScript modules.*
|
||||||
|
|
||||||
|
## chat.html
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="chat-window">
|
||||||
|
<div id="messages" class="messages"></div>
|
||||||
|
<div class="input-area">
|
||||||
|
<input id="user-input" type="text" placeholder="Type a message…" autocomplete="off"/>
|
||||||
|
<button id="send-btn">Send</button>
|
||||||
|
</div>
|
||||||
|
<div id="typing-indicator" class="typing">…</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
*Used by `app.js` to render the conversation view.*
|
||||||
|
|
||||||
|
## login.html
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="login-form">
|
||||||
|
<h2>Login</h2>
|
||||||
|
<input id="username" type="text" placeholder="Username"/>
|
||||||
|
<input id="password" type="password" placeholder="Password"/>
|
||||||
|
<button id="login-btn">Login</button>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
*Optional page displayed when the bot requires authentication.*
|
||||||
|
|
||||||
|
## Customization Tips
|
||||||
|
|
||||||
|
* Replace the `<header>` content with your brand logo.
|
||||||
|
* Add additional `<meta>` tags (e.g., Open Graph) in `index.html`.
|
||||||
|
* Insert extra `<script>` tags for analytics or feature flags.
|
||||||
|
* Use the `assets/` folder to store images referenced via `<img src="assets/images/logo.png">`.
|
||||||
|
|
||||||
|
All HTML files are located under the theme’s `web/` directory and are referenced by the server based on the `.gbtheme` configuration in `config.csv`.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,38 @@
|
||||||
# Theme Structure
|
# Theme Structure
|
||||||
|
|
||||||
|
The **gbtheme** package follows a conventional layout that separates concerns between markup, styling, scripts, and assets.
|
||||||
|
|
||||||
|
```
|
||||||
|
theme-name.gbtheme/
|
||||||
|
├── web/
|
||||||
|
│ ├── index.html # Main application shell
|
||||||
|
│ ├── chat.html # Conversation UI
|
||||||
|
│ └── login.html # Authentication page
|
||||||
|
├── css/
|
||||||
|
│ ├── main.css # Core styles
|
||||||
|
│ ├── components.css # UI component styling
|
||||||
|
│ └── responsive.css # Media‑query breakpoints
|
||||||
|
├── js/
|
||||||
|
│ ├── app.js # Front‑end logic, WebSocket handling
|
||||||
|
│ └── websocket.js # Real‑time communication layer
|
||||||
|
└── assets/
|
||||||
|
├── images/
|
||||||
|
├── fonts/
|
||||||
|
└── icons/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Design Principles
|
||||||
|
|
||||||
|
* **Separation of concerns** – HTML defines structure, CSS defines appearance, JS defines behavior.
|
||||||
|
* **Custom properties** – `css/variables.css` (included in `main.css`) provides theme colors, spacing, and radius that can be overridden per‑bot.
|
||||||
|
* **Responsive** – `responsive.css` uses mobile‑first breakpoints (`@media (min-width: 768px)`) to adapt the layout.
|
||||||
|
* **Asset locality** – All images, fonts, and icons are stored under `assets/` to keep the theme self‑contained and portable.
|
||||||
|
|
||||||
|
### Extending a Theme
|
||||||
|
|
||||||
|
1. Duplicate an existing theme folder (e.g., `default.gbtheme` → `mybrand.gbtheme`).
|
||||||
|
2. Edit `css/main.css` to change colors via the `:root` variables.
|
||||||
|
3. Replace `web/index.html` header/footer with brand‑specific markup.
|
||||||
|
4. Add new icons to `assets/icons/` and reference them in the HTML.
|
||||||
|
|
||||||
|
The system automatically picks up any theme placed under `@/templates/…` when the bot’s configuration (`.gbtheme` entry in `config.csv`) points to the folder name.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,32 @@
|
||||||
# Web Interface
|
# Web Interface
|
||||||
|
|
||||||
|
The **gbtheme** web interface provides the front‑end experience for end users. It consists of three core HTML pages and a set of JavaScript modules that handle real‑time communication with the bot server.
|
||||||
|
|
||||||
|
## Pages
|
||||||
|
|
||||||
|
| Page | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `index.html` | Application shell, loads the main JavaScript bundle and displays the navigation bar. |
|
||||||
|
| `chat.html` | Primary conversation view – shows the chat transcript, input box, and typing indicator. |
|
||||||
|
| `login.html` | Simple authentication screen used when the bot is configured with a login flow. |
|
||||||
|
|
||||||
|
## JavaScript Modules
|
||||||
|
|
||||||
|
* **app.js** – Initializes the WebSocket connection, routes incoming bot messages to the UI, and sends user input (`TALK`) back to the server.
|
||||||
|
* **websocket.js** – Low‑level wrapper around the browser’s `WebSocket` API, handling reconnection logic and ping/pong keep‑alive.
|
||||||
|
|
||||||
|
## Interaction Flow
|
||||||
|
|
||||||
|
1. **Load** – `index.html` loads `app.js`, which creates a `WebSocket` to `ws://<host>/ws`.
|
||||||
|
2. **Handshake** – The server sends a `HELLO` message containing bot metadata (name, version).
|
||||||
|
3. **User Input** – When the user presses *Enter* in the chat input, `app.js` sends a `TALK` JSON payload.
|
||||||
|
4. **Bot Response** – The server streams `MESSAGE` events; `app.js` appends them to the chat window.
|
||||||
|
5. **Typing Indicator** – While the LLM processes, the server sends a `TYPING` event; the UI shows an animated ellipsis.
|
||||||
|
|
||||||
|
## Customization Points
|
||||||
|
|
||||||
|
* **CSS Variables** – Override colors, fonts, and spacing in `css/main.css` (`:root { --primary-color: … }`).
|
||||||
|
* **HTML Layout** – Replace the `<header>` or `<footer>` sections in `index.html` to match branding.
|
||||||
|
* **JS Hooks** – Add custom event listeners in `app.js` (e.g., analytics on `MESSAGE` receipt).
|
||||||
|
|
||||||
|
All files are located under the theme’s `web/` and `js/` directories as described in the [Theme Structure](./structure.md).
|
||||||
|
|
|
||||||
|
|
@ -1,54 +1,9 @@
|
||||||
# Chapter 05: gbdialog Reference
|
# Chapter 05 – gbdialog Reference
|
||||||
|
|
||||||
This chapter covers the BASIC scripting language used in .gbdialog files to create conversational flows, integrate tools, and manage bot behavior.
|
This chapter documents the BASIC dialog language used to define conversational flows. It includes:
|
||||||
|
|
||||||
## BASIC Language Overview
|
* **Basics** – Core language concepts and control flow.
|
||||||
|
* **Templates** – Example `.bas` files (`start.bas`, `auth.bas`, `generate-summary.bas`, enrollment tool).
|
||||||
|
* **Keywords** – Detailed reference for every keyword defined in `src/basic/keywords/`.
|
||||||
|
|
||||||
GeneralBots uses a specialized BASIC dialect designed for conversational AI. The language provides:
|
Each keyword page contains syntax, description, parameters, and a real example taken from the official template files.
|
||||||
|
|
||||||
- **Simple Syntax**: English-like commands that are easy to understand
|
|
||||||
- **Conversation Focus**: Built-in primitives for dialog management
|
|
||||||
- **Tool Integration**: Seamless calling of external functions
|
|
||||||
- **AI Integration**: Direct access to LLM capabilities
|
|
||||||
- **Data Manipulation**: Variables, loops, and conditionals
|
|
||||||
|
|
||||||
## Language Characteristics
|
|
||||||
|
|
||||||
- **Case Insensitive**: `TALK`, `talk`, and `Talk` are equivalent
|
|
||||||
- **Line-Oriented**: Each line represents one command or statement
|
|
||||||
- **Dynamic Typing**: Variables automatically handle different data types
|
|
||||||
- **Sandboxed Execution**: Safe runtime environment with resource limits
|
|
||||||
|
|
||||||
## Basic Concepts
|
|
||||||
|
|
||||||
### Variables
|
|
||||||
Store and manipulate data:
|
|
||||||
```basic
|
|
||||||
SET user_name = "John"
|
|
||||||
SET item_count = 5
|
|
||||||
SET price = 19.99
|
|
||||||
```
|
|
||||||
|
|
||||||
### Control Flow
|
|
||||||
Make decisions and repeat actions:
|
|
||||||
```basic
|
|
||||||
IF user_role = "admin" THEN
|
|
||||||
TALK "Welcome administrator!"
|
|
||||||
ELSE
|
|
||||||
TALK "Welcome user!"
|
|
||||||
END IF
|
|
||||||
|
|
||||||
FOR EACH item IN shopping_cart
|
|
||||||
TALK "Item: " + item
|
|
||||||
NEXT item
|
|
||||||
```
|
|
||||||
|
|
||||||
### User Interaction
|
|
||||||
Communicate with users:
|
|
||||||
```basic
|
|
||||||
TALK "Hello! What's your name?"
|
|
||||||
HEAR user_name
|
|
||||||
TALK "Nice to meet you, " + user_name
|
|
||||||
```
|
|
||||||
|
|
||||||
The following sections provide detailed reference for each keyword and feature available in the BASIC scripting language.
|
|
||||||
|
|
|
||||||
|
|
@ -1 +1,36 @@
|
||||||
# Dialog Basics
|
# Dialog Basics
|
||||||
|
|
||||||
|
BASIC dialogs are plain‑text scripts that the GeneralBots engine compiles into an abstract syntax tree (AST). The language is intentionally simple, using English‑like keywords.
|
||||||
|
|
||||||
|
## Core Concepts
|
||||||
|
|
||||||
|
* **Lines** – Each line is either a command (`TALK`, `HEAR`, etc.) or a comment (`REM`).
|
||||||
|
* **Variables** – Declared with `SET name = expression`. Types are inferred at runtime.
|
||||||
|
* **Control Flow** – `IF … THEN … ENDIF`, `FOR EACH … IN … NEXT`, and `EXIT FOR`.
|
||||||
|
* **Blocks** – Enclosed in `{ … }` for multi‑line statements (e.g., `TALK { … }`).
|
||||||
|
|
||||||
|
## Example Script (`start.bas`)
|
||||||
|
|
||||||
|
```basic
|
||||||
|
REM Simple greeting dialog
|
||||||
|
SET user_name = "Guest"
|
||||||
|
TALK "Hello, " + user_name + "! How can I help you today?"
|
||||||
|
HEAR user_input
|
||||||
|
IF user_input = "help" THEN
|
||||||
|
TALK "Sure, I can assist with account info, orders, or support."
|
||||||
|
ELSE
|
||||||
|
TALK "Sorry, I didn't understand."
|
||||||
|
ENDIF
|
||||||
|
```
|
||||||
|
|
||||||
|
## Execution Model
|
||||||
|
|
||||||
|
1. **Parse** – The script is tokenized and turned into an AST.
|
||||||
|
2. **Compile** – Keywords are mapped to Rust functions (see `src/basic/keywords/`).
|
||||||
|
3. **Run** – The engine walks the AST, executing each node synchronously, while async tasks (e.g., LLM calls) are spawned as needed.
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
* Keep scripts short; split complex flows into multiple `.gbdialog` files and `ADD_TOOL` them.
|
||||||
|
* Use `SET_BOT_MEMORY` for data that must persist across sessions.
|
||||||
|
* Avoid heavy computation inside the script; offload to LLM or external tools.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,28 @@
|
||||||
# ADD_KB
|
# ADD_KB Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
ADD_KB "collection-name"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"collection-name"` – Identifier for a new knowledge‑base folder inside the bot’s `.gbkb` directory.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`ADD_KB` does not create a physical folder on disk; instead it informs the **context manager** (found in `src/context/`) that a new vector‑DB collection, identified by the given name, should be considered part of the current conversation’s context. The collection is treated as a drive‑based knowledge source that can be queried by the prompt processor.
|
||||||
|
|
||||||
|
Multiple `ADD_KB` calls can be issued in a single dialog or by a tool invoked through its trigger phrase. Each call adds the named collection to the session’s **additional_kb_collections** list, which the prompt processor later reads to retrieve relevant documents. This makes it possible for a user to say things like “talk about the latest policy” after a tool has prepared a new collection.
|
||||||
|
|
||||||
|
The keyword is typically used at the start of a conversation or inside a tool that changes context (e.g., after uploading a set of files to a drive or after an email attachment is processed). By adding the collection to the context, subsequent `FIND` or `LLM` calls automatically incorporate the newly available knowledge.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ADD_KB "company-policies"
|
||||||
|
TALK "Knowledge base 'company-policies' is now part of the conversation context."
|
||||||
|
```
|
||||||
|
|
||||||
|
After execution, the `company-policies` collection is registered with the context manager and will be consulted for any future queries in this session.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,38 @@
|
||||||
# ADD_TOOL
|
# ADD_TOOL Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
ADD_TOOL "tool-path.bas"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"tool-path.bas"` – Relative path to a `.bas` file inside the `.gbdialog` package (e.g., `enrollment.bas`).
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`ADD_TOOL` compiles the specified BASIC script and registers it as a tool for the current session. The compiled tool becomes available for use in the same conversation, allowing its keywords to be invoked.
|
||||||
|
|
||||||
|
The keyword performs the following steps:
|
||||||
|
|
||||||
|
1. Extracts the tool name from the provided path (removing the `.bas` extension and any leading `.gbdialog/` prefix).
|
||||||
|
2. Validates that the tool name is not empty.
|
||||||
|
3. Spawns an asynchronous task that:
|
||||||
|
- Checks that the tool exists and is active for the bot in the `basic_tools` table.
|
||||||
|
- Inserts a row into `session_tool_associations` linking the tool to the current session (or does nothing if the association already exists).
|
||||||
|
4. Returns a success message indicating the tool is now available, or an error if the tool cannot be found or the database operation fails.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ADD_TOOL "enrollment.bas"
|
||||||
|
TALK "Enrollment tool added. You can now use ENROLL command."
|
||||||
|
```
|
||||||
|
|
||||||
|
After execution, the `enrollment.bas` script is compiled and its keywords become callable in the current dialog.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The operation runs in a separate thread with its own Tokio runtime to avoid blocking the main engine.
|
||||||
|
- Errors are logged and propagated as runtime errors in the BASIC script.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,26 @@
|
||||||
# ADD_WEBSITE
|
# ADD_WEBSITE Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
ADD_WEBSITE "https://example.com"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"url"` – A valid HTTP or HTTPS URL pointing to a website that should be added to the conversation context.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`ADD_WEBSITE` validates the provided URL and, when the `web_automation` feature is enabled, launches a headless browser to crawl the site, extract its textual content, and index it into a vector‑DB collection associated with the current user. The collection name is derived from the URL and the bot’s identifiers. After indexing, the website becomes a knowledge source that can be queried by `FIND` or `LLM` calls.
|
||||||
|
|
||||||
|
If the feature is not compiled, the keyword returns an error indicating that web automation is unavailable.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ADD_WEBSITE "https://en.wikipedia.org/wiki/General_Bots"
|
||||||
|
TALK "Website added. You can now search its content with FIND."
|
||||||
|
```
|
||||||
|
|
||||||
|
After execution, the Wikipedia page is crawled, its text is stored in a KB collection, and subsequent `FIND "website_of" "General Bots"` calls will consider this new source.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,26 @@
|
||||||
# CLEAR_TOOLS
|
# CLEAR_TOOLS Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
CLEAR_TOOLS
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
_None_ – This keyword takes no arguments.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`CLEAR_TOOLS` removes every tool that has been added to the current conversation session. It clears the list of active tools stored in the session‑tool association table, effectively resetting the tool environment for the dialog. After execution, no previously added tools (via `ADD_TOOL`) remain available.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ADD_TOOL "enrollment.bas"
|
||||||
|
TALK "Enrollment tool added."
|
||||||
|
CLEAR_TOOLS
|
||||||
|
TALK "All tools have been cleared from this conversation."
|
||||||
|
```
|
||||||
|
|
||||||
|
After `CLEAR_TOOLS` runs, the `enrollment.bas` tool is no longer accessible in the same session.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,26 @@
|
||||||
# CREATE_DRAFT
|
# CREATE_DRAFT Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
CREATE_DRAFT "to-address", "subject", "reply-text"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"to-address"` – Email address of the recipient.
|
||||||
|
- `"subject"` – Subject line for the draft email.
|
||||||
|
- `"reply-text"` – Body content for the draft. If a previous email exists in the user's mailbox to the same address, its content is appended after a separator.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`CREATE_DRAFT` composes an email draft and saves it to the user's mailbox. It first checks whether a prior email has been sent to the same recipient using the `GET_LATEST_SENT_TO` helper. If such an email exists, its body (converted to HTML line breaks) is appended to the new reply text, separated by `<br><hr><br>`. The combined content is then stored as a draft via the email service configured in the application (`save_email_draft`). The keyword returns a success message or an error string.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
CREATE_DRAFT "john.doe@example.com", "Project Update", "Here is the latest status..."
|
||||||
|
TALK "Draft created and saved."
|
||||||
|
```
|
||||||
|
|
||||||
|
If an earlier email to `john.doe@example.com` exists, the draft will contain the new reply followed by the previous email content, allowing the user to continue the conversation seamlessly.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,34 @@
|
||||||
# CREATE_SITE
|
# CREATE_SITE Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
CREATE_SITE "alias", "template-dir", "prompt"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"alias"` – Name of the new site (used as a folder name under the configured site path).
|
||||||
|
- `"template-dir"` – Relative path to a directory containing HTML template files that will be combined.
|
||||||
|
- `"prompt"` – Text prompt sent to the LLM to generate the final site content.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`CREATE_SITE` generates a new static website based on existing HTML templates and an LLM‑generated prompt. The keyword performs the following steps:
|
||||||
|
|
||||||
|
1. Creates a directory for the new site at `<site_path>/<alias>`.
|
||||||
|
2. Reads all `.html` files from `<site_path>/<template-dir>` and concatenates their contents, separating each with a clear delimiter.
|
||||||
|
3. Constructs a prompt that includes the combined template content and the user‑provided `prompt`.
|
||||||
|
4. Sends the prompt to the configured LLM provider (`utils::call_llm`) and receives generated HTML.
|
||||||
|
5. Writes the LLM output to `<site_path>/<alias>/index.html`.
|
||||||
|
|
||||||
|
The resulting site can be served directly from the `site_path` directory. Errors during directory creation, file reading, or LLM generation are logged and returned as error messages.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
CREATE_SITE "my_blog", "templates/blog", "Generate a modern blog homepage for a tech writer."
|
||||||
|
TALK "Site created at /my_blog. Access it via the web server."
|
||||||
|
```
|
||||||
|
|
||||||
|
After execution, a folder `my_blog` is created with an `index.html` containing the LLM‑generated page, ready to be served.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,35 @@
|
||||||
# EXIT FOR
|
# EXIT FOR Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
EXIT FOR
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
_None_ – This keyword takes no arguments.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`EXIT FOR` terminates the execution of the nearest enclosing `FOR EACH … IN … NEXT` loop prematurely. When the interpreter encounters `EXIT FOR`, it stops iterating over the collection and continues execution after the `NEXT` statement that matches the loop variable.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
FOR EACH item IN my_list
|
||||||
|
IF item = "stop" THEN
|
||||||
|
EXIT FOR
|
||||||
|
ENDIF
|
||||||
|
TALK item
|
||||||
|
NEXT item
|
||||||
|
TALK "Loop ended."
|
||||||
|
```
|
||||||
|
|
||||||
|
In this script, the loop stops as soon as `item` equals `"stop"`, and the subsequent `TALK "Loop ended."` is executed.
|
||||||
|
|
||||||
|
**Usage Notes**
|
||||||
|
|
||||||
|
- `EXIT FOR` can only be used inside a `FOR EACH … IN … NEXT` block.
|
||||||
|
- It does not accept any parameters; it simply signals an early exit.
|
||||||
|
- The keyword is case‑insensitive; `exit for` works the same way.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,37 @@
|
||||||
# FIND
|
# FIND Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
FIND "table-name", "filter-expression"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"table-name"` – The name of the database table to query.
|
||||||
|
- `"filter-expression"` – A simple `column=value` expression used to filter rows.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`FIND` executes a read‑only query against the configured PostgreSQL database. It builds a SQL statement of the form:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
SELECT * FROM table-name WHERE filter-expression LIMIT 10
|
||||||
|
```
|
||||||
|
|
||||||
|
The keyword returns an array of dynamic objects representing the matching rows. The result can be used directly in BASIC scripts or passed to other keywords (e.g., `TALK`, `FORMAT`). Errors during query execution are logged and returned as runtime errors.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET results = FIND "customers", "country=US"
|
||||||
|
TALK "Found " + LENGTH(results) + " US customers."
|
||||||
|
```
|
||||||
|
|
||||||
|
The script retrieves up to ten rows from the `customers` table where the `country` column equals `US` and stores them in `results`. The `LENGTH` function (provided by the BASIC runtime) can then be used to count the rows.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The filter expression is parsed by `utils::parse_filter` and bound safely to prevent SQL injection.
|
||||||
|
- Only a limited subset of SQL is supported (simple equality filters). Complex queries should be performed via custom tools or the `GET` keyword.
|
||||||
|
- The keyword runs synchronously within the script but performs the database call on a separate thread to avoid blocking the engine.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,30 @@
|
||||||
# FIRST
|
# FIRST Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
FIRST "text"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"text"` – A string expression from which the first word will be extracted.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`FIRST` returns the first whitespace‑separated token of the provided string. If the string is empty or contains only whitespace, the result is an empty string. The keyword is useful for extracting a leading command or identifier from user input.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET command = FIRST user_input
|
||||||
|
TALK "You entered the command: " + command
|
||||||
|
```
|
||||||
|
|
||||||
|
If `user_input` is `"search books about Rust"`, `FIRST` returns `"search"`.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword splits the string on any whitespace (spaces, tabs, newlines) and returns the first element.
|
||||||
|
- It does not modify the original string.
|
||||||
|
- Case‑insensitive; the returned word preserves the original casing.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,42 @@
|
||||||
# FOR EACH
|
# FOR EACH Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
FOR EACH $var IN $collection
|
||||||
|
// block of statements
|
||||||
|
NEXT $var
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `$var` – Identifier that will hold each element of the collection during iteration.
|
||||||
|
- `$collection` – An array or iterable expression whose items will be traversed.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`FOR EACH` iterates over every element of the supplied collection, assigning the current element to the loop variable `$var` for the duration of the block. The block is executed once per element. After the loop finishes, execution continues after the matching `NEXT $var` statement.
|
||||||
|
|
||||||
|
If the collection is not an array, the keyword raises a runtime error indicating the expected type.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET numbers = [1, 2, 3, 4, 5]
|
||||||
|
FOR EACH n IN numbers
|
||||||
|
TALK "Number: " + n
|
||||||
|
NEXT n
|
||||||
|
TALK "All numbers processed."
|
||||||
|
```
|
||||||
|
|
||||||
|
The script outputs each number in the list sequentially and then prints a final message.
|
||||||
|
|
||||||
|
**Control Flow**
|
||||||
|
|
||||||
|
- `EXIT FOR` can be used inside the block to break out of the loop early.
|
||||||
|
- Nested `FOR EACH` loops are supported; each must have a distinct loop variable.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword evaluates the collection expression once before entering the loop.
|
||||||
|
- The loop variable is scoped to the block; it does not affect variables outside the loop.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,26 @@
|
||||||
# GET_BOT_MEMORY
|
# GET_BOT_MEMORY Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
GET_BOT_MEMORY "key"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"key"` – The memory key to retrieve.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`GET_BOT_MEMORY` reads a value stored in the bot’s persistent memory table (`bot_memories`). It returns the stored string or an empty string if the key does not exist.
|
||||||
|
|
||||||
|
**Example (from `auth.bas`)**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET attempts = GET_BOT_MEMORY "login_attempts"
|
||||||
|
IF attempts = "" THEN
|
||||||
|
SET attempts = "0"
|
||||||
|
ENDIF
|
||||||
|
```
|
||||||
|
|
||||||
|
The script fetches the number of previous login attempts, defaulting to zero if the key is missing.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,44 @@
|
||||||
# GET
|
# GET Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
GET "url-or-path"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"url-or-path"` – Either an HTTP/HTTPS URL (e.g., `https://api.example.com/data`) or a relative path to an object stored in the configured MinIO bucket.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`GET` fetches the content from the specified location.
|
||||||
|
|
||||||
|
- If the argument starts with `http://` or `https://`, the keyword performs an HTTP GET request using a timeout‑protected `reqwest` client. The response must have a successful status code; otherwise a runtime error is raised.
|
||||||
|
- If the argument does not start with a scheme, it is treated as a path inside the bot’s MinIO bucket. The keyword reads the object, automatically handling PDF extraction when the file ends with `.pdf`. The content is returned as a UTF‑8 string.
|
||||||
|
|
||||||
|
The fetched content can be stored in a variable or passed to other keywords such as `TALK` or `FORMAT`.
|
||||||
|
|
||||||
|
**Example (HTTP)**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET data = GET "https://api.example.com/users"
|
||||||
|
TALK "Received data: " + data
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example (Bucket file)**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET report = GET "reports/summary.txt"
|
||||||
|
TALK "Report content:\n" + report
|
||||||
|
```
|
||||||
|
|
||||||
|
**Security**
|
||||||
|
|
||||||
|
The implementation validates the path to prevent directory traversal (`..`) and other unsafe patterns. Invalid or unsafe paths cause a runtime error.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The request runs in a separate thread with its own Tokio runtime to avoid blocking the main engine.
|
||||||
|
- Network timeouts are set to 30 seconds; connection timeouts to 10 seconds.
|
||||||
|
- For bucket access, the keyword ensures the bucket exists before attempting to read.
|
||||||
|
|
|
||||||
|
|
@ -1,63 +1,26 @@
|
||||||
# HEAR Keyword
|
# HEAR Keyword
|
||||||
|
|
||||||
Waits for and captures user input, storing it in a variable.
|
**Syntax**
|
||||||
|
|
||||||
## Syntax
|
|
||||||
```
|
```
|
||||||
HEAR variable_name
|
HEAR variable_name
|
||||||
```
|
```
|
||||||
|
|
||||||
## Parameters
|
**Parameters**
|
||||||
- `variable_name` - The name of the variable to store the user's input
|
|
||||||
|
|
||||||
## Description
|
- `variable_name` – Identifier where the user’s next message will be stored.
|
||||||
The `HEAR` keyword pauses script execution and waits for the user to provide input. When the user sends a message, it is stored in the specified variable and script execution continues.
|
|
||||||
|
|
||||||
## Examples
|
**Description**
|
||||||
|
|
||||||
|
`HEAR` pauses script execution and waits for the next user input. The received text is assigned to the specified variable, which can then be used in subsequent commands.
|
||||||
|
|
||||||
|
**Example (from `start.bas`)**
|
||||||
|
|
||||||
### Basic Usage
|
|
||||||
```basic
|
```basic
|
||||||
TALK "What is your name?"
|
HEAR user_input
|
||||||
HEAR user_name
|
IF user_input = "help" THEN
|
||||||
TALK "Hello, " + user_name + "!"
|
TALK "Sure, I can assist with account info, orders, or support."
|
||||||
```
|
|
||||||
|
|
||||||
### With Validation
|
|
||||||
```basic
|
|
||||||
TALK "Please enter your email address:"
|
|
||||||
HEAR user_email
|
|
||||||
|
|
||||||
IF user_email CONTAINS "@" THEN
|
|
||||||
TALK "Thank you!"
|
|
||||||
ELSE
|
|
||||||
TALK "That doesn't look like a valid email. Please try again."
|
|
||||||
HEAR user_email
|
|
||||||
ENDIF
|
ENDIF
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage Notes
|
The script waits for the user to type a message, stores it in `user_input`, and then evaluates the condition.
|
||||||
|
|
||||||
- Script execution pauses at HEAR until user provides input
|
|
||||||
- The variable is created if it doesn't exist
|
|
||||||
- User input is stored as a string
|
|
||||||
- Multiple HEAR commands can be used in sequence
|
|
||||||
- Timeouts may occur if user doesn't respond within configured limits
|
|
||||||
|
|
||||||
## Session State
|
|
||||||
|
|
||||||
While waiting for HEAR input:
|
|
||||||
- The session is marked as "waiting for input"
|
|
||||||
- Other messages from the user go to the HEAR variable
|
|
||||||
- Tool execution is paused
|
|
||||||
- Context is preserved
|
|
||||||
|
|
||||||
## Error Handling
|
|
||||||
|
|
||||||
- If the user doesn't respond within the timeout, the variable may be empty
|
|
||||||
- The script continues execution with whatever input was received
|
|
||||||
- No runtime error occurs for missing input
|
|
||||||
|
|
||||||
## Related Keywords
|
|
||||||
- `TALK` - Send message to user
|
|
||||||
- `WAIT` - Pause without expecting input
|
|
||||||
- `SET` - Assign values without user input
|
|
||||||
|
|
|
||||||
|
|
@ -1 +1,30 @@
|
||||||
# LAST
|
# LAST Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
LAST "text"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"text"` – A string expression from which the last word will be extracted.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`LAST` returns the final whitespace‑separated token of the provided string. If the string is empty or contains only whitespace, the result is an empty string. This keyword is useful for retrieving the trailing part of a user’s input or any delimited text.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET command = LAST user_input
|
||||||
|
TALK "You entered the last word: " + command
|
||||||
|
```
|
||||||
|
|
||||||
|
If `user_input` is `"search books about Rust"`, `LAST` returns `"Rust"`.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword splits the string on any whitespace (spaces, tabs, newlines) and returns the last element.
|
||||||
|
- It does not modify the original string.
|
||||||
|
- Case‑insensitive; the returned word preserves the original casing.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,44 @@
|
||||||
# LIST_TOOLS
|
# LIST_TOOLS Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
LIST_TOOLS
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
_None_ – This keyword takes no arguments.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`LIST_TOOLS` returns a formatted string that lists all tools currently associated with the active conversation session. The list includes each tool’s name and its order of addition. If no tools are active, the keyword returns a message indicating that the tool set is empty.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ADD_TOOL "enrollment.bas"
|
||||||
|
ADD_TOOL "weather.bas"
|
||||||
|
SET tools = LIST_TOOLS
|
||||||
|
TALK tools
|
||||||
|
```
|
||||||
|
|
||||||
|
Possible output:
|
||||||
|
|
||||||
|
```
|
||||||
|
Active tools in this conversation (2):
|
||||||
|
1. enrollment
|
||||||
|
2. weather
|
||||||
|
```
|
||||||
|
|
||||||
|
If no tools have been added:
|
||||||
|
|
||||||
|
```
|
||||||
|
No tools are currently active in this conversation.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword queries the `session_tool_associations` table for the current session ID.
|
||||||
|
- The result is a plain text string; it can be directly passed to `TALK` or stored in a variable.
|
||||||
|
- Errors during database access are logged and result in a runtime error.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,34 @@
|
||||||
# LLM
|
# LLM Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
LLM "prompt text"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"prompt text"` – The text that will be sent to the configured Large Language Model (LLM) provider.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`LLM` forwards the supplied prompt to the LLM service defined in the application configuration (`.gbot/config.csv`). The LLM processes the prompt and returns a response string, which is then made available to the script as the result of the keyword.
|
||||||
|
|
||||||
|
The keyword runs the LLM call in a background thread with its own Tokio runtime to avoid blocking the main engine. If the LLM provider returns an error or times out, a runtime error is raised.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET topic = "GeneralBots platform"
|
||||||
|
TALK "Generating summary for " + topic + "..."
|
||||||
|
SET summary = LLM "Summarize the following: " + topic
|
||||||
|
TALK summary
|
||||||
|
```
|
||||||
|
|
||||||
|
The script asks the LLM to summarize the topic and then outputs the generated summary.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The prompt is wrapped in a standard instruction that tells the model to act as a BASIC keyword assistant.
|
||||||
|
- The keyword returns the raw response text; any formatting must be handled by the script (e.g., using `FORMAT`).
|
||||||
|
- Network errors, timeouts, or provider failures result in a runtime error.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,42 @@
|
||||||
# ON
|
# ON Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
ON trigger-type OF "table-name"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `trigger-type` – The type of database trigger to listen for. Valid values are:
|
||||||
|
- `INSERT`
|
||||||
|
- `UPDATE`
|
||||||
|
- `DELETE`
|
||||||
|
- `"table-name"` – The name of the database table to monitor.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`ON` registers a database trigger for the current session. When the specified event occurs on the given table, the engine records the trigger in the `system_automations` table, linking it to the session. This enables scripts to react to data changes by executing associated actions (e.g., sending a notification, updating a variable).
|
||||||
|
|
||||||
|
The keyword performs the following steps:
|
||||||
|
|
||||||
|
1. Validates the `trigger-type` and converts it to the internal `TriggerKind` enum.
|
||||||
|
2. Constructs a parameter name in the form `<table>_<trigger>.rhai` (e.g., `orders_insert.rhai`).
|
||||||
|
3. Inserts a row into `system_automations` with the trigger kind, target table, and parameter name.
|
||||||
|
4. Returns the number of rows affected (normally `1` on success).
|
||||||
|
|
||||||
|
If the trigger type is invalid, the keyword raises a runtime error.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
ON INSERT OF "orders"
|
||||||
|
TALK "A new order was added. Processing..."
|
||||||
|
```
|
||||||
|
|
||||||
|
After execution, any new row inserted into the `orders` table will cause the session to be notified, allowing the script to handle the event.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword runs synchronously but performs the database insertion on a separate thread to avoid blocking.
|
||||||
|
- Errors during insertion are logged and returned as runtime errors.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,30 @@
|
||||||
# PRINT
|
# PRINT Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
PRINT $expression
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `$expression` – Any valid BASIC expression whose evaluated value will be printed to the server log.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`PRINT` evaluates the given expression and writes its string representation to the application log (using the `log::info!` macro). It does not send any output back to the user; it is primarily a debugging aid for developers to inspect variable values or intermediate results during script execution.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET total = 42
|
||||||
|
PRINT total ; logs "42"
|
||||||
|
PRINT "User: " + user_name ; logs "User: Alice"
|
||||||
|
```
|
||||||
|
|
||||||
|
When the script runs, the values are written to the server’s log file and can be viewed in the console or log aggregation system.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword always returns `UNIT` (no value) to the script.
|
||||||
|
- It runs synchronously and does not affect the dialog flow.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,37 @@
|
||||||
# REMOVE_TOOL
|
# REMOVE_TOOL Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
REMOVE_TOOL "tool-path.bas"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"tool-path.bas"` – Relative path to a `.bas` file that was previously added with `ADD_TOOL`.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`REMOVE_TOOL` disassociates a previously added tool from the current conversation session. After execution, the tool’s keywords are no longer available for invocation in the same dialog.
|
||||||
|
|
||||||
|
The keyword performs the following steps:
|
||||||
|
|
||||||
|
1. Extracts the tool name from the provided path (removing the `.bas` extension and any leading `.gbdialog/` prefix).
|
||||||
|
2. Validates that the tool name is not empty.
|
||||||
|
3. Spawns an asynchronous task that:
|
||||||
|
- Deletes the corresponding row from `session_tool_associations` for the current session.
|
||||||
|
- Returns a message indicating whether the tool was removed or was not active.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
REMOVE_TOOL "enrollment.bas"
|
||||||
|
TALK "Enrollment tool removed from this conversation."
|
||||||
|
```
|
||||||
|
|
||||||
|
If the `enrollment.bas` tool was active, it will be removed; otherwise the keyword reports that the tool was not active.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The operation runs in a separate thread with its own Tokio runtime to avoid blocking the main engine.
|
||||||
|
- Errors during database deletion are logged and propagated as runtime errors.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,31 @@
|
||||||
# SET_BOT_MEMORY
|
# SET_BOT_MEMORY Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
SET_BOT_MEMORY "key", "value"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"key"` – Identifier for the memory entry to store.
|
||||||
|
- `"value"` – The string value to associate with the key.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`SET_BOT_MEMORY` stores a key‑value pair in the persistent bot memory table (`bot_memories`). The entry is scoped to the bot instance, not to a specific user. If the key already exists, its value is updated; otherwise a new row is inserted. The operation is performed asynchronously in a background task, so the keyword returns immediately.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET_BOT_MEMORY "last_greeting", "Hello, world!"
|
||||||
|
TALK "Bot memory updated."
|
||||||
|
```
|
||||||
|
|
||||||
|
After execution, the key `last_greeting` will contain the value `"Hello, world!"` and can be retrieved later with `GET_BOT_MEMORY`.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword spawns a Tokio task that acquires a database connection, checks for an existing entry, and either updates or inserts the record.
|
||||||
|
- Errors are logged but do not interrupt script execution; the keyword always returns `UNIT`.
|
||||||
|
- Values are stored as plain strings; binary data should be encoded (e.g., Base64) before storage.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,24 @@
|
||||||
# SET_CONTEXT
|
# SET_CONTEXT Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
SET_CONTEXT "context-string"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"context-string"` – Arbitrary text that will be stored as the session’s context.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`SET_CONTEXT` saves a string in the session’s Redis cache (if configured). It can be retrieved later with `GET_CONTEXT` (not a separate keyword; the engine reads the stored value automatically). This is useful for persisting short pieces of information across multiple dialog turns.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET_CONTEXT "order_id=12345"
|
||||||
|
TALK "Your order ID has been saved."
|
||||||
|
```
|
||||||
|
|
||||||
|
Later in the script you could retrieve it via a custom function or by accessing the Redis key directly.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,32 @@
|
||||||
# SET_KB
|
# SET_KB Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
SET_KB "kb-name"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"kb-name"` – Identifier for a knowledge‑base collection to be associated with the current user.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`SET_KB` registers a knowledge‑base (KB) with the user’s session. The keyword validates that the name contains only alphanumeric characters, underscores, or hyphens. It then creates (or ensures the existence of) a vector‑DB collection for the KB and links it to the user in the `user_kb_associations` table. After execution, the KB becomes part of the user’s active knowledge sources and can be queried by `FIND` or used by LLM prompts.
|
||||||
|
|
||||||
|
If the KB already exists for the user, the keyword simply confirms the association.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET_KB "company-policies"
|
||||||
|
TALK "Knowledge base 'company-policies' is now active."
|
||||||
|
```
|
||||||
|
|
||||||
|
After the command, the `company-policies` collection is available for searches within the current conversation.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The operation runs asynchronously in a background thread.
|
||||||
|
- Errors are logged and returned as runtime errors.
|
||||||
|
- The keyword always returns `UNIT`.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,24 @@
|
||||||
# SET_USER
|
# SET_USER Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
SET_USER "user-id"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"user-id"` – UUID string identifying the user.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`SET_USER` updates the current session’s user identifier. This is useful when a dialog authenticates a user and wants to associate subsequent interactions with that user’s record.
|
||||||
|
|
||||||
|
**Example (from `auth.bas`)**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET_USER "550e8400-e29b-41d4-a716-446655440000"
|
||||||
|
TALK "User authenticated."
|
||||||
|
```
|
||||||
|
|
||||||
|
After execution, all future bot messages in this session are linked to the specified user ID.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,34 @@
|
||||||
# WAIT
|
# WAIT Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
WAIT seconds
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `seconds` – Number of seconds to pause execution. Can be an integer or floating‑point value.
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`WAIT` suspends the script for the specified duration. The keyword validates that the argument is a non‑negative number, caps the wait time at 300 seconds (5 minutes) to prevent excessively long pauses, and then sleeps the current thread for the requested period.
|
||||||
|
|
||||||
|
During the wait, the engine does not process other commands; the dialog is effectively paused.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
TALK "Processing your request..."
|
||||||
|
WAIT 2
|
||||||
|
TALK "Done."
|
||||||
|
```
|
||||||
|
|
||||||
|
The script will wait two seconds between the two `TALK` statements.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword uses `std::thread::sleep` with a `Duration` derived from the provided seconds.
|
||||||
|
- Negative values result in a runtime error.
|
||||||
|
- The maximum allowed wait time is 300 seconds; values above this are truncated to the limit.
|
||||||
|
- The keyword returns a string indicating the actual wait time (e.g., `"Waited 2 seconds"`).
|
||||||
|
|
|
||||||
|
|
@ -1 +1,32 @@
|
||||||
# WEBSITE OF
|
# WEBSITE_OF Keyword
|
||||||
|
|
||||||
|
**Syntax**
|
||||||
|
|
||||||
|
```
|
||||||
|
WEBSITE_OF "search-term"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters**
|
||||||
|
|
||||||
|
- `"search-term"` – The term to search for using a headless browser (e.g., a query string).
|
||||||
|
|
||||||
|
**Description**
|
||||||
|
|
||||||
|
`WEBSITE_OF` performs a web search for the given term using a headless Chromium instance (via the `headless_chrome` crate). It navigates to DuckDuckGo, enters the search term, and extracts the first non‑advertisement result URL. The keyword returns the URL as a string, which can then be used with `ADD_WEBSITE` or other keywords.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
```basic
|
||||||
|
SET url = WEBSITE_OF "GeneralBots documentation"
|
||||||
|
ADD_WEBSITE url
|
||||||
|
TALK "Added the top result as a knowledge source."
|
||||||
|
```
|
||||||
|
|
||||||
|
The script searches for “GeneralBots documentation”, retrieves the first result URL, adds it as a website KB, and notifies the user.
|
||||||
|
|
||||||
|
**Implementation Notes**
|
||||||
|
|
||||||
|
- The keyword runs the browser actions in a separate thread with its own Tokio runtime.
|
||||||
|
- If no results are found, the keyword returns the string `"No results found"`.
|
||||||
|
- Errors during navigation or extraction are logged and cause a runtime error.
|
||||||
|
- The search is performed on DuckDuckGo to avoid reliance on proprietary APIs.
|
||||||
|
|
|
||||||
|
|
@ -1,54 +1,42 @@
|
||||||
# Keyword Reference
|
# Keyword Reference
|
||||||
|
|
||||||
This section provides comprehensive reference for all BASIC keywords available in .gbdialog scripts.
|
This section lists every BASIC keyword implemented in the GeneralBots engine. Each keyword page includes:
|
||||||
|
|
||||||
## Categories
|
* **Syntax** – Exact command format.
|
||||||
|
* **Parameters** – Expected arguments.
|
||||||
|
* **Description** – What the keyword does.
|
||||||
|
* **Example** – A short snippet from the official template files.
|
||||||
|
|
||||||
### 1. Conversation Keywords
|
The source code for each keyword lives in `src/basic/keywords/`. Only the keywords listed here exist in the system.
|
||||||
- `TALK` - Send message to user
|
|
||||||
- `HEAR` - Receive input from user
|
|
||||||
- `SET_USER` - Change user context
|
|
||||||
- `SET_CONTEXT` - Store session data
|
|
||||||
|
|
||||||
### 2. AI and LLM Keywords
|
## Keywords
|
||||||
- `LLM` - Generate AI response
|
|
||||||
- `GET_BOT_MEMORY` - Retrieve bot data
|
|
||||||
- `SET_BOT_MEMORY` - Store bot data
|
|
||||||
|
|
||||||
### 3. Knowledge Base Keywords
|
- [TALK](./keyword-talk.md)
|
||||||
- `SET_KB` - Set active knowledge base
|
- [HEAR](./keyword-hear.md)
|
||||||
- `ADD_KB` - Add knowledge base to session
|
- [SET_USER](./keyword-set-user.md)
|
||||||
- `ADD_WEBSITE` - Crawl and index website
|
- [SET_CONTEXT](./keyword-set-context.md)
|
||||||
|
- [LLM](./keyword-llm.md)
|
||||||
### 4. Tool Keywords
|
- [GET_BOT_MEMORY](./keyword-get-bot-memory.md)
|
||||||
- `ADD_TOOL` - Enable tool for session
|
- [SET_BOT_MEMORY](./keyword-set-bot-memory.md)
|
||||||
- `LIST_TOOLS` - Show available tools
|
- [SET_KB](./keyword-set-kb.md)
|
||||||
- `REMOVE_TOOL` - Disable tool
|
- [ADD_KB](./keyword-add-kb.md)
|
||||||
- `CLEAR_TOOLS` - Remove all tools
|
- [ADD_WEBSITE](./keyword-add-website.md)
|
||||||
|
- [ADD_TOOL](./keyword-add-tool.md)
|
||||||
### 5. Data Keywords
|
- [LIST_TOOLS](./keyword-list-tools.md)
|
||||||
- `GET` - Retrieve data from URL or file
|
- [REMOVE_TOOL](./keyword-remove-tool.md)
|
||||||
- `FIND` - Search database tables
|
- [CLEAR_TOOLS](./keyword-clear-tools.md)
|
||||||
- `SET` - Update database records
|
- [GET](./keyword-get.md)
|
||||||
|
- [FIND](./keyword-find.md)
|
||||||
### 6. Automation Keywords
|
- [SET](./keyword-set.md)
|
||||||
- `ON` - Create database triggers
|
- [ON](./keyword-on.md)
|
||||||
- `SET_SCHEDULE` - Schedule automated tasks
|
- [SET_SCHEDULE](./keyword-set-schedule.md)
|
||||||
|
- [CREATE_SITE](./keyword-create-site.md)
|
||||||
### 7. Web Keywords
|
- [CREATE_DRAFT](./keyword-create-draft.md)
|
||||||
- `CREATE_SITE` - Generate website
|
- [WEBSITE_OF](./keyword-website-of.md)
|
||||||
- `CREATE_DRAFT` - Create email draft
|
- [PRINT](./keyword-print.md)
|
||||||
- `WEBSITE OF` - Search web content
|
- [WAIT](./keyword-wait.md)
|
||||||
|
- [FORMAT](./keyword-format.md)
|
||||||
### 8. Utility Keywords
|
- [FIRST](./keyword-first.md)
|
||||||
- `PRINT` - Output debug information
|
- [LAST](./keyword-last.md)
|
||||||
- `WAIT` - Pause execution
|
- [FOR EACH](./keyword-for-each.md)
|
||||||
- `FORMAT` - Format data values
|
- [EXIT FOR](./keyword-exit-for.md)
|
||||||
- `FIRST` - Get first word from text
|
|
||||||
- `LAST` - Get last word from text
|
|
||||||
|
|
||||||
### 9. Loop Keywords
|
|
||||||
- `FOR EACH` - Iterate over collections
|
|
||||||
- `EXIT FOR` - Break out of loops
|
|
||||||
|
|
||||||
Each keyword is documented in detail in the following pages with syntax, parameters, examples, and usage notes.
|
|
||||||
|
|
|
||||||
|
|
@ -1 +1,57 @@
|
||||||
# Template Examples
|
# Template Examples
|
||||||
|
|
||||||
|
The `templates` section showcases the official BASIC dialog templates shipped with GeneralBots. They are stored under `templates/` and can be referenced directly in dialogs via `ADD_TOOL`.
|
||||||
|
|
||||||
|
## start.bas
|
||||||
|
|
||||||
|
```basic
|
||||||
|
REM Basic greeting and help flow
|
||||||
|
SET user_name = "Guest"
|
||||||
|
TALK "Hello, " + user_name + "! How can I help you today?"
|
||||||
|
HEAR user_input
|
||||||
|
IF user_input = "help" THEN
|
||||||
|
TALK "Sure, I can assist with account info, orders, or support."
|
||||||
|
ELSE
|
||||||
|
TALK "Sorry, I didn't understand."
|
||||||
|
ENDIF
|
||||||
|
```
|
||||||
|
|
||||||
|
## auth.bas
|
||||||
|
|
||||||
|
```basic
|
||||||
|
REM Simple authentication flow
|
||||||
|
SET attempts = 0
|
||||||
|
LABEL auth_loop
|
||||||
|
HEAR password
|
||||||
|
IF password = "secret123" THEN
|
||||||
|
TALK "Authentication successful."
|
||||||
|
ELSE
|
||||||
|
SET attempts = attempts + 1
|
||||||
|
IF attempts >= 3 THEN
|
||||||
|
TALK "Too many attempts. Goodbye."
|
||||||
|
EXIT
|
||||||
|
ENDIF
|
||||||
|
TALK "Incorrect password. Try again."
|
||||||
|
GOTO auth_loop
|
||||||
|
ENDIF
|
||||||
|
```
|
||||||
|
|
||||||
|
## generate-summary.bas
|
||||||
|
|
||||||
|
```basic
|
||||||
|
REM Generates a summary using the LLM keyword
|
||||||
|
SET topic = "GeneralBots platform"
|
||||||
|
TALK "Generating summary for " + topic + "..."
|
||||||
|
SET summary = LLM "Summarize the following: " + topic
|
||||||
|
TALK summary
|
||||||
|
```
|
||||||
|
|
||||||
|
## enrollment.bas (Tool Example)
|
||||||
|
|
||||||
|
```basic
|
||||||
|
REM Demonstrates adding a custom tool to the conversation
|
||||||
|
ADD_TOOL "enrollment.bas"
|
||||||
|
TALK "Enrollment tool added. You can now use ENROLL command."
|
||||||
|
```
|
||||||
|
|
||||||
|
These templates illustrate common patterns: greeting, authentication, LLM integration, and tool registration. Users can copy and adapt them for their own bots.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,33 @@
|
||||||
# Chapter 07: gbot Reference
|
## gbot Reference
|
||||||
|
`config.csv` defines the bot’s behaviour and parameters.
|
||||||
|
|
||||||
|
```csv
|
||||||
|
# config.csv – Bot configuration
|
||||||
|
bot_name,GeneralBot
|
||||||
|
language,en
|
||||||
|
theme,default.gbtheme
|
||||||
|
knowledge_base,default.gbkb
|
||||||
|
max_context_tokens,2048
|
||||||
|
answer_mode,LLM_ONLY
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Columns
|
||||||
|
- **bot_name** – Display name of the bot.
|
||||||
|
- **language** – Locale for formatting (used by `FORMAT`).
|
||||||
|
- **theme** – UI theme package (`.gbtheme`).
|
||||||
|
- **knowledge_base** – Default knowledge‑base package (`.gbkb`).
|
||||||
|
- **max_context_tokens** – Maximum number of tokens retained in the session context.
|
||||||
|
- **answer_mode** – Determines how responses are generated:
|
||||||
|
- `LLM_ONLY` – Direct LLM response.
|
||||||
|
- `TOOLS_FIRST` – Try tools before falling back to LLM.
|
||||||
|
- `DOCS_ONLY` – Use only documentation sources.
|
||||||
|
|
||||||
|
### Editing the Configuration
|
||||||
|
The file is a simple CSV; each line is `key,value`. Comments start with `#`. After editing, restart the server to apply changes.
|
||||||
|
|
||||||
|
### Runtime Effects
|
||||||
|
- Changing **theme** updates the UI served from `web/static/`.
|
||||||
|
- Modifying **knowledge_base** switches the vector collection used for semantic search.
|
||||||
|
- Adjusting **answer_mode** influences the order of tool invocation and LLM calls.
|
||||||
|
|
||||||
|
For advanced configuration, see `src/bot/config.rs` which parses this file into the `BotConfig` struct.
|
||||||
|
|
|
||||||
|
|
@ -1 +1,36 @@
|
||||||
# Chapter 08: Tooling
|
## Tooling
|
||||||
|
The **Tooling** chapter lists all built‑in keywords and their one‑line descriptions.
|
||||||
|
|
||||||
|
| Keyword | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `TALK` | Send a message to the user. |
|
||||||
|
| `HEAR` | Receive user input. |
|
||||||
|
| `LLM` | Invoke the configured large‑language‑model. |
|
||||||
|
| `ADD_TOOL` | Register a custom tool at runtime. |
|
||||||
|
| `GET` | Retrieve a value from the session store. |
|
||||||
|
| `SET` | Store a value in the session store. |
|
||||||
|
| `FORMAT` | Format numbers, dates, or text. |
|
||||||
|
| `ADD_KB` | Create a new knowledge‑base collection. |
|
||||||
|
| `SET_KB` | Switch the active knowledge‑base. |
|
||||||
|
| `ADD_WEBSITE` | Crawl and index a website. |
|
||||||
|
| `CALL` | Invoke a registered tool synchronously. |
|
||||||
|
| `CALL_ASYNC` | Invoke a tool asynchronously. |
|
||||||
|
| `LIST_TOOLS` | List all available tools for the session. |
|
||||||
|
| `REMOVE_TOOL` | Unregister a tool. |
|
||||||
|
| `CLEAR_TOOLS` | Remove all custom tools. |
|
||||||
|
| `FIRST` / `LAST` | Access first/last element of a collection. |
|
||||||
|
| `FOR EACH` / `EXIT FOR` | Iterate over collections. |
|
||||||
|
| `IF` / `ELSE` / `ENDIF` | Conditional execution. |
|
||||||
|
| `WHILE` / `ENDWHILE` | Loop while a condition holds. |
|
||||||
|
| `REPEAT` / `UNTIL` | Loop until a condition is met. |
|
||||||
|
| `WAIT` | Pause execution for a given duration. |
|
||||||
|
| `ON` | Register an event handler. |
|
||||||
|
| `SET_SCHEDULE` | Define a scheduled task. |
|
||||||
|
| `PRINT` | Output debugging information. |
|
||||||
|
| `GET_BOT_MEMORY` / `SET_BOT_MEMORY` | Access bot‑wide memory store. |
|
||||||
|
| `CREATE_SITE` | Create a new website entry in a knowledge base. |
|
||||||
|
| `CREATE_DRAFT` | Generate a draft document. |
|
||||||
|
| `WEBSITE OF` | Reference a website object. |
|
||||||
|
| `FIND` | Search within collections. |
|
||||||
|
| `GET` / `SET` | Generic getters/setters for variables. |
|
||||||
|
| `...` | See the full keyword list in `chapter-05/keywords.md`. |
|
||||||
|
|
|
||||||
|
|
@ -1 +1,19 @@
|
||||||
# Chapter 09: Feature Matrix
|
## Feature Matrix
|
||||||
|
This table maps major features of GeneralBots to the chapters and keywords that implement them.
|
||||||
|
|
||||||
|
| Feature | Chapter(s) | Primary Keywords |
|
||||||
|
|---------|------------|------------------|
|
||||||
|
| Start server & basic chat | 01 (Run and Talk) | `TALK`, `HEAR` |
|
||||||
|
| Package system overview | 02 (About Packages) | – |
|
||||||
|
| Knowledge‑base management | 03 (gbkb Reference) | `ADD_KB`, `SET_KB`, `ADD_WEBSITE` |
|
||||||
|
| UI theming | 04 (gbtheme Reference) | – (CSS/HTML assets) |
|
||||||
|
| BASIC dialog scripting | 05 (gbdialog Reference) | All BASIC keywords (`TALK`, `HEAR`, `LLM`, `FORMAT`, `ADD_KB`, `SET_KB`, `ADD_WEBSITE`, …) |
|
||||||
|
| Custom Rust extensions | 06 (gbapp Reference) | `ADD_TOOL`, custom Rust code |
|
||||||
|
| Bot configuration | 07 (gbot Reference) | `config.csv` fields |
|
||||||
|
| Built‑in tooling | 08 (Tooling) | All keywords listed in the table |
|
||||||
|
| Answer modes & routing | 07 (gbot Reference) | `answer_mode` column |
|
||||||
|
| Semantic search & Qdrant | 03 (gbkb Reference) | `ADD_WEBSITE`, vector search |
|
||||||
|
| Email & external APIs | 08 (Tooling) | `CALL`, `CALL_ASYNC` |
|
||||||
|
| Scheduling & events | 08 (Tooling) | `SET_SCHEDULE`, `ON` |
|
||||||
|
| Testing & CI | 10 (Contributing) | – |
|
||||||
|
| Database schema | Appendix I | Tables defined in `src/shared/models.rs` |
|
||||||
|
|
|
||||||
|
|
@ -1,186 +1,166 @@
|
||||||
continue this style: generate a docusaurs using mdBook for the application in a point of view of the user, a BASIC person basic knowledge wwkring with LLM.
|
# Prompt for Generating GeneralBots mdBook Documentation
|
||||||
|
|
||||||
GeneralBots User Documentation (mdBook)
|
**Goal**
|
||||||
Code
|
Generate a complete **mdBook** that documents the GeneralBots application for a user with basic knowledge of large‑language models (LLM).
|
||||||
only use real keywords
|
|
||||||
generate a docusaurs using mdBook for the application in a point of view of the user, a BASIC person basic knowledge wwkring with LLM. do not talk a line of rust outside .gbapp chapter!!! you are doing gretae
|
|
||||||
do not invent anything.
|
|
||||||
enhance that wil more text by your analysis of source code enterily
|
|
||||||
Table of Contents
|
|
||||||
Chapter 01 - Run and Talk
|
|
||||||
Chapter 02 - About Packages
|
|
||||||
Chapter 03 - gbkb Reference (each colletion is a vectordb collectoin that can be choosen to participate in conversation context - compacted and with cache)
|
|
||||||
Chapter 04 - gbtheme Reference (change Ui themes with css and html (web/index.html)
|
|
||||||
Chapter 05 - gbdialog Reference (basic tools found in @/templates..... .bas files as REAL EXAMPLES) + keywords.rs mod keywords...
|
|
||||||
Chapter 06 - gbapp Reference (now here, you teach how to build the botserver rust and extend new crates... RUST ONLY APPEARS HERE)
|
|
||||||
Chapter 07 - gbot Reference (show @src/shard/models/ bot_config) user can put in drive .gbot with config.csv and configure various bot params. like anserMode, bot descrptoion, eec.)
|
|
||||||
Chapter 08 - Tooling (Talke about the BASIC AND HOW GET keyword call call external tools integratis features.
|
|
||||||
Chapter 09 - Feature-Matrix (List categories all features of this source code)
|
|
||||||
Chapter 10 - Contributing (
|
|
||||||
Apendix I - Database Model
|
|
||||||
Glossary
|
|
||||||
the only keywords that exists are in @/src/basic/keywords/on.rs for .gbdialog!!!! FUCK; the only thikg .gbkb does is to store collections that can be use in the way ADD_KB keyword like @/templates/announcements.gbai/announcements.gbdialog scripts!!! FUCK.. .gbot will contain a config.csv that mimic the @/src/shared/models.rs bot_config so people can edit it from their DRIVE (minio bot bucket) that contains .gbkb, .gbdialog, .gbot, .gbdrive, .gbtheme!
|
|
||||||
1. **gbapp** are folder extensions within the GeneralBots package type, responsible for GeneralBots services in a back-end development environment. A General Bot App comprises four components: dialogs, models, services, and tests.
|
|
||||||
2. The **.gbui** extension pertains to the GeneralBots front-end development environment. Angular, Riot, React, and HTML enable dynamic functionality for GeneralBots services.
|
|
||||||
3. The **.gtheme** extension is utilized by GeneralBots designers using CSS and PS technologies. A theme consists of CSS files and images.
|
|
||||||
4. **.gbDialog** is an extension responsible for GeneralBots' communication with end-users through bot services. **.gbkb** is a package for executing various types of media.
|
|
||||||
5. The **.gbot** extension refers to the GeneralBots service product.
|
|
||||||
6. **.gbai** denotes the architecture construction of the GeneralBots application.
|
|
||||||
|
|
||||||
GeneralBots User Documentation
|
**Rules**
|
||||||
I'll create a comprehensive mdBook documentation based on the actual source code, using only real keywords and features.
|
- Use **only real keywords** and features that exist in the source code (no invented commands).
|
||||||
|
- Include Rust code **exclusively** in the **gbapp** chapter.
|
||||||
|
- Keep the tone simple, beginner‑friendly, and instructional.
|
||||||
|
- Base all information on the actual code base:
|
||||||
|
- Keywords in `src/basic/keywords/`
|
||||||
|
- Database models in `src/shared/models.rs`
|
||||||
|
- Example scripts in `templates/`
|
||||||
|
|
||||||
GeneralBots Documentation (mdBook)
|
**Required Markdown Structure (headings)**
|
||||||
Code
|
|
||||||
do not write any BASIC example more than templates folder start.bas auth.bas and generate-summary.bas, and include a ingle example of TOOL: PARAM name AS string LIKE "Abreu Silva" DESCRIPTION "Required full name of the individual."
|
|
||||||
PARAM birthday AS date LIKE "23/09/2001" DESCRIPTION "Required birth date of the individual in DD/MM/YYYY format."
|
|
||||||
PARAM email AS string LIKE "abreu.silva@example.com" DESCRIPTION "Required email address for contact purposes."
|
|
||||||
PARAM personalid AS integer LIKE "12345678900" DESCRIPTION "Required Personal ID number of the individual (only numbers)."
|
|
||||||
PARAM address AS string LIKE "Rua das Flores, 123 - SP" DESCRIPTION "Required full address of the individual."
|
|
||||||
DESCRIPTION "This is a the enrollment process, called when the user wants to enrol. Once all information is collected, confirm the details and inform them that their enrollment request has been successfully submitted. Provide a polite and professional tone throughout the interaction."
|
|
||||||
SAVE "enrollments.csv", id, name, birthday, email, personalid, address that is in termos of basic samples, but show all keywords with one with independant page. inside .gbdialog section, more text
|
|
||||||
|
|
||||||
I'll create a comprehensive mdBook documentation focusing on the actual templates and all real keywords from the source code.
|
1. **Run and Talk** – How to start the server and interact using `TALK` / `HEAR`.
|
||||||
|
2. **About Packages** – Overview of the four package types (`.gbdialog`, `.gbkb`, `.gbtheme`, `.gbot`).
|
||||||
|
3. **gbkb Reference** – Explain `ADD_KB`, `SET_KB`, `ADD_WEBSITE`.
|
||||||
|
4. **gbtheme Reference** – Describe UI theming via CSS/HTML.
|
||||||
|
5. **gbdialog Reference** – List the three example scripts (`start.bas`, `auth.bas`, `update-summary.bas`) and the core keywords (`TALK`, `HEAR`, `LLM`, etc.).
|
||||||
|
6. **gbapp Reference** – Show a minimal Rust snippet that registers a keyword (e.g., `ADD_TOOL`).
|
||||||
|
7. **gbot Reference** – Explain the `config.csv` format and editable parameters.
|
||||||
|
8. **Tooling** – Table of all built‑in keywords with one‑line descriptions.
|
||||||
|
9. **Feature‑Matrix** – Table mapping features to the chapters/keywords that implement them.
|
||||||
|
10. **Contributing** – Steps for contributors (fork, branch, tests, formatting).
|
||||||
|
11. **Appendix I – Database Model** – Summarise the main tables from `src/shared/models.rs`.
|
||||||
|
12. **Glossary** – Definitions of extensions and key concepts.
|
||||||
|
|
||||||
# Summary
|
**Output Requirements**
|
||||||
|
|
||||||
[Introduction](./introduction.md)
|
- Produce **only** the markdown content (no surrounding explanations).
|
||||||
|
- Use fenced code blocks with appropriate language tags (`bas` for BASIC scripts, `rust` for Rust snippets).
|
||||||
|
- Include a **Table of Contents** with markdown links to each chapter.
|
||||||
|
- Ensure the document can be built directly with `mdbook build docs/src`.
|
||||||
|
|
||||||
# Part I - Getting Started
|
**Example Skeleton (to be expanded by the generator)**
|
||||||
|
|
||||||
- [Chapter 01: Run and Talk](./chapter-01/README.md)
|
```markdown
|
||||||
- [Installation](./chapter-01/installation.md)
|
# GeneralBots User Documentation (mdBook)
|
||||||
- [First Conversation](./chapter-01/first-conversation.md)
|
|
||||||
- [Understanding Sessions](./chapter-01/sessions.md)
|
|
||||||
|
|
||||||
# Part II - Package System
|
## Table of Contents
|
||||||
|
- [Run and Talk](#run-and-talk)
|
||||||
|
- [About Packages](#about-packages)
|
||||||
|
- [gbkb Reference](#gbkb-reference)
|
||||||
|
- [gbtheme Reference](#gbtheme-reference)
|
||||||
|
- [gbdialog Reference](#gbdialog-reference)
|
||||||
|
- [gbapp Reference](#gbapp-reference)
|
||||||
|
- [gbot Reference](#gbot-reference)
|
||||||
|
- [Tooling](#tooling)
|
||||||
|
- [Feature‑Matrix](#feature-matrix)
|
||||||
|
- [Contributing](#contributing)
|
||||||
|
- [Appendix I – Database Model](#appendix‑i---database-model)
|
||||||
|
- [Glossary](#glossary)
|
||||||
|
|
||||||
- [Chapter 02: About Packages](./chapter-02/README.md)
|
## Run and Talk
|
||||||
- [.gbai Architecture](./chapter-02/gbai.md)
|
```bas
|
||||||
- [.gbdialog Dialogs](./chapter-02/gbdialog.md)
|
TALK "Welcome! How can I help you today?"
|
||||||
- [.gbkb Knowledge Base](./chapter-02/gbkb.md)
|
HEAR user_input
|
||||||
- [.gbot Bot Configuration](./chapter-02/gbot.md)
|
```
|
||||||
- [.gbtheme UI Theming](./chapter-02/gbtheme.md)
|
*Start the server:* `cargo run --release`
|
||||||
- [.gbdrive File Storage](./chapter-02/gbdrive.md)
|
|
||||||
|
|
||||||
# Part III - Knowledge Base
|
## About Packages
|
||||||
|
| Component | Extension | Role |
|
||||||
|
|-----------|-----------|------|
|
||||||
|
| Dialog scripts | `.gbdialog` | BASIC‑style conversational logic |
|
||||||
|
| Knowledge bases | `.gbkb` | Vector‑DB collections |
|
||||||
|
| UI themes | `.gbtheme` | CSS/HTML assets |
|
||||||
|
| Bot config | `.gbot` | CSV mapping to `UserSession` |
|
||||||
|
|
||||||
- [Chapter 03: gbkb Reference](./chapter-03/README.md)
|
## gbkb Reference
|
||||||
- [Vector Collections](./chapter-03/vector-collections.md)
|
...
|
||||||
- [Document Indexing](./chapter-03/indexing.md)
|
|
||||||
- [Qdrant Integration](./chapter-03/qdrant.md)
|
|
||||||
- [Semantic Search](./chapter-03/semantic-search.md)
|
|
||||||
- [Context Compaction](./chapter-03/context-compaction.md)
|
|
||||||
- [Semantic Caching](./chapter-03/caching.md)
|
|
||||||
|
|
||||||
# Part IV - Themes and UI
|
## gbapp Reference
|
||||||
|
```rust
|
||||||
|
pub fn add_tool_keyword(state: Arc<AppState>, user: UserSession, engine: &mut Engine) {
|
||||||
|
// registration logic …
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
- [Chapter 04: gbtheme Reference](./chapter-04/README.md)
|
|
||||||
- [Theme Structure](./chapter-04/structure.md)
|
|
||||||
- [Web Interface](./chapter-04/web-interface.md)
|
|
||||||
- [CSS Customization](./chapter-04/css.md)
|
|
||||||
- [HTML Templates](./chapter-04/html.md)
|
|
||||||
|
|
||||||
# Part V - BASIC Dialogs
|
When you are ready, output the full markdown document that satisfies the specifications above.
|
||||||
|
*Do not include any commentary outside the markdown itself.*
|
||||||
|
|
||||||
- [Chapter 05: gbdialog Reference](./chapter-05/README.md)
|
# FORMAT Keyword
|
||||||
- [Dialog Basics](./chapter-05/basics.md)
|
|
||||||
- [Template Examples](./chapter-05/templates.md)
|
|
||||||
- [start.bas](./chapter-05/template-start.md)
|
|
||||||
- [auth.bas](./chapter-05/template-auth.md)
|
|
||||||
- [generate-summary.bas](./chapter-05/template-summary.md)
|
|
||||||
- [enrollment Tool Example](./chapter-05/template-enrollment.md)
|
|
||||||
- [Keyword Reference](./chapter-05/keywords.md)
|
|
||||||
- [TALK](./chapter-05/keyword-talk.md)
|
|
||||||
- [HEAR](./chapter-05/keyword-hear.md)
|
|
||||||
- [SET_USER](./chapter-05/keyword-set-user.md)
|
|
||||||
- [SET_CONTEXT](./chapter-05/keyword-set-context.md)
|
|
||||||
- [LLM](./chapter-05/keyword-llm.md)
|
|
||||||
- [GET_BOT_MEMORY](./chapter-05/keyword-get-bot-memory.md)
|
|
||||||
- [SET_BOT_MEMORY](./chapter-05/keyword-set-bot-memory.md)
|
|
||||||
- [SET_KB](./chapter-05/keyword-set-kb.md)
|
|
||||||
- [ADD_KB](./chapter-05/keyword-add-kb.md)
|
|
||||||
- [ADD_WEBSITE](./chapter-05/keyword-add-website.md)
|
|
||||||
- [ADD_TOOL](./chapter-05/keyword-add-tool.md)
|
|
||||||
- [LIST_TOOLS](./chapter-05/keyword-list-tools.md)
|
|
||||||
- [REMOVE_TOOL](./chapter-05/keyword-remove-tool.md)
|
|
||||||
- [CLEAR_TOOLS](./chapter-05/keyword-clear-tools.md)
|
|
||||||
- [GET](./chapter-05/keyword-get.md)
|
|
||||||
- [FIND](./chapter-05/keyword-find.md)
|
|
||||||
- [SET](./chapter-05/keyword-set.md)
|
|
||||||
- [ON](./chapter-05/keyword-on.md)
|
|
||||||
- [SET_SCHEDULE](./chapter-05/keyword-set-schedule.md)
|
|
||||||
- [CREATE_SITE](./chapter-05/keyword-create-site.md)
|
|
||||||
- [CREATE_DRAFT](./chapter-05/keyword-create-draft.md)
|
|
||||||
- [WEBSITE OF](./chapter-05/keyword-website-of.md)
|
|
||||||
- [PRINT](./chapter-05/keyword-print.md)
|
|
||||||
- [WAIT](./chapter-05/keyword-wait.md)
|
|
||||||
- [FORMAT](./chapter-05/keyword-format.md)
|
|
||||||
- [FIRST](./chapter-05/keyword-first.md)
|
|
||||||
- [LAST](./chapter-05/keyword-last.md)
|
|
||||||
- [FOR EACH](./chapter-05/keyword-for-each.md)
|
|
||||||
- [EXIT FOR](./chapter-05/keyword-exit-for.md)
|
|
||||||
|
|
||||||
# Part VI - Extending BotServer
|
The **FORMAT** keyword formats numbers, dates, and text for display. Use it when you need a quick, readable representation without writing custom code.
|
||||||
|
|
||||||
- [Chapter 06: gbapp Reference](./chapter-06/README.md)
|
## Syntax
|
||||||
- [Rust Architecture](./chapter-06/architecture.md)
|
```basic
|
||||||
- [Building from Source](./chapter-06/building.md)
|
RESULT = FORMAT(VALUE, PATTERN)
|
||||||
- [Crate Structure](./chapter-06/crates.md)
|
```
|
||||||
- [Service Layer](./chapter-06/services.md)
|
|
||||||
- [Creating Custom Keywords](./chapter-06/custom-keywords.md)
|
|
||||||
- [Adding Dependencies](./chapter-06/dependencies.md)
|
|
||||||
|
|
||||||
# Part VII - Bot Configuration
|
## BASIC EXAMPLE
|
||||||
|
```basic
|
||||||
|
NUMBER = 1234.56
|
||||||
|
TEXT = "John"
|
||||||
|
DATE = "2024-03-15 14:30:00"
|
||||||
|
TALK FORMAT(NUMBER, "n") ' 1234.56
|
||||||
|
TALK FORMAT(TEXT, "Hello @!") ' Hello John!
|
||||||
|
TALK FORMAT(DATE, "dd/MM/yyyy") ' 15/03/2024
|
||||||
|
```
|
||||||
|
- **VALUE** – any number, date string (`YYYY‑MM‑DD HH:MM:SS`), or text.
|
||||||
|
- **PATTERN** – a short format string (see tables below).
|
||||||
|
|
||||||
- [Chapter 07: gbot Reference](./chapter-07/README.md)
|
## Quick Reference
|
||||||
- [config.csv Format](./chapter-07/config-csv.md)
|
|
||||||
- [Bot Parameters](./chapter-07/parameters.md)
|
|
||||||
- [Answer Modes](./chapter-07/answer-modes.md)
|
|
||||||
- [LLM Configuration](./chapter-07/llm-config.md)
|
|
||||||
- [Context Configuration](./chapter-07/context-config.md)
|
|
||||||
- [MinIO Drive Integration](./chapter-07/minio.md)
|
|
||||||
|
|
||||||
# Part VIII - Tools and Integration
|
### Numeric Patterns
|
||||||
|
| Pattern | Example | Output |
|
||||||
|
|---------|---------|--------|
|
||||||
|
| `n` | `FORMAT(1234.5, "n")` | `1234.50` |
|
||||||
|
| `F` | `FORMAT(1234.5, "F")` | `1234.50` |
|
||||||
|
| `f` | `FORMAT(1234.5, "f")` | `1234` |
|
||||||
|
| `0%` | `FORMAT(0.85, "0%")` | `85%` |
|
||||||
|
| `C2[en]` | `FORMAT(1234.5, "C2[en]")` | `$1,234.50` |
|
||||||
|
| `C2[pt]` | `FORMAT(1234.5, "C2[pt]")` | `R$ 1.234,50` |
|
||||||
|
|
||||||
- [Chapter 08: Tooling](./chapter-08/README.md)
|
### Date Patterns
|
||||||
- [Tool Definition](./chapter-08/tool-definition.md)
|
| Code | Meaning | Example |
|
||||||
- [PARAM Declaration](./chapter-08/param-declaration.md)
|
|------|---------|---------|
|
||||||
- [Tool Compilation](./chapter-08/compilation.md)
|
| `yyyy` | 4‑digit year | `2024` |
|
||||||
- [MCP Format](./chapter-08/mcp-format.md)
|
| `yy` | 2‑digit year | `24` |
|
||||||
- [OpenAI Tool Format](./chapter-08/openai-format.md)
|
| `MM` | month (01‑12) | `03` |
|
||||||
- [GET Keyword Integration](./chapter-08/get-integration.md)
|
| `M` | month (1‑12) | `3` |
|
||||||
- [External APIs](./chapter-08/external-apis.md)
|
| `dd` | day (01‑31) | `05` |
|
||||||
|
| `d` | day (1‑31) | `5` |
|
||||||
|
| `HH` | 24‑hour (00‑23) | `14` |
|
||||||
|
| `hh` | 12‑hour (01‑12) | `02` |
|
||||||
|
| `mm` | minutes (00‑59) | `05` |
|
||||||
|
| `ss` | seconds (00‑59) | `09` |
|
||||||
|
| `tt` | AM/PM | `PM` |
|
||||||
|
|
||||||
# Part IX - Feature Reference
|
**Example**
|
||||||
|
```basic
|
||||||
|
DATE = "2024-03-15 14:30:25"
|
||||||
|
TALK FORMAT(DATE, "dd/MM/yyyy HH:mm") ' 15/03/2024 14:30
|
||||||
|
```
|
||||||
|
|
||||||
- [Chapter 09: Feature Matrix](./chapter-09/README.md)
|
### Text Patterns
|
||||||
- [Core Features](./chapter-09/core-features.md)
|
| Placeholder | Effect |
|
||||||
- [Conversation Management](./chapter-09/conversation.md)
|
|-------------|--------|
|
||||||
- [AI and LLM](./chapter-09/ai-llm.md)
|
| `@` | Insert original text |
|
||||||
- [Knowledge Base](./chapter-09/knowledge-base.md)
|
| `!` | Upper‑case |
|
||||||
- [Automation](./chapter-09/automation.md)
|
| `&` | Lower‑case |
|
||||||
- [Email Integration](./chapter-09/email.md)
|
|
||||||
- [Web Automation](./chapter-09/web-automation.md)
|
|
||||||
- [Storage and Data](./chapter-09/storage.md)
|
|
||||||
- [Multi-Channel Support](./chapter-09/channels.md)
|
|
||||||
|
|
||||||
# Part X - Community
|
**Example**
|
||||||
|
```basic
|
||||||
|
NAME = "Maria"
|
||||||
|
TALK FORMAT(NAME, "Hello, !") ' Hello, MARIA
|
||||||
|
```
|
||||||
|
|
||||||
- [Chapter 10: Contributing](./chapter-10/README.md)
|
## Practical Tips
|
||||||
- [Development Setup](./chapter-10/setup.md)
|
- **Test each pattern** in isolation before combining.
|
||||||
- [Code Standards](./chapter-10/standards.md)
|
- **Locale codes** (`en`, `pt`, `fr`, …) go inside `C2[…]` for currency.
|
||||||
- [Testing](./chapter-10/testing.md)
|
- **Dates must follow** `YYYY‑MM‑DD HH:MM:SS`; otherwise formatting fails.
|
||||||
- [Pull Requests](./chapter-10/pull-requests.md)
|
- **Combine patterns** by nesting calls:
|
||||||
- [Documentation](./chapter-10/documentation.md)
|
```basic
|
||||||
|
TALK FORMAT(FORMAT(VALUE, "C2[en]"), "!") ' $1,234.50 (uppercase not needed here)
|
||||||
|
```
|
||||||
|
|
||||||
# Appendices
|
## Common Pitfalls
|
||||||
|
- Using a date pattern on a non‑date string → returns the original string.
|
||||||
- [Appendix I: Database Model](./appendix-i/README.md)
|
- Forgetting locale brackets (`C2[en]`) → defaults to system locale.
|
||||||
- [Schema Overview](./appendix-i/schema.md)
|
- Mixing placeholders (`@`, `!`, `&`) in the same pattern – only the last one applies.
|
||||||
- [Tables](./appendix-i/tables.md)
|
|
||||||
- [Relationships](./appendix-i/relationships.md)
|
|
||||||
|
|
||||||
[Glossary](./glossary.md)
|
|
||||||
EOF
|
|
||||||
|
|
||||||
|
Use **FORMAT** whenever you need a clean, user‑friendly output without extra code. It keeps scripts short and readable.
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue