GeneralBots/botserver
2
1
Fork 0
Code Issues Pull requests Projects Releases 323 Packages Wiki Activity Actions

- From 1 to 4 validated.

Browse source
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-11-23 17:02:22 -03:00
parent 0382a39012
commit 4e76abbba0
81 changed files with 4660 additions and 4393 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

81
docs/FINAL_FIXES_SUMMARY.md Normal file
View file

@ -0,0 +1,81 @@
# Final Documentation Fixes Summary
## Issues Fixed
### 1. ✅ Diagram Alignment
- Fixed right border alignment issues in multiple diagrams
- Standardized spacing and alignment across all ASCII art diagrams
- Ensured consistent box sizes and connections
### 2. ✅ Removed Roadmap References
- Removed all roadmap mentions from documentation:
- Chapter 10 README.md (2 occurrences)
- Chapter 10 pull-requests.md (1 occurrence)
- No more roadmap references in the documentation
### 3. ✅ Moved NVIDIA GPU Setup
- Moved from Chapter 1 to Chapter 8 (Tooling)
- Updated SUMMARY.md references
- Makes more sense in the tools/integration chapter
### 4. ✅ Authentication Terminology
- Changed to mention "Zitadel" only once in user-auth.md
- Now refers to "directory service" throughout
- Notes that it's installed via installer.rs
- More generic and accurate terminology
### 5. ✅ Fixed Chapter 1
- **Step 2**: Changed to "Write a simple tool" (was misleading before)
- **Removed environment variables section**: Was incorrect, not needed
- **Binary references**: Removed excessive "Rust" mentions, just say "binary"
- More accurate and cleaner presentation
### 6. ✅ Sessions Documentation
- Renamed "Understanding Sessions" to "Sessions and Channels"
- Removed "best practices" section (it's automatic, no practices needed)
- Added "Write Once, Run Everywhere" section about multi-channel support
- Emphasized automatic nature of sessions
- Added mobile app support via web views
### 7. ✅ Removed Non-Existent Keywords
Deleted documentation files and SUMMARY.md references for keywords that don't exist:
- ADD MEMBER
- ADD SUGGESTION
- CLEAR SUGGESTIONS
- BOOK
- REMEMBER
- SAVE FROM UNSTRUCTURED
- WEATHER
- CHANGE THEME
### 8. ✅ Cleaned Up Language
- Stopped saying "Rust" everywhere - just "binary" or "BotServer"
- Made documentation less technical where appropriate
- Focused on what users can do, not implementation details
## Files Modified
### Major Changes
- `/chapter-01/README.md` - Removed env vars, fixed step 2
- `/chapter-01/sessions.md` - Renamed, removed practices, added channels
- `/chapter-11/user-auth.md` - Directory service terminology
- `/introduction.md` - Fixed diagrams, removed "Rust" emphasis
- `/SUMMARY.md` - Removed 8 non-existent keywords, moved GPU setup
### Files Deleted
- 8 keyword documentation files that didn't correspond to real keywords
### Files Moved
- `chapter-01/nvidia-gpu-setup.md` → `chapter-08/nvidia-gpu-setup.md`
## Result
The documentation is now:
- ✅ More accurate (no phantom features)
- ✅ Better organized (GPU setup in right place)
- ✅ Cleaner presentation (aligned diagrams)
- ✅ Consistent terminology (directory service)
- ✅ Focused on users (not implementation)
- ✅ Honest about capabilities (removed non-existent keywords)
All requested fixes have been completed.

2
docs/src/README.md
View file

@ -169,7 +169,7 @@ This documentation is a **living document** that evolves with the codebase. Cont
2. Submit documentation improvements via pull requests
3. Report issues on GitHub
See [TODO.txt](TODO.txt) for known documentation gaps and future enhancements.
See [TODO.txt](TODO.txt) for known documentation gaps.
---

16
docs/src/SUMMARY.md
View file

@ -9,8 +9,7 @@
- [Quick Start](./chapter-01/quick-start.md)
- [Installation](./chapter-01/installation.md)
- [First Conversation](./chapter-01/first-conversation.md)
- [Understanding Sessions](./chapter-01/sessions.md)
- [NVIDIA GPU Setup for LXC](./chapter-01/nvidia-gpu-setup.md)
- [Sessions and Channels](./chapter-01/sessions.md)
# Part II - Package System
@ -29,11 +28,9 @@
- [KB and Tools System](./chapter-03/kb-and-tools.md)
- [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)
- [Semantic Cache with Valkey](./chapter-03/semantic-cache.md)
# Part IV - Themes and UI
@ -57,9 +54,7 @@
- [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)
- [USE KB](./chapter-05/keyword-use-kb.md)
@ -81,16 +76,8 @@
- [LAST](./chapter-05/keyword-last.md)
- [FOR EACH](./chapter-05/keyword-for-each.md)
- [EXIT FOR](./chapter-05/keyword-exit-for.md)
- [ADD MEMBER](./chapter-05/keyword-add-member.md)
- [ADD SUGGESTION](./chapter-05/keyword-add-suggestion.md)
- [CLEAR SUGGESTIONS](./chapter-05/keyword-clear-suggestions.md)
- [BOOK](./chapter-05/keyword-book.md)
- [REMEMBER](./chapter-05/keyword-remember.md)
- [SAVE FROM UNSTRUCTURED](./chapter-05/keyword-save-from-unstructured.md)
- [SEND MAIL](./chapter-05/keyword-send-mail.md)
- [WEATHER](./chapter-05/keyword-weather.md)
- [FIND](./chapter-05/keyword-find.md)
- [CHANGE THEME](./chapter-05/keyword-change-theme.md)
# Part VI - Extending BotServer
@ -123,6 +110,7 @@
- [Tool Format](./chapter-08/openai-format.md)
- [GET Keyword Integration](./chapter-08/get-integration.md)
- [External APIs](./chapter-08/external-apis.md)
- [NVIDIA GPU Setup for LXC](./chapter-08/nvidia-gpu-setup.md)
# Part IX - Feature Reference

100
docs/src/appendix-i/assets/kb-access.svg Normal file
View file

@ -0,0 +1,100 @@
<svg width="800" height="400" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
<marker id="arrow-ref" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#999"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Knowledge Base Access</text>
<!-- user_sessions -->
<rect x="50" y="80" width="200" height="120" fill="none" stroke="#FBBF24" stroke-width="2" rx="8"/>
<rect x="50" y="80" width="200" height="30" fill="none" stroke="#FBBF24" stroke-width="2" rx="8 8 0 0"/>
<text x="150" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FCD34D">user_sessions</text>
<g font-family="monospace" font-size="11" fill="#A0AEC0">
<text x="60" y="130">• id</text>
<text x="60" y="145">• user_id</text>
<text x="60" y="160">• bot_id</text>
<text x="60" y="175">• session_token</text>
</g>
<!-- Arrow to user_kb_associations -->
<line x1="250" y1="140" x2="320" y2="140" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<text x="285" y="130" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#718096">Has Access</text>
<!-- user_kb_associations -->
<rect x="320" y="80" width="200" height="120" fill="none" stroke="#4FD1C5" stroke-width="2" rx="8"/>
<rect x="320" y="80" width="200" height="30" fill="none" stroke="#4FD1C5" stroke-width="2" rx="8 8 0 0"/>
<text x="420" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#81E6D9">user_kb_associations</text>
<g font-family="monospace" font-size="11" fill="#A0AEC0">
<text x="330" y="130">• id</text>
<text x="330" y="145">• session_id</text>
<text x="330" y="160">• kb_id</text>
<text x="330" y="175">• created_at</text>
</g>
<!-- Reference arrow down -->
<line x1="420" y1="200" x2="420" y2="240" stroke="#999" stroke-width="2" stroke-dasharray="5,5" marker-end="url(#arrow-ref)"/>
<text x="435" y="220" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#718096">References</text>
<!-- kb_collections -->
<rect x="50" y="240" width="200" height="140" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
<rect x="50" y="240" width="200" height="30" fill="none" stroke="#48BB78" stroke-width="2" rx="8 8 0 0"/>
<text x="150" y="260" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">kb_collections</text>
<g font-family="monospace" font-size="11" fill="#A0AEC0">
<text x="60" y="290">• id</text>
<text x="60" y="305">• bot_id</text>
<text x="60" y="320">• name</text>
<text x="60" y="335">• created_at</text>
<text x="60" y="350">• metadata</text>
</g>
<!-- Arrow to kb_documents -->
<line x1="250" y1="310" x2="320" y2="310" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<text x="285" y="300" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#718096">Contains</text>
<text x="285" y="320" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- kb_documents -->
<rect x="320" y="240" width="200" height="140" fill="none" stroke="#68D391" stroke-width="2" rx="8"/>
<rect x="320" y="240" width="200" height="30" fill="none" stroke="#68D391" stroke-width="2" rx="8 8 0 0"/>
<text x="420" y="260" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#9AE6B4">kb_documents</text>
<g font-family="monospace" font-size="11" fill="#A0AEC0">
<text x="330" y="290">• id</text>
<text x="330" y="305">• collection_id</text>
<text x="330" y="320">• content</text>
<text x="330" y="335">• embeddings</text>
<text x="330" y="350">• metadata</text>
</g>
<!-- Vector indicator -->
<g id="vector-indicator" transform="translate(550, 280)">
<rect x="0" y="0" width="180" height="80" fill="none" stroke="#B794F4" stroke-width="1" rx="5" stroke-dasharray="3,3" opacity="0.7"/>
<text x="90" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#D6BCFA">Vector Storage</text>
<text x="90" y="45" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Embeddings stored</text>
<text x="90" y="60" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">for semantic search</text>
</g>
<!-- Connection from kb_documents to vector indicator -->
<line x1="520" y1="335" x2="550" y2="320" stroke="#B794F4" stroke-width="1" stroke-dasharray="3,3" opacity="0.7"/>
<!-- Access flow description -->
<g id="access-flow" transform="translate(550, 100)">
<rect x="0" y="0" width="200" height="100" fill="none" stroke="#4A5568" stroke-width="1" rx="5" stroke-dasharray="2,2" opacity="0.5"/>
<text x="100" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#CBD5E0">Access Pattern</text>
<g font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">
<text x="10" y="40">1. Session requests KB</text>
<text x="10" y="55">2. Association created</text>
<text x="10" y="70">3. KB documents available</text>
<text x="10" y="85">4. Vector search enabled</text>
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 5.6 KiB

186
docs/src/appendix-i/assets/schema-detailed.svg Normal file
View file

@ -0,0 +1,186 @@
<svg width="1000" height="700" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="500" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Database Entity Details</text>
<!-- Organizations Table -->
<g id="organizations">
<rect x="50" y="60" width="400" height="150" fill="none" stroke="#4299E1" stroke-width="2" rx="5"/>
<rect x="50" y="60" width="400" height="30" fill="none" stroke="#4299E1" stroke-width="2" rx="5 5 0 0"/>
<text x="250" y="80" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#63B3ED">organizations</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="60" y="110">id: UUID (PK)</text>
<text x="60" y="130">name: VARCHAR(255)</text>
<text x="60" y="150">created_at: TIMESTAMPTZ</text>
<text x="60" y="170">updated_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Bots Table -->
<g id="bots">
<rect x="550" y="60" width="400" height="190" fill="none" stroke="#48BB78" stroke-width="2" rx="5"/>
<rect x="550" y="60" width="400" height="30" fill="none" stroke="#48BB78" stroke-width="2" rx="5 5 0 0"/>
<text x="750" y="80" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">bots</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="560" y="110">id: UUID (PK)</text>
<text x="560" y="130">organization_id: UUID (FK)</text>
<text x="560" y="150">name: VARCHAR(255)</text>
<text x="560" y="170">configuration: JSONB</text>
<text x="560" y="190">created_at: TIMESTAMPTZ</text>
<text x="560" y="210">updated_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Bot Memories Table -->
<g id="bot_memories">
<rect x="50" y="290" width="280" height="130" fill="none" stroke="#B794F4" stroke-width="2" rx="5"/>
<rect x="50" y="290" width="280" height="30" fill="none" stroke="#B794F4" stroke-width="2" rx="5 5 0 0"/>
<text x="190" y="310" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">bot_memories</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="60" y="340">id: UUID (PK)</text>
<text x="60" y="360">bot_id: UUID (FK)</text>
<text x="60" y="380">key: TEXT</text>
<text x="60" y="400">value: TEXT</text>
</g>
</g>
<!-- User Sessions Table -->
<g id="user_sessions">
<rect x="360" y="290" width="280" height="170" fill="none" stroke="#FBBF24" stroke-width="2" rx="5"/>
<rect x="360" y="290" width="280" height="30" fill="none" stroke="#FBBF24" stroke-width="2" rx="5 5 0 0"/>
<text x="500" y="310" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FCD34D">user_sessions</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="370" y="340">id: UUID (PK)</text>
<text x="370" y="360">user_id: UUID (FK)</text>
<text x="370" y="380">bot_id: UUID (FK)</text>
<text x="370" y="400">session_token: TEXT</text>
<text x="370" y="420">created_at: TIMESTAMPTZ</text>
<text x="370" y="440">expires_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- KB Collections Table -->
<g id="kb_collections">
<rect x="670" y="290" width="280" height="150" fill="none" stroke="#4FD1C5" stroke-width="2" rx="5"/>
<rect x="670" y="290" width="280" height="30" fill="none" stroke="#4FD1C5" stroke-width="2" rx="5 5 0 0"/>
<text x="810" y="310" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#81E6D9">kb_collections</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="680" y="340">id: TEXT (PK)</text>
<text x="680" y="360">bot_id: UUID (FK)</text>
<text x="680" y="380">name: TEXT</text>
<text x="680" y="400">description: TEXT</text>
<text x="680" y="420">created_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Users Table -->
<g id="users">
<rect x="50" y="480" width="280" height="170" fill="none" stroke="#FC8181" stroke-width="2" rx="5"/>
<rect x="50" y="480" width="280" height="30" fill="none" stroke="#FC8181" stroke-width="2" rx="5 5 0 0"/>
<text x="190" y="500" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">users</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="60" y="530">id: UUID (PK)</text>
<text x="60" y="550">username: TEXT</text>
<text x="60" y="570">email: TEXT</text>
<text x="60" y="590">password_hash: TEXT</text>
<text x="60" y="610">active: BOOLEAN</text>
<text x="60" y="630">created_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Message History Table -->
<g id="message_history">
<rect x="360" y="480" width="280" height="170" fill="none" stroke="#A78BFA" stroke-width="2" rx="5"/>
<rect x="360" y="480" width="280" height="30" fill="none" stroke="#A78BFA" stroke-width="2" rx="5 5 0 0"/>
<text x="500" y="500" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#C4B5FD">message_history</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="370" y="530">id: UUID (PK)</text>
<text x="370" y="550">session_id: UUID (FK)</text>
<text x="370" y="570">user_id: UUID (FK)</text>
<text x="370" y="590">bot_id: UUID (FK)</text>
<text x="370" y="610">message: TEXT</text>
<text x="370" y="630">sender: TEXT</text>
</g>
</g>
<!-- KB Documents Table -->
<g id="kb_documents">
<rect x="670" y="480" width="280" height="170" fill="none" stroke="#34D399" stroke-width="2" rx="5"/>
<rect x="670" y="480" width="280" height="30" fill="none" stroke="#34D399" stroke-width="2" rx="5 5 0 0"/>
<text x="810" y="500" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#6EE7B7">kb_documents</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="680" y="530">id: UUID (PK)</text>
<text x="680" y="550">collection_id: TEXT (FK)</text>
<text x="680" y="570">content: TEXT</text>
<text x="680" y="590">embeddings: VECTOR</text>
<text x="680" y="610">metadata: JSONB</text>
<text x="680" y="630">created_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Relationships -->
<g stroke="#888" stroke-width="2" fill="none">
<!-- organizations to bots -->
<line x1="450" y1="135" x2="550" y2="135" marker-end="url(#arrow)"/>
<text x="500" y="130" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- bots to bot_memories -->
<line x1="750" y1="250" x2="190" y2="290" marker-end="url(#arrow)"/>
<text x="470" y="270" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- bots to user_sessions -->
<line x1="750" y1="250" x2="500" y2="290" marker-end="url(#arrow)"/>
<!-- bots to kb_collections -->
<line x1="750" y1="250" x2="810" y2="290" marker-end="url(#arrow)"/>
<text x="780" y="270" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- kb_collections to kb_documents -->
<line x1="810" y1="440" x2="810" y2="480" marker-end="url(#arrow)"/>
<text x="825" y="460" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- user_sessions to message_history -->
<line x1="500" y1="460" x2="500" y2="480" marker-end="url(#arrow)"/>
<text x="515" y="470" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- users to user_sessions (dotted) -->
<path d="M 330 565 L 360 390" stroke-dasharray="5,5" marker-end="url(#arrow)" opacity="0.6"/>
<text x="345" y="475" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
</g>
<!-- Legend -->
<g id="legend" transform="translate(50, 670)">
<text x="0" y="0" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#CBD5E0">Color Coding:</text>
<rect x="100" y="-10" width="20" height="10" fill="none" stroke="#4299E1" stroke-width="2"/>
<text x="125" y="0" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Organization</text>
<rect x="220" y="-10" width="20" height="10" fill="none" stroke="#48BB78" stroke-width="2"/>
<text x="245" y="0" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Bot Core</text>
<rect x="320" y="-10" width="20" height="10" fill="none" stroke="#FBBF24" stroke-width="2"/>
<text x="345" y="0" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Sessions</text>
<rect x="420" y="-10" width="20" height="10" fill="none" stroke="#4FD1C5" stroke-width="2"/>
<text x="445" y="0" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Knowledge</text>
<rect x="530" y="-10" width="20" height="10" fill="none" stroke="#FC8181" stroke-width="2"/>
<text x="555" y="0" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Users</text>
<rect x="620" y="-10" width="20" height="10" fill="none" stroke="#A78BFA" stroke-width="2"/>
<text x="645" y="0" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Messages</text>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 9.3 KiB

139
docs/src/appendix-i/assets/schema-overview.svg Normal file
View file

@ -0,0 +1,139 @@
<svg width="900" height="600" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="450" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Database Schema Overview</text>
<!-- Organizations -->
<rect x="50" y="60" width="180" height="60" fill="none" stroke="#4299E1" stroke-width="2" rx="5"/>
<text x="140" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#63B3ED">organizations</text>
<text x="140" y="105" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#90CDF4">Top Level Entity</text>
<!-- Bots -->
<rect x="320" y="60" width="180" height="60" fill="none" stroke="#48BB78" stroke-width="2" rx="5"/>
<text x="410" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">bots</text>
<text x="410" y="105" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#9AE6B4">Bot Instances</text>
<!-- Bot Configuration -->
<rect x="590" y="60" width="180" height="60" fill="none" stroke="#F6AD55" stroke-width="2" rx="5"/>
<text x="680" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBD38D">bot_configuration</text>
<text x="680" y="105" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FED7AA">Settings</text>
<!-- Bot Memories -->
<rect x="220" y="180" width="180" height="60" fill="none" stroke="#B794F4" stroke-width="2" rx="5"/>
<text x="310" y="205" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">bot_memories</text>
<text x="310" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">State Storage</text>
<!-- KB Collections -->
<rect x="420" y="180" width="180" height="60" fill="none" stroke="#4FD1C5" stroke-width="2" rx="5"/>
<text x="510" y="205" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#81E6D9">kb_collections</text>
<text x="510" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#B2F5EA">Knowledge Base</text>
<!-- KB Documents -->
<rect x="420" y="280" width="180" height="60" fill="none" stroke="#4FD1C5" stroke-width="2" rx="5"/>
<text x="510" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#81E6D9">kb_documents</text>
<text x="510" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#B2F5EA">Documents</text>
<!-- Users -->
<rect x="50" y="380" width="180" height="60" fill="none" stroke="#FC8181" stroke-width="2" rx="5"/>
<text x="140" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">users</text>
<text x="140" y="425" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FEB2B2">User Accounts</text>
<!-- User Sessions -->
<rect x="320" y="380" width="180" height="60" fill="none" stroke="#FBBF24" stroke-width="2" rx="5"/>
<text x="410" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FCD34D">user_sessions</text>
<text x="410" y="425" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FDE68A">Active Sessions</text>
<!-- Message History -->
<rect x="590" y="380" width="180" height="60" fill="none" stroke="#A78BFA" stroke-width="2" rx="5"/>
<text x="680" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#C4B5FD">message_history</text>
<text x="680" y="425" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#DDD6FE">Chat Messages</text>
<!-- User Login Tokens -->
<rect x="50" y="480" width="180" height="60" fill="none" stroke="#F87171" stroke-width="2" rx="5"/>
<text x="140" y="505" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#F87171">user_login_tokens</text>
<text x="140" y="525" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FCA5A5">Auth Tokens</text>
<!-- User KB Associations -->
<rect x="320" y="480" width="180" height="60" fill="none" stroke="#34D399" stroke-width="2" rx="5"/>
<text x="410" y="505" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#6EE7B7">user_kb_associations</text>
<text x="410" y="525" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A7F3D0">KB Access</text>
<!-- Session Tool Associations -->
<rect x="590" y="480" width="180" height="60" fill="none" stroke="#60A5FA" stroke-width="2" rx="5"/>
<text x="680" y="505" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#93C5FD">session_tool_associations</text>
<text x="680" y="525" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#BFDBFE">Tool Access</text>
<!-- Basic Tools -->
<rect x="650" y="280" width="180" height="60" fill="none" stroke="#F59E0B" stroke-width="2" rx="5"/>
<text x="740" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBBF24">basic_tools</text>
<text x="740" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FCD34D">BASIC Scripts</text>
<!-- Relationships -->
<g stroke="#888" stroke-width="2" fill="none">
<!-- organizations to bots -->
<line x1="230" y1="90" x2="320" y2="90" marker-end="url(#arrow)"/>
<text x="275" y="85" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- bots to bot_configuration -->
<line x1="500" y1="90" x2="590" y2="90" marker-end="url(#arrow)"/>
<text x="545" y="85" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- bots to bot_memories -->
<line x1="360" y1="120" x2="310" y2="180" marker-end="url(#arrow)"/>
<text x="330" y="150" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- bots to kb_collections -->
<line x1="460" y1="120" x2="510" y2="180" marker-end="url(#arrow)"/>
<text x="485" y="150" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- kb_collections to kb_documents -->
<line x1="510" y1="240" x2="510" y2="280" marker-end="url(#arrow)"/>
<text x="525" y="260" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- users to user_sessions -->
<line x1="230" y1="410" x2="320" y2="410" marker-end="url(#arrow)"/>
<text x="275" y="405" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- user_sessions to message_history -->
<line x1="500" y1="410" x2="590" y2="410" marker-end="url(#arrow)"/>
<text x="545" y="405" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- users to user_login_tokens -->
<line x1="140" y1="440" x2="140" y2="480" marker-end="url(#arrow)"/>
<text x="155" y="460" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- user_sessions to user_kb_associations -->
<line x1="410" y1="440" x2="410" y2="480" marker-end="url(#arrow)"/>
<text x="425" y="460" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- user_sessions to session_tool_associations -->
<line x1="480" y1="440" x2="620" y2="480" marker-end="url(#arrow)"/>
<text x="550" y="460" font-family="Arial, sans-serif" font-size="10" fill="#718096">1:N</text>
<!-- user_kb_associations to kb_collections (reference) -->
<path d="M 410 480 Q 410 360 510 240" stroke-dasharray="5,5" marker-end="url(#arrow)" opacity="0.6"/>
<text x="450" y="360" font-family="Arial, sans-serif" font-size="10" fill="#718096">ref</text>
<!-- session_tool_associations to basic_tools (reference) -->
<path d="M 680 480 Q 740 400 740 340" stroke-dasharray="5,5" marker-end="url(#arrow)" opacity="0.6"/>
<text x="710" y="410" font-family="Arial, sans-serif" font-size="10" fill="#718096">ref</text>
<!-- bots to user_sessions (cross reference) -->
<path d="M 410 120 Q 410 250 410 380" stroke-dasharray="3,3" opacity="0.4"/>
</g>
<!-- Legend -->
<g id="legend" transform="translate(50, 550)">
<text x="0" y="0" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#CBD5E0">Legend:</text>
<line x1="80" y1="-5" x2="120" y2="-5" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<text x="125" y="0" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">1:N Relationship</text>
<line x1="250" y1="-5" x2="290" y2="-5" stroke="#888" stroke-width="2" stroke-dasharray="5,5" marker-end="url(#arrow)" opacity="0.6"/>
<text x="295" y="0" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Reference</text>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 9 KiB

95
docs/src/appendix-i/assets/session-flow.svg Normal file
View file

@ -0,0 +1,95 @@
<svg width="700" height="500" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="350" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Session Flow Diagram</text>
<!-- User Login -->
<rect x="50" y="70" width="180" height="80" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="140" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#90CDF4">User Login</text>
<text x="140" y="120" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Authentication</text>
<text x="140" y="135" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Entry Point</text>
<!-- Arrow -->
<line x1="230" y1="110" x2="280" y2="110" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<text x="255" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#718096">Creates</text>
<!-- users table -->
<rect x="280" y="70" width="180" height="130" fill="none" stroke="#FC8181" stroke-width="2" rx="8"/>
<rect x="280" y="70" width="180" height="30" fill="none" stroke="#FC8181" stroke-width="2" rx="8 8 0 0"/>
<text x="370" y="90" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">users</text>
<g font-family="monospace" font-size="11" fill="#A0AEC0">
<text x="290" y="120">• id</text>
<text x="290" y="135">• email</text>
<text x="290" y="150">• zitadel_id</text>
<text x="290" y="165">• created_at</text>
<text x="290" y="180">• updated_at</text>
</g>
<!-- Arrow down -->
<line x1="370" y1="200" x2="370" y2="240" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<text x="385" y="220" text-anchor="start" font-family="Arial, sans-serif" font-size="10" fill="#718096">Creates</text>
<!-- user_sessions table -->
<rect x="280" y="240" width="180" height="150" fill="none" stroke="#FBBF24" stroke-width="2" rx="8"/>
<rect x="280" y="240" width="180" height="30" fill="none" stroke="#FBBF24" stroke-width="2" rx="8 8 0 0"/>
<text x="370" y="260" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FCD34D">user_sessions</text>
<g font-family="monospace" font-size="11" fill="#A0AEC0">
<text x="290" y="290">• id</text>
<text x="290" y="305">• user_id</text>
<text x="290" y="320">• bot_id</text>
<text x="290" y="335">• token</text>
<text x="290" y="350">• created_at</text>
<text x="290" y="365">• expires_at</text>
</g>
<!-- Arrow to message_history -->
<line x1="460" y1="315" x2="510" y2="315" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<text x="485" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#718096">Generates</text>
<text x="485" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#718096">Messages</text>
<!-- message_history table -->
<rect x="510" y="240" width="180" height="150" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
<rect x="510" y="240" width="180" height="30" fill="none" stroke="#B794F4" stroke-width="2" rx="8 8 0 0"/>
<text x="600" y="260" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">message_history</text>
<g font-family="monospace" font-size="11" fill="#A0AEC0">
<text x="520" y="290">• id</text>
<text x="520" y="305">• session_id</text>
<text x="520" y="320">• role</text>
<text x="520" y="335">• content</text>
<text x="520" y="350">• timestamp</text>
<text x="520" y="365">• metadata</text>
</g>
<!-- Flow indicators -->
<g id="flow-numbers" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#4A5568">
<circle cx="140" cy="70" r="15" fill="none" stroke="#4A5568" stroke-width="1"/>
<text x="140" y="75" text-anchor="middle">1</text>
<circle cx="370" cy="70" r="15" fill="none" stroke="#4A5568" stroke-width="1"/>
<text x="370" y="75" text-anchor="middle">2</text>
<circle cx="370" cy="240" r="15" fill="none" stroke="#4A5568" stroke-width="1"/>
<text x="370" y="245" text-anchor="middle">3</text>
<circle cx="600" cy="240" r="15" fill="none" stroke="#4A5568" stroke-width="1"/>
<text x="600" y="245" text-anchor="middle">4</text>
</g>
<!-- Process description -->
<g id="process-description" transform="translate(50, 420)">
<rect x="0" y="0" width="600" height="60" fill="none" stroke="#4A5568" stroke-width="1" rx="5" stroke-dasharray="2,2" opacity="0.5"/>
<text x="300" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#CBD5E0">Process Flow</text>
<g font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">
<text x="20" y="45">1. User authenticates → 2. User record created/updated → 3. Session established → 4. Messages logged</text>
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 5.2 KiB

51
docs/src/appendix-i/relationships.md
View file

@ -12,13 +12,13 @@ The database follows a hierarchical structure with organizations at the top, con
```
organizations
├── bots (1:N)
├── bot_configuration (1:N)
├── bot_memories (1:N)
├── kb_collections (1:N)
│ └── kb_documents (1:N)
├── basic_tools (1:N)
└── system_automations (1:N)
bots (1:N)
bot_configuration (1:N)
bot_memories (1:N)
kb_collections (1:N)
kb_documents (1:N)
basic_tools (1:N)
system_automations (1:N)
```
**Key Relationships:**
@ -30,16 +30,17 @@ organizations
```
users
├── user_sessions (1:N)
│ ├── message_history (1:N)
│ ├── clicks (1:N)
│ ├── user_kb_associations (1:N)
│ └── session_tool_associations (1:N)
├── user_login_tokens (1:N)
├── user_preferences (1:1)
└── user_email_accounts (1:N)
├── email_drafts (1:N)
└── email_folders (1:N)
user_sessions (1:N)
message_history (1:N)
clicks (1:N)
user_kb_associations (1:N)
session_tool_associations (1:N)
user_login_tokens (1:N)
user_preferences (1:1)
user_email_accounts (1:N)
email_drafts (1:N)
email_folders (1:N)
folder_messages (1:N)
```
**Key Relationships:**
@ -51,13 +52,15 @@ users
```
bots ←→ user_sessions ←→ users
│ │
│ ├── message_history
│ ├── user_kb_associations → kb_collections
│ └── session_tool_associations → basic_tools
│
├── kb_collections
└── basic_tools
user_sessions:
message_history
user_kb_associations → kb_collections
session_tool_associations → basic_tools
bots:
kb_collections
basic_tools
```
**Key Relationships:**

21
docs/src/appendix-i/schema.md
View file

@ -10,6 +10,17 @@ The database schema follows these design principles:
- **Foreign Key Relationships**: Referential integrity between related entities
- **JSON Fields**: Flexible storage for dynamic configuration and metadata
## Database Schema Diagram
## Entity Relationship Overview
![Database Schema Overview](./assets/schema-overview.svg)
### Core Tables Structure
## Detailed Schema
![Database Entity Details](./assets/schema-detailed.svg)
## Schema Categories
### 1. Organization & Bot Management
@ -43,6 +54,16 @@ The database schema follows these design principles:
## Table Relationships
### Session Management Flow
### Session Flow
![Session Flow Diagram](./assets/session-flow.svg)
### Knowledge Base Access Pattern
### Knowledge Base Access
![Knowledge Base Access](./assets/kb-access.svg)
### Primary Relationships
1. **Bot Hierarchy**

79
docs/src/assets/architecture.svg Normal file
View file

@ -0,0 +1,79 @@
<svg width="900" height="600" xmlns="http://www.w3.org/2000/svg">
<!-- Main Container -->
<rect x="50" y="30" width="800" height="540" fill="none" stroke="#4A5568" stroke-width="3" rx="10"/>
<!-- Title Bar -->
<rect x="50" y="30" width="800" height="50" fill="none" stroke="#4A5568" stroke-width="2" rx="10 10 0 0"/>
<text x="450" y="60" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="bold" fill="#E2E8F0">BotServer (Single Binary)</text>
<!-- Top Layer Components -->
<g id="top-components">
<!-- Web Server -->
<rect x="100" y="120" width="200" height="80" fill="none" stroke="#4299E1" stroke-width="2" rx="8"/>
<text x="200" y="150" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#63B3ED">Web Server</text>
<text x="200" y="175" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#90CDF4">(Axum)</text>
<!-- BASIC Interpreter -->
<rect x="350" y="120" width="200" height="80" fill="none" stroke="#F56565" stroke-width="2" rx="8"/>
<text x="450" y="150" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#FC8181">BASIC</text>
<text x="450" y="175" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#FEB2B2">Interpreter</text>
<text x="450" y="190" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FBB6CE">(Rhai)</text>
<!-- LLM Integration -->
<rect x="600" y="120" width="200" height="80" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
<text x="700" y="150" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#D6BCFA">LLM</text>
<text x="700" y="175" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#E9D8FD">Integration</text>
</g>
<!-- Connection Lines from Top to Middle -->
<g stroke="#718096" stroke-width="2" fill="none">
<line x1="200" y1="200" x2="200" y2="240" stroke-dasharray="5,5" opacity="0.6"/>
<line x1="450" y1="200" x2="450" y2="240" stroke-dasharray="5,5" opacity="0.6"/>
<line x1="700" y1="200" x2="700" y2="240" stroke-dasharray="5,5" opacity="0.6"/>
</g>
<!-- Session Manager -->
<rect x="100" y="240" width="700" height="60" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
<text x="450" y="275" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#68D391">Session Manager (Tokio)</text>
<!-- Connection Lines from Middle to Data Layer -->
<g stroke="#718096" stroke-width="2" fill="none">
<line x1="250" y1="300" x2="250" y2="340" stroke-dasharray="5,5" opacity="0.6"/>
<line x1="450" y1="300" x2="450" y2="340" stroke-dasharray="5,5" opacity="0.6"/>
<line x1="650" y1="300" x2="650" y2="340" stroke-dasharray="5,5" opacity="0.6"/>
</g>
<!-- Data Layer Components -->
<g id="data-components">
<!-- PostgreSQL -->
<rect x="100" y="340" width="200" height="80" fill="none" stroke="#4A90E2" stroke-width="2" rx="8"/>
<text x="200" y="370" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#5BA0F2">PostgreSQL</text>
<text x="200" y="395" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#7BB4F6">Database</text>
<!-- Valkey Cache -->
<rect x="350" y="340" width="200" height="80" fill="none" stroke="#E53E3E" stroke-width="2" rx="8"/>
<text x="450" y="370" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#FC6B6B">Valkey</text>
<text x="450" y="395" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#FD8E8E">Cache</text>
<!-- Qdrant Vectors -->
<rect x="600" y="340" width="200" height="80" fill="none" stroke="#38D4B2" stroke-width="2" rx="8"/>
<text x="700" y="370" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#4EECC8">Qdrant</text>
<text x="700" y="395" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#6FF4D2">Vectors</text>
</g>
<!-- Object Storage -->
<rect x="100" y="450" width="700" height="100" fill="none" stroke="#38A169" stroke-width="2" rx="8"/>
<text x="450" y="480" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#48BB78">Object Storage (SeaweedFS/S3)</text>
<!-- Storage Items -->
<g id="storage-items">
<rect x="150" y="500" width="150" height="35" fill="none" stroke="#68D391" stroke-width="1" rx="5"/>
<text x="225" y="522" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#9AE6B4">Documents</text>
<rect x="375" y="500" width="150" height="35" fill="none" stroke="#68D391" stroke-width="1" rx="5"/>
<text x="450" y="522" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#9AE6B4">Templates</text>
<rect x="600" y="500" width="150" height="35" fill="none" stroke="#68D391" stroke-width="1" rx="5"/>
<text x="675" y="522" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#9AE6B4">Assets</text>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 5.1 KiB

59
docs/src/assets/conversation-flow.svg Normal file
View file

@ -0,0 +1,59 @@
<svg width="800" height="200" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#666"/>
</marker>
</defs>
<!-- Boxes -->
<g id="boxes">
<!-- User Input -->
<rect x="20" y="30" width="100" height="40" fill="none" stroke="#4A9EFF" stroke-width="2" rx="5"/>
<text x="70" y="55" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#4A9EFF">User Input</text>
<!-- BASIC Script -->
<rect x="180" y="30" width="100" height="40" fill="none" stroke="#FF9F40" stroke-width="2" rx="5"/>
<text x="230" y="55" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#FF9F40">BASIC Script</text>
<!-- LLM Decision -->
<rect x="340" y="30" width="100" height="40" fill="none" stroke="#BA68C8" stroke-width="2" rx="5"/>
<text x="390" y="55" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#BA68C8">LLM Decision</text>
<!-- Tool Execution -->
<rect x="500" y="30" width="120" height="40" fill="none" stroke="#66BB6A" stroke-width="2" rx="5"/>
<text x="560" y="55" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#66BB6A">Tool Execution</text>
<!-- Save to CSV -->
<rect x="500" y="100" width="120" height="40" fill="none" stroke="#EC407A" stroke-width="2" rx="5"/>
<text x="560" y="125" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#EC407A">Save to CSV</text>
<!-- Search Knowledge -->
<rect x="320" y="100" width="140" height="40" fill="none" stroke="#26A69A" stroke-width="2" rx="5"/>
<text x="390" y="125" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#26A69A">Search Knowledge</text>
<!-- Bot Response -->
<rect x="160" y="160" width="120" height="40" fill="none" stroke="#5C6BC0" stroke-width="2" rx="5"/>
<text x="220" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#5C6BC0">Bot Response</text>
</g>
<!-- Arrows -->
<g id="arrows" stroke="#888" stroke-width="2" fill="none">
<!-- Horizontal flow -->
<line x1="120" y1="50" x2="180" y2="50" marker-end="url(#arrow)"/>
<line x1="280" y1="50" x2="340" y2="50" marker-end="url(#arrow)"/>
<line x1="440" y1="50" x2="500" y2="50" marker-end="url(#arrow)"/>
<!-- Vertical connections -->
<line x1="230" y1="70" x2="230" y2="90" stroke-dasharray="3,3" opacity="0.6"/>
<line x1="390" y1="70" x2="390" y2="100" marker-end="url(#arrow)"/>
<line x1="560" y1="70" x2="560" y2="100" marker-end="url(#arrow)"/>
<!-- Feedback lines -->
<line x1="230" y1="90" x2="220" y2="160" marker-end="url(#arrow)"/>
<line x1="390" y1="140" x2="240" y2="160" marker-end="url(#arrow)"/>
<line x1="500" y1="120" x2="280" y2="170" marker-end="url(#arrow)"/>
<!-- User to Bot Response -->
<path d="M 70 70 Q 70 180 160 180" stroke-dasharray="3,3" marker-end="url(#arrow)" opacity="0.6"/>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 3 KiB

95
docs/src/assets/package-system-flow.svg Normal file
View file

@ -0,0 +1,95 @@
<svg width="800" height="500" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
<marker id="arrow-double" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#999"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Package System Flow</text>
<!-- User Request -->
<rect x="50" y="60" width="120" height="50" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="110" y="90" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#90CDF4">User Request</text>
<!-- Bot Response -->
<rect x="630" y="60" width="120" height="50" fill="none" stroke="#68D391" stroke-width="2" rx="8"/>
<text x="690" y="90" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#9AE6B4">Bot Response</text>
<!-- start.bas Box -->
<rect x="50" y="180" width="180" height="140" fill="none" stroke="#F6AD55" stroke-width="2" rx="8"/>
<rect x="50" y="180" width="180" height="35" fill="none" stroke="#F6AD55" stroke-width="2" rx="8 8 0 0"/>
<text x="140" y="203" text-anchor="middle" font-family="monospace" font-size="14" font-weight="bold" fill="#FBD38D">start.bas</text>
<!-- BASIC Commands -->
<text x="60" y="240" font-family="monospace" font-size="12" fill="#A0AEC0">USE KB "docs"</text>
<text x="60" y="260" font-family="monospace" font-size="12" fill="#A0AEC0">answer=HEAR</text>
<text x="60" y="280" font-family="monospace" font-size="12" fill="#A0AEC0">result=LLM()</text>
<text x="60" y="300" font-family="monospace" font-size="12" fill="#A0AEC0">TALK result</text>
<!-- LLM Engine Box -->
<rect x="350" y="180" width="180" height="140" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
<rect x="350" y="180" width="180" height="35" fill="none" stroke="#B794F4" stroke-width="2" rx="8 8 0 0"/>
<text x="440" y="203" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">LLM Engine</text>
<text x="440" y="250" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" fill="#D6BCFA">(GPT/Local)</text>
<text x="440" y="280" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#A0AEC0">Processes requests</text>
<text x="440" y="300" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#A0AEC0">Makes decisions</text>
<!-- Vector Search Box -->
<rect x="300" y="370" width="200" height="100" fill="none" stroke="#4FD1C5" stroke-width="2" rx="8"/>
<rect x="300" y="370" width="200" height="35" fill="none" stroke="#4FD1C5" stroke-width="2" rx="8 8 0 0"/>
<text x="400" y="393" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#81E6D9">Vector Search</text>
<text x="400" y="430" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" fill="#81E6D9">(.gbkb docs)</text>
<text x="400" y="450" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#A0AEC0">Semantic search</text>
<!-- Arrows -->
<g stroke="#888" stroke-width="2" fill="none">
<!-- User to start.bas -->
<line x1="170" y1="85" x2="140" y2="180" marker-end="url(#arrow)"/>
<!-- start.bas to LLM (bidirectional) -->
<line x1="230" y1="200" x2="350" y2="200" marker-end="url(#arrow)"/>
<line x1="350" y1="220" x2="230" y2="220" marker-end="url(#arrow)" stroke="#999"/>
<line x1="230" y1="280" x2="350" y2="280" marker-end="url(#arrow)"/>
<line x1="350" y1="300" x2="230" y2="300" marker-end="url(#arrow)" stroke="#999"/>
<!-- LLM to Vector Search -->
<line x1="440" y1="320" x2="400" y2="370" marker-end="url(#arrow)"/>
<!-- Vector Search back to LLM -->
<path d="M 400 370 Q 340 340 380 320" stroke="#999" stroke-dasharray="5,5" marker-end="url(#arrow-double)" opacity="0.7"/>
<!-- Bot Response arrow -->
<path d="M 530 250 Q 600 150 630 85" marker-end="url(#arrow)"/>
<!-- start.bas to Bot Response -->
<path d="M 140 180 Q 140 85 630 85" stroke="#999" stroke-dasharray="5,5" marker-end="url(#arrow-double)" opacity="0.7"/>
</g>
<!-- Labels on arrows -->
<text x="290" y="195" font-family="Arial, sans-serif" font-size="11" fill="#718096">Commands</text>
<text x="290" y="235" font-family="Arial, sans-serif" font-size="11" fill="#718096">Results</text>
<text x="420" y="345" font-family="Arial, sans-serif" font-size="11" fill="#718096">Query</text>
<text x="320" y="345" font-family="Arial, sans-serif" font-size="11" fill="#718096">Context</text>
<!-- Legend -->
<g id="legend" transform="translate(600, 380)">
<rect x="0" y="0" width="180" height="100" fill="none" stroke="#4A5568" stroke-width="1" rx="5" opacity="0.5"/>
<text x="90" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#CBD5E0">Flow Legend</text>
<line x1="10" y1="40" x2="40" y2="40" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<text x="50" y="45" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Direct flow</text>
<line x1="10" y1="60" x2="40" y2="60" stroke="#999" stroke-width="2" stroke-dasharray="5,5" marker-end="url(#arrow-double)" opacity="0.7"/>
<text x="50" y="65" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Feedback/Return</text>
<line x1="10" y1="80" x2="40" y2="80" stroke="#888" stroke-width="2"/>
<line x1="40" y1="80" x2="10" y2="80" stroke="#999" stroke-width="2"/>
<text x="50" y="85" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Bidirectional</text>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 5.8 KiB

254
docs/src/chapter-01/README.md
View file

@ -1,169 +1,179 @@
# Chapter 01: Run and Talk
Getting started with BotServer is incredibly simple: **just run it!**
**Zero to chatbot in 60 seconds.** This chapter gets BotServer running with a working bot you can talk to immediately.
## Quick Start
## The One-Command Install
```bash
# Download and run
./botserver
# Or build from source
cargo run
```
That's it! The bootstrap process handles everything automatically.
That's literally it. First run triggers auto-bootstrap that:
- Installs PostgreSQL, cache, storage, vector DB
- Downloads AI models
- Creates default bot
- Starts web server
## What You'll Learn
Takes 2-5 minutes. Grab coffee. Come back to a running bot.
This chapter covers everything you need to get started:
## Your First Chat
1. **[Installation](./installation.md)** - How the automatic bootstrap works
2. **[First Conversation](./first-conversation.md)** - Start chatting with your bot
3. **[Quick Start](./quick-start.md)** - Create your first bot
Once bootstrap finishes:
## The Bootstrap Magic
1. Open browser to `http://localhost:8080`
2. Write a simple tool (see below)
3. Bot responds using GPT-3.5 (or local model)
When you first run BotServer, it automatically:
No configuration. No API keys (for local). It just works.
- ✅ Detects your operating system
- ✅ Downloads and installs PostgreSQL database
- ✅ Downloads and installs drive (S3-compatible object storage)
- ✅ Downloads and installs Valkey cache
- ✅ Downloads LLM models to botserver-stack/
- ✅ Generates secure credentials
- ✅ Creates default bots
- ✅ Starts the web server
## What's Actually Happening
**No manual configuration needed!** Everything just works.
Behind that simple `./botserver` command:
### Optional Components
```
Installing PostgreSQL 16.2... ✓
Installing Valkey cache... ✓
Installing SeaweedFS storage... ✓
Installing Qdrant vectors... ✓
Downloading embeddings... ✓
Creating database schema... ✓
Generating secure credentials... ✓
Loading bot templates... ✓
Starting web server on :8080 ✓
```
After bootstrap, you can install additional services:
Everything lands in `botserver-stack/` directory. Fully self-contained.
- **Stalwart** - Full-featured email server for sending/receiving
- **Zitadel** - Identity and access management (directory service)
- **LiveKit** - Real-time video/audio conferencing
- **Additional LLM models** - For offline operation
## Make Your Own Bot in 2 Minutes
### Step 1: Create Package
```bash
mkdir templates/my-bot.gbai
mkdir templates/my-bot.gbai/my-bot.gbdialog
```
### Step 2: Write Start Script
```bash
cat > templates/my-bot.gbai/my-bot.gbdialog/start.bas << 'EOF'
TALK "Hi! I'm your personal assistant."
TALK "What can I help you with?"
answer = HEAR
TALK "I can help you with: " + answer
EOF
```
### Step 3: Restart & Test
```bash
./botserver restart
# Visit http://localhost:8080/my-bot
```
Your bot is live.
## Adding Intelligence
### Give It Knowledge
Drop PDFs into knowledge base:
```bash
mkdir templates/my-bot.gbai/my-bot.gbkb
cp ~/Documents/policies.pdf templates/my-bot.gbai/my-bot.gbkb/
```
Bot instantly answers questions from your documents.
### Give It Tools
Create a tool for booking meetings:
```bash
cat > templates/my-bot.gbai/my-bot.gbdialog/book-meeting.bas << 'EOF'
PARAM person, date, time
DESCRIPTION "Books a meeting"
SAVE "meetings.csv", person, date, time
TALK "Meeting booked with " + person + " on " + date
EOF
```
Now just say "Book a meeting with John tomorrow at 2pm" - AI handles the rest.
## Optional Components
Want email? Video calls? Better models?
```bash
./botserver install email # Stalwart email server
./botserver install directory # Zitadel identity provider
./botserver install meeting # LiveKit conferencing
./botserver install llm # Local LLM models
./botserver install email # Full email server
./botserver install meeting # Video conferencing
./botserver install llm # Local AI models
```
## Your First Bot
Each adds specific functionality. None required to start.
After bootstrap completes (2-5 minutes), open your browser to:
## File Structure After Bootstrap
```
http://localhost:8080
botserver-stack/
postgres/ # Database files
valkey/ # Cache data
seaweedfs/ # Object storage
qdrant/ # Vector database
models/ # Embeddings
templates/
default.gbai/ # Default bot
my-bot.gbai/ # Your bot
.env # Auto-generated config
```
You'll see the default bot ready to chat! Just start talking - the LLM handles everything.
## Troubleshooting Quick Fixes
For specific bots like the enrollment example below:
```
http://localhost:8080/edu
**Port already in use?**
```bash
HTTP_PORT=3000 ./botserver
```
## The Magic Formula
```
📚 Documents (.gbkb/) + 🔧 Tools (.bas) + 🤖 LLM = ✨ Intelligent Bot
**Bootstrap fails?**
```bash
./botserver cleanup
./botserver # Try again
```
**No programming required!** Just:
1. Drop documents in `.gbkb/` folders
2. Create simple tools as `.bas` files (optional)
3. Start chatting - the LLM does the rest!
## Example: Student Enrollment Bot (EDU)
Deploy a new bot by creating a bucket in the object storage drive. Access it at `/edu`:
### 1. Add Course Documents
```
edu.gbai/
edu.gbkb/
policies/
enrollment-policy.pdf
course-catalog.pdf
**Want fresh start?**
```bash
rm -rf botserver-stack .env
./botserver
```
### 2. Create Enrollment Tool
Deploy a bot by creating a new bucket in the drive. Tools are `.bas` files:
`edu.gbdialog/enrollment.bas`:
```bas
PARAM name AS string LIKE "John Smith" DESCRIPTION "Student name"
PARAM email AS string LIKE "john@example.com" DESCRIPTION "Email"
PARAM course AS string LIKE "Computer Science" DESCRIPTION "Course"
DESCRIPTION "Processes student enrollment"
SAVE "enrollments.csv", name, email, course, NOW()
TALK "Welcome to " + course + ", " + name + "!"
**Check what's running:**
```bash
./botserver status
```
### 3. Just Chat!
## Container Deployment
```
User: I want to enroll in computer science
Bot: I'll help you enroll! What's your name?
User: John Smith
Bot: Thanks John! What's your email?
User: john@example.com
Bot: [Executes enrollment.bas]
Welcome to Computer Science, John Smith!
Prefer containers? Use LXC mode:
```bash
./botserver --container
```
The LLM automatically:
- ✅ Understands user wants to enroll
- ✅ Calls the enrollment tool
- ✅ Collects required parameters
- ✅ Executes when ready
- ✅ Answers questions from your documents
Creates isolated LXC containers for each component. Same auto-bootstrap, better isolation.
## Key Concepts
## What You've Learned
### Tools = Just `.bas` Files
A **tool** is simply a `.bas` file that the LLM discovers and calls automatically.
### Knowledge = Just Documents
Drop PDFs, Word docs, or text files in `.gbkb/` - instant searchable knowledge base!
### Sessions
Each conversation is a **session** that persists:
- User identity (authenticated or anonymous)
- Conversation history
- Context and variables
- Active tools and knowledge bases
Sessions automatically save to PostgreSQL and cache in Valkey for performance.
✅ BotServer installs itself completely
✅ Default bot works immediately
✅ Create new bots in minutes
✅ Add documents for instant knowledge
✅ Write tools for custom actions
## Next Steps
- **[Installation](./installation.md)** - Understand the bootstrap process
- **[First Conversation](./first-conversation.md)** - Try out your bot
- **[Quick Start](./quick-start.md)** - Build your own bot
- **[About Packages](../chapter-02/README.md)** - Create bot packages
- **[Quick Start](./quick-start.md)** - Build a real bot
- **[Installation Details](./installation.md)** - How bootstrap works
- **[First Conversation](./first-conversation.md)** - Chat interface tour
- **[Sessions](./sessions.md)** - How conversations persist
## Philosophy
## The Philosophy
BotServer follows these principles:
We believe setup should be invisible. You want a bot, not a DevOps degree. That's why everything auto-configures. Focus on your bot's personality and knowledge, not infrastructure.
1. **Just Run It** - Bootstrap handles everything
2. **Just Chat** - No complex dialog flows needed
3. **Just Add Content** - Documents + tools = intelligent bot
4. **LLM Does the Work** - No IF/THEN logic required
5. **Production Ready** - Built for real-world use
Ready to get started? Head to [Installation](./installation.md)!
Ready for more? Continue to [Quick Start](./quick-start.md) to build something real.

98
docs/src/chapter-01/assets/bootstrap-process.svg Normal file
View file

@ -0,0 +1,98 @@
<svg width="800" height="700" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Auto-Bootstrap Process</text>
<!-- Start: ./botserver (First Run) -->
<rect x="325" y="50" width="150" height="40" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="400" y="75" text-anchor="middle" font-family="monospace" font-size="14" fill="#90CDF4">./botserver</text>
<!-- Arrow down -->
<line x1="400" y1="90" x2="400" y2="120" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Detect System -->
<rect x="300" y="120" width="200" height="60" fill="none" stroke="#F6AD55" stroke-width="2" rx="8"/>
<text x="400" y="145" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBD38D">Detect System</text>
<text x="400" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#CBD5E0">(Linux/Mac)</text>
<!-- Arrow down -->
<line x1="400" y1="180" x2="400" y2="210" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Main Process Container -->
<rect x="50" y="210" width="700" height="280" fill="none" stroke="#4A5568" stroke-width="2" rx="10" stroke-dasharray="5,5" opacity="0.6"/>
<text x="400" y="235" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#A0AEC0">Auto-Bootstrap Process</text>
<!-- Component Grid -->
<g id="components">
<!-- PostgreSQL -->
<rect x="100" y="260" width="140" height="100" fill="none" stroke="#4A90E2" stroke-width="2" rx="8"/>
<text x="170" y="285" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#63B3ED">PostgreSQL</text>
<text x="170" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#90CDF4">16.2</text>
<text x="170" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Install</text>
<text x="170" y="340" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Configure</text>
<text x="170" y="355" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Migrate</text>
<!-- Valkey -->
<rect x="260" y="260" width="140" height="100" fill="none" stroke="#E53E3E" stroke-width="2" rx="8"/>
<text x="330" y="285" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">Valkey</text>
<text x="330" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FEB2B2">Cache</text>
<text x="330" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Install</text>
<text x="330" y="340" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Configure</text>
<text x="330" y="355" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Start</text>
<!-- SeaweedFS -->
<rect x="420" y="260" width="140" height="100" fill="none" stroke="#38A169" stroke-width="2" rx="8"/>
<text x="490" y="285" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#48BB78">SeaweedFS</text>
<text x="490" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#68D391">Storage</text>
<text x="490" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Install</text>
<text x="490" y="340" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Configure</text>
<text x="490" y="355" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Start</text>
<!-- Qdrant -->
<rect x="580" y="260" width="140" height="100" fill="none" stroke="#38D4B2" stroke-width="2" rx="8"/>
<text x="650" y="285" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#4FD1C5">Qdrant</text>
<text x="650" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#81E6D9">Vectors</text>
<text x="650" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Install</text>
<text x="650" y="340" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Configure</text>
<text x="650" y="355" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Start</text>
</g>
<!-- LLM Models -->
<rect x="150" y="380" width="500" height="80" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
<text x="400" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">LLM Models (Optional)</text>
<text x="400" y="430" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Download BGE embeddings</text>
<text x="400" y="445" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">✓ Download Llama model (if local)</text>
<!-- Arrow down -->
<line x1="400" y1="490" x2="400" y2="520" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Generate .env file -->
<rect x="275" y="520" width="250" height="80" fill="none" stroke="#ED8936" stroke-width="2" rx="8"/>
<text x="400" y="545" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#F6AD55">Generate .env file</text>
<text x="400" y="565" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#CBD5E0">• Secure passwords</text>
<text x="400" y="580" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#CBD5E0">• Connection URLs</text>
<text x="400" y="595" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#CBD5E0">• Port assignments</text>
<!-- Arrow down -->
<line x1="400" y1="600" x2="400" y2="630" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Load Templates -->
<rect x="275" y="630" width="250" height="80" fill="none" stroke="#9F7AEA" stroke-width="2" rx="8"/>
<text x="400" y="655" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#B794F4">Load Templates</text>
<text x="400" y="675" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#CBD5E0">• Scan .gbai dirs</text>
<text x="400" y="690" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#CBD5E0">• Create bots</text>
<text x="400" y="705" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#CBD5E0">• Index documents</text>
<!-- Arrow down -->
<line x1="400" y1="710" x2="400" y2="740" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Start Web Server -->
<rect x="275" y="740" width="250" height="60" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
<text x="400" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">Start Web Server</text>
<text x="400" y="785" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#9AE6B4">localhost:8080</text>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 7.4 KiB

111
docs/src/chapter-01/assets/quick-start-bootstrap.svg Normal file
View file

@ -0,0 +1,111 @@
<svg width="900" height="900" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="450" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Bootstrap Flow</text>
<!-- Start -->
<rect x="350" y="60" width="200" height="50" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="450" y="85" text-anchor="middle" font-family="monospace" font-size="14" fill="#90CDF4">./botserver</text>
<text x="450" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#CBD5E0">(first run)</text>
<!-- Arrow -->
<line x1="450" y1="110" x2="450" y2="140" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- OS Detection -->
<rect x="325" y="140" width="250" height="70" fill="none" stroke="#F6AD55" stroke-width="2" rx="8"/>
<text x="450" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBD38D">OS Detection</text>
<text x="450" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FED7AA">Linux/Mac/Windows</text>
<!-- Arrow -->
<line x1="450" y1="210" x2="450" y2="240" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Component Installation Box -->
<rect x="100" y="240" width="700" height="180" fill="none" stroke="#4A5568" stroke-width="2" rx="10" stroke-dasharray="5,5" opacity="0.6"/>
<text x="450" y="265" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#A0AEC0">Component Installation</text>
<!-- Component Grid -->
<g id="components">
<!-- PostgreSQL -->
<rect x="150" y="290" width="150" height="80" fill="none" stroke="#4A90E2" stroke-width="2" rx="6"/>
<text x="225" y="315" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#63B3ED">PostgreSQL</text>
<text x="225" y="335" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#90CDF4">16.2</text>
<!-- Valkey -->
<rect x="325" y="290" width="150" height="80" fill="none" stroke="#E53E3E" stroke-width="2" rx="6"/>
<text x="400" y="315" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#FC8181">Valkey</text>
<text x="400" y="335" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FEB2B2">Cache</text>
<!-- SeaweedFS -->
<rect x="500" y="290" width="150" height="80" fill="none" stroke="#38A169" stroke-width="2" rx="6"/>
<text x="575" y="315" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#48BB78">SeaweedFS</text>
<text x="575" y="335" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">Storage</text>
<!-- Qdrant -->
<rect x="675" y="290" width="125" height="80" fill="none" stroke="#38D4B2" stroke-width="2" rx="6"/>
<text x="737" y="315" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#4FD1C5">Qdrant</text>
<text x="737" y="335" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#81E6D9">Vectors</text>
</g>
<!-- Connection lines -->
<g stroke="#888" stroke-width="1" fill="none" opacity="0.5">
<line x1="225" y1="370" x2="225" y2="390"/>
<line x1="400" y1="370" x2="400" y2="390"/>
<line x1="575" y1="370" x2="575" y2="390"/>
<line x1="737" y1="370" x2="737" y2="390"/>
<line x1="225" y1="390" x2="737" y2="390"/>
<line x1="450" y1="390" x2="450" y2="450"/>
</g>
<!-- Arrow -->
<line x1="450" y1="420" x2="450" y2="450" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Configuration & Setup -->
<rect x="200" y="450" width="500" height="120" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
<text x="450" y="475" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">Configuration &amp; Setup</text>
<g font-family="Arial, sans-serif" font-size="12" fill="#E9D8FD">
<text x="250" y="505">• Generate credentials</text>
<text x="250" y="525">• Create .env file</text>
<text x="480" y="505">• Initialize databases</text>
<text x="480" y="525">• Create storage buckets</text>
</g>
<!-- Arrow -->
<line x1="450" y1="570" x2="450" y2="600" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Bot Deployment Box -->
<rect x="150" y="600" width="600" height="200" fill="none" stroke="#4A5568" stroke-width="2" rx="10" stroke-dasharray="5,5" opacity="0.6"/>
<text x="450" y="625" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#A0AEC0">Bot Deployment</text>
<!-- Deployment Steps -->
<rect x="200" y="650" width="500" height="40" fill="none" stroke="#FBBF24" stroke-width="1" rx="6"/>
<text x="450" y="675" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FCD34D">Scan templates/ directory</text>
<!-- Arrow down -->
<line x1="450" y1="690" x2="450" y2="710" stroke="#888" stroke-width="1" marker-end="url(#arrow)" opacity="0.7"/>
<rect x="200" y="710" width="500" height="60" fill="none" stroke="#68D391" stroke-width="1" rx="6"/>
<text x="450" y="735" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#9AE6B4">Load .gbai packages</text>
<text x="350" y="755" font-family="monospace" font-size="11" fill="#A0AEC0">• default.gbai</text>
<text x="500" y="755" font-family="monospace" font-size="11" fill="#A0AEC0">• announcements.gbai</text>
<!-- Arrow down -->
<line x1="450" y1="770" x2="450" y2="790" stroke="#888" stroke-width="1" marker-end="url(#arrow)" opacity="0.7"/>
<rect x="200" y="790" width="500" height="60" fill="none" stroke="#81E6D9" stroke-width="1" rx="6"/>
<text x="450" y="815" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#B2F5EA">Upload to object storage</text>
<text x="450" y="835" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#B2F5EA">Index documents • Register in database</text>
<!-- Arrow -->
<line x1="450" y1="850" x2="450" y2="880" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Start Web Server -->
<rect x="275" y="880" width="350" height="70" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
<text x="450" y="905" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">Start Web Server</text>
<text x="450" y="925" text-anchor="middle" font-family="monospace" font-size="12" fill="#9AE6B4">http://localhost:8080</text>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 6.7 KiB

103
docs/src/chapter-01/assets/session-manager.svg Normal file
View file

@ -0,0 +1,103 @@
<svg width="800" height="500" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
<marker id="arrow-double" markerWidth="10" markerHeight="10" refX="5" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L5,3 z" fill="#999"/>
<path d="M5,0 L5,6 L10,3 z" fill="#999"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Session Manager Architecture</text>
<!-- User Input -->
<rect x="50" y="60" width="150" height="50" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="125" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#90CDF4">User Input</text>
<!-- Bot Response -->
<rect x="600" y="60" width="150" height="50" fill="none" stroke="#68D391" stroke-width="2" rx="8"/>
<text x="675" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#9AE6B4">Bot Response</text>
<!-- Arrows down from User Input and up to Bot Response -->
<line x1="125" y1="110" x2="125" y2="150" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<line x1="675" y1="150" x2="675" y2="110" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- WebSocket/HTTP boxes -->
<rect x="50" y="150" width="150" height="60" fill="none" stroke="#F6AD55" stroke-width="2" rx="6"/>
<text x="125" y="175" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#FBD38D">WebSocket</text>
<text x="125" y="195" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FED7AA">/HTTP</text>
<rect x="600" y="150" width="150" height="60" fill="none" stroke="#F6AD55" stroke-width="2" rx="6"/>
<text x="675" y="175" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" font-weight="bold" fill="#FBD38D">WebSocket</text>
<text x="675" y="195" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FED7AA">/HTTP</text>
<!-- Arrows to/from Session Manager -->
<line x1="125" y1="210" x2="125" y2="250" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<line x1="675" y1="250" x2="675" y2="210" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Session Manager Box -->
<rect x="100" y="250" width="600" height="130" fill="none" stroke="#B794F4" stroke-width="3" rx="10"/>
<text x="400" y="280" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#D6BCFA">Session Manager</text>
<!-- Session Manager Steps -->
<g font-family="Arial, sans-serif" font-size="12" fill="#E9D8FD">
<text x="150" y="310">1. Validate Token</text>
<text x="150" y="330">2. Load Session</text>
<text x="150" y="350">3. Update State</text>
<text x="450" y="310">4. Execute BASIC</text>
<text x="450" y="330">5. Generate Response</text>
<text x="450" y="350">6. Save History</text>
</g>
<!-- Arrows down to databases -->
<line x1="250" y1="380" x2="250" y2="420" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<line x1="550" y1="380" x2="550" y2="420" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Database boxes -->
<rect x="150" y="420" width="200" height="80" fill="none" stroke="#E53E3E" stroke-width="2" rx="8"/>
<text x="250" y="450" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">Valkey</text>
<text x="250" y="470" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FEB2B2">(Cache)</text>
<rect x="450" y="420" width="200" height="80" fill="none" stroke="#4A90E2" stroke-width="2" rx="8"/>
<text x="550" y="450" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#63B3ED">PostgreSQL</text>
<text x="550" y="470" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#90CDF4">(Persist)</text>
<!-- Sync arrow between databases -->
<path d="M 350 460 L 450 460" stroke="#888" stroke-width="2" marker-end="url(#arrow-double)" stroke-dasharray="5,5" opacity="0.7"/>
<text x="400" y="455" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Sync Every</text>
<text x="400" y="475" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Message</text>
<!-- Process Flow Numbers -->
<g font-family="Arial, sans-serif" font-size="10" fill="#718096">
<circle cx="125" cy="130" r="12" fill="none" stroke="#718096" stroke-width="1"/>
<text x="125" y="134" text-anchor="middle">1</text>
<circle cx="125" cy="230" r="12" fill="none" stroke="#718096" stroke-width="1"/>
<text x="125" y="234" text-anchor="middle">2</text>
<circle cx="400" cy="315" r="12" fill="none" stroke="#718096" stroke-width="1"/>
<text x="400" y="319" text-anchor="middle">3</text>
<circle cx="675" cy="230" r="12" fill="none" stroke="#718096" stroke-width="1"/>
<text x="675" y="234" text-anchor="middle">4</text>
<circle cx="675" cy="130" r="12" fill="none" stroke="#718096" stroke-width="1"/>
<text x="675" y="134" text-anchor="middle">5</text>
</g>
<!-- Features box -->
<g id="features" transform="translate(50, 520)">
<rect x="0" y="0" width="700" height="60" fill="none" stroke="#4A5568" stroke-width="1" rx="5" stroke-dasharray="2,2" opacity="0.5"/>
<text x="350" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#CBD5E0">Key Features</text>
<g font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">
<text x="50" y="45">• Real-time WebSocket support</text>
<text x="250" y="45">• Automatic session persistence</text>
<text x="450" y="45">• Redis-compatible caching</text>
<text x="600" y="45">• ACID compliance</text>
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 6 KiB

79
docs/src/chapter-01/assets/session-states.svg Normal file
View file

@ -0,0 +1,79 @@
<svg width="600" height="800" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="300" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Session State Flow</text>
<!-- Browser Opens -->
<rect x="200" y="60" width="200" height="50" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="300" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#90CDF4">Browser</text>
<text x="300" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#CBD5E0">Opens</text>
<!-- Arrow down -->
<line x1="300" y1="110" x2="300" y2="150" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- CREATE State -->
<rect x="200" y="150" width="200" height="80" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
<text x="300" y="175" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">CREATE</text>
<text x="300" y="195" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#9AE6B4">New UUID</text>
<text x="300" y="210" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#9AE6B4">Token Gen</text>
<!-- Arrow down -->
<line x1="300" y1="230" x2="300" y2="270" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- ACTIVE State -->
<rect x="200" y="270" width="200" height="80" fill="none" stroke="#4299E1" stroke-width="2" rx="8"/>
<text x="300" y="295" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#63B3ED">ACTIVE</text>
<text x="300" y="315" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#90CDF4">Chatting</text>
<text x="300" y="330" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#90CDF4">Messages</text>
<!-- Arrow down -->
<line x1="300" y1="350" x2="300" y2="390" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- IDLE State -->
<rect x="200" y="390" width="200" height="80" fill="none" stroke="#F6AD55" stroke-width="2" rx="8"/>
<text x="300" y="415" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBD38D">IDLE</text>
<text x="300" y="435" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FED7AA">No Input</text>
<text x="300" y="450" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FED7AA">30min Timer</text>
<!-- User Returns Loop -->
<path d="M 400 430 Q 480 360 480 310 Q 480 260 400 310"
stroke="#888" stroke-width="2" fill="none" marker-end="url(#arrow)" stroke-dasharray="5,5" opacity="0.7"/>
<text x="490" y="360" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">User Returns</text>
<!-- Arrow down -->
<line x1="300" y1="470" x2="300" y2="510" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- EXPIRE State -->
<rect x="200" y="510" width="200" height="80" fill="none" stroke="#FC8181" stroke-width="2" rx="8"/>
<text x="300" y="535" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">EXPIRE</text>
<text x="300" y="555" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FEB2B2">7d Anon</text>
<text x="300" y="570" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FEB2B2">Never Auth</text>
<!-- Retry Loop -->
<path d="M 200 550 Q 120 400 120 200 Q 120 150 200 190"
stroke="#888" stroke-width="2" fill="none" marker-end="url(#arrow)" stroke-dasharray="5,5" opacity="0.7"/>
<text x="90" y="360" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Retry</text>
<!-- Arrow down -->
<line x1="300" y1="590" x2="300" y2="630" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- CLEANUP State -->
<rect x="200" y="630" width="200" height="80" fill="none" stroke="#718096" stroke-width="2" rx="8"/>
<text x="300" y="655" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#A0AEC0">CLEANUP</text>
<text x="300" y="675" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#CBD5E0">Archive</text>
<text x="300" y="690" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#CBD5E0">Delete</text>
<!-- State Duration Labels -->
<g id="durations" font-family="Arial, sans-serif" font-size="10" fill="#718096">
<text x="420" y="195" text-anchor="start">Instant</text>
<text x="420" y="315" text-anchor="start">Active use</text>
<text x="420" y="435" text-anchor="start">30 minutes</text>
<text x="420" y="555" text-anchor="start">7 days / Never</text>
<text x="420" y="675" text-anchor="start">Permanent</text>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 5 KiB

105
docs/src/chapter-01/assets/tool-execution-flow.svg Normal file
View file

@ -0,0 +1,105 @@
<svg width="700" height="800" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="350" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Tool Execution Flow</text>
<!-- User Input -->
<rect x="200" y="60" width="300" height="50" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="350" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" fill="#90CDF4">User: "I want to enroll in</text>
<text x="350" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" fill="#90CDF4">Computer Science"</text>
<!-- Arrow down -->
<line x1="350" y1="110" x2="350" y2="140" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- LLM Analyzes -->
<rect x="225" y="140" width="250" height="80" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
<text x="350" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">LLM Analyzes</text>
<text x="350" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#E9D8FD">"enrollment need"</text>
<text x="350" y="200" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Intent detection</text>
<!-- Arrow down -->
<line x1="350" y1="220" x2="350" y2="250" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Scan Available Tools -->
<rect x="175" y="250" width="350" height="100" fill="none" stroke="#F6AD55" stroke-width="2" rx="8"/>
<text x="350" y="275" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBD38D">Scan Available Tools</text>
<g font-family="monospace" font-size="12">
<text x="220" y="305" fill="#68D391">• enrollment.bas ✓</text>
<text x="220" y="325" fill="#A0AEC0">• other-tools.bas</text>
</g>
<!-- Arrow down -->
<line x1="350" y1="350" x2="350" y2="380" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Collect Parameters -->
<rect x="175" y="380" width="350" height="120" fill="none" stroke="#4FD1C5" stroke-width="2" rx="8"/>
<text x="350" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#81E6D9">Collect Parameters</text>
<g font-family="Arial, sans-serif" font-size="12" fill="#B2F5EA">
<text x="220" y="435">• name: (ask user)</text>
<text x="220" y="455">• email: (ask user)</text>
<text x="220" y="475">• course: "Comp Sci"</text>
</g>
<!-- Arrow down -->
<line x1="350" y1="500" x2="350" y2="530" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Execute enrollment.bas -->
<rect x="175" y="530" width="350" height="100" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
<text x="350" y="555" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">Execute enrollment.bas</text>
<g font-family="Arial, sans-serif" font-size="12" fill="#9AE6B4">
<text x="220" y="585">• Save to CSV</text>
<text x="220" y="605">• Return confirmation</text>
</g>
<!-- Arrow down -->
<line x1="350" y1="630" x2="350" y2="660" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Bot Response -->
<rect x="175" y="660" width="350" height="60" fill="none" stroke="#68D391" stroke-width="2" rx="8"/>
<text x="350" y="685" text-anchor="middle" font-family="Arial, sans-serif" font-size="13" fill="#9AE6B4">"Welcome to Computer Science!"</text>
<text x="350" y="705" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">Confirmation sent to user</text>
<!-- Side annotations -->
<g font-family="Arial, sans-serif" font-size="10" fill="#718096">
<!-- Time indicators -->
<text x="50" y="180" text-anchor="end">~100ms</text>
<text x="50" y="300" text-anchor="end">~50ms</text>
<text x="50" y="440" text-anchor="end">Interactive</text>
<text x="50" y="580" text-anchor="end">~200ms</text>
<text x="50" y="690" text-anchor="end">Instant</text>
<!-- Process descriptions -->
<text x="550" y="180">Natural language</text>
<text x="550" y="200">understanding</text>
<text x="550" y="300">Tool discovery</text>
<text x="550" y="320">and matching</text>
<text x="550" y="440">Smart parameter</text>
<text x="550" y="460">extraction</text>
<text x="550" y="580">BASIC script</text>
<text x="550" y="600">execution</text>
</g>
<!-- Tool example box -->
<g id="tool-example" transform="translate(50, 740)">
<rect x="0" y="0" width="600" height="120" fill="none" stroke="#4A5568" stroke-width="1" rx="5" stroke-dasharray="2,2" opacity="0.5"/>
<text x="300" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#CBD5E0">enrollment.bas</text>
<g font-family="monospace" font-size="11" fill="#A0AEC0">
<text x="20" y="45">' Student enrollment tool</text>
<text x="20" y="65">PARAM name, email, course</text>
<text x="20" y="85">SAVE "enrollments.csv", name, email, course, NOW()</text>
<text x="20" y="105">TALK "Welcome to " + course + ", " + name + "!"</text>
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 5.3 KiB

9
docs/src/chapter-01/installation.md
View file

@ -1,6 +1,10 @@
# Installation
This guide covers the installation and setup of BotServer on various platforms.
BotServer installs itself automatically through the bootstrap process. No manual setup required - just run the binary and everything gets configured.
## Bootstrap Flow Diagram
![Auto-Bootstrap Process](./assets/bootstrap-process.svg)
## System Requirements
@ -24,9 +28,6 @@ BotServer handles all dependencies automatically:
```bash
# Download and run
./botserver
# Or build from source
cargo run
```
The bootstrap process automatically downloads everything to `botserver-stack/`:

288
docs/src/chapter-01/nvidia-gpu-setup.md
View file

@ -1,287 +1 @@
# NVIDIA GPU Setup for LXC Containers
This guide covers setting up NVIDIA GPU passthrough for BotServer running in LXC containers, enabling hardware acceleration for local LLM inference.
## Prerequisites
- NVIDIA GPU (RTX 3060 or better with 12GB+ VRAM recommended)
- NVIDIA drivers installed on the host system
- LXD/LXC installed
- CUDA-capable GPU
## LXD Configuration (Interactive Setup)
When initializing LXD, use these settings:
```bash
sudo lxd init
```
Answer the prompts as follows:
- **Would you like to use LXD clustering?** → `no`
- **Do you want to configure a new storage pool?** → `no` (will create `/generalbots` later)
- **Would you like to connect to a MAAS server?** → `no`
- **Would you like to create a new local network bridge?** → `yes`
- **What should the new bridge be called?** → `lxdbr0`
- **What IPv4 address should be used?** → `auto`
- **What IPv6 address should be used?** → `auto`
- **Would you like the LXD server to be available over the network?** → `no`
- **Would you like stale cached images to be updated automatically?** → `no`
- **Would you like a YAML "lxd init" preseed to be printed?** → `no`
### Storage Configuration
- **Storage backend name:** → `default`
- **Storage backend driver:** → `zfs`
- **Create a new ZFS pool?** → `yes`
## NVIDIA GPU Configuration
### On the Host System
Create a GPU profile and attach it to your container:
```bash
# Create GPU profile
lxc profile create gpu
# Add GPU device to profile
lxc profile device add gpu gpu gpu gputype=physical
# Apply GPU profile to your container
lxc profile add gb-system gpu
```
### Inside the Container
Configure NVIDIA driver version pinning and install drivers:
1. **Pin NVIDIA driver versions** to ensure stability:
```bash
cat > /etc/apt/preferences.d/nvidia-drivers << 'EOF'
Package: *nvidia*
Pin: version 560.35.05-1
Pin-Priority: 1001
Package: cuda-drivers*
Pin: version 560.35.05-1
Pin-Priority: 1001
Package: libcuda*
Pin: version 560.35.05-1
Pin-Priority: 1001
Package: libxnvctrl*
Pin: version 560.35.05-1
Pin-Priority: 1001
Package: libnv*
Pin: version 560.35.05-1
Pin-Priority: 1001
EOF
```
2. **Install NVIDIA drivers and CUDA toolkit:**
```bash
# Update package lists
apt update
# Install NVIDIA driver and nvidia-smi
apt install -y nvidia-driver nvidia-smi
# Add CUDA repository
wget https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/cuda-keyring_1.1-1_all.deb
dpkg -i cuda-keyring_1.1-1_all.deb
# Install CUDA toolkit
apt-get update
apt-get -y install cuda-toolkit-12-8
apt-get install -y cuda-drivers
```
## Verify GPU Access
After installation, verify GPU is accessible:
```bash
# Check GPU is visible
nvidia-smi
# Should show your GPU with driver version 560.35.05
```
## Configure BotServer for GPU
Update your bot's `config.csv` to use GPU acceleration:
```csv
name,value
llm-server-gpu-layers,35
```
The number of layers depends on your GPU memory:
- **RTX 3060 (12GB):** 20-35 layers
- **RTX 3070 (8GB):** 15-25 layers
- **RTX 4070 (12GB):** 30-40 layers
- **RTX 4090 (24GB):** 50-99 layers
## Troubleshooting
### GPU Not Detected
If `nvidia-smi` doesn't show the GPU:
1. Check host GPU drivers:
```bash
# On host
nvidia-smi
lxc config device list gb-system
```
2. Verify GPU passthrough:
```bash
# Inside container
ls -la /dev/nvidia*
```
3. Check kernel modules:
```bash
lsmod | grep nvidia
```
### Driver Version Mismatch
If you encounter driver version conflicts:
1. Ensure host and container use the same driver version
2. Remove the version pinning file and install matching drivers:
```bash
rm /etc/apt/preferences.d/nvidia-drivers
apt update
apt install nvidia-driver-560
```
### CUDA Library Issues
If CUDA libraries aren't found:
```bash
# Add CUDA to library path
echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf.d/cuda.conf
ldconfig
# Add to PATH
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
## Custom llama.cpp Compilation
If you need custom CPU/GPU optimizations or specific hardware support, compile llama.cpp from source:
### Prerequisites
```bash
sudo apt update
sudo apt install build-essential cmake git
```
### Compilation Steps
```bash
# Clone llama.cpp repository
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
# Create build directory
mkdir build
cd build
# Configure with CUDA support
cmake .. -DLLAMA_CUDA=ON -DLLAMA_CURL=OFF
# Compile using all available cores
make -j$(nproc)
```
### Compilation Options
For different hardware configurations:
```bash
# CPU-only build (no GPU)
cmake .. -DLLAMA_CURL=OFF
# CUDA with specific compute capability
cmake .. -DLLAMA_CUDA=ON -DLLAMA_CUDA_FORCE_COMPUTE=75
# ROCm for AMD GPUs
cmake .. -DLLAMA_HIPBLAS=ON
# Metal for Apple Silicon
cmake .. -DLLAMA_METAL=ON
# AVX2 optimizations for modern CPUs
cmake .. -DLLAMA_AVX2=ON
# F16C for half-precision support
cmake .. -DLLAMA_F16C=ON
```
### After Compilation
```bash
# Copy compiled binary to BotServer
cp bin/llama-server /path/to/botserver-stack/bin/llm/
# Update config.csv to use custom build
llm-server-path,/path/to/botserver-stack/bin/llm/
```
### Benefits of Custom Compilation
- **Hardware-specific optimizations** for your exact CPU/GPU
- **Custom CUDA compute capabilities** for newer GPUs
- **AVX/AVX2/AVX512** instructions for faster CPU inference
- **Reduced binary size** by excluding unused features
- **Support for experimental features** not in releases
## Performance Optimization
### Memory Settings
For optimal LLM performance with GPU:
```csv
name,value
llm-server-gpu-layers,35
llm-server-mlock,true
llm-server-no-mmap,false
llm-server-ctx-size,4096
```
### Multiple GPUs
For systems with multiple GPUs, specify which GPU to use:
```bash
# List available GPUs
lxc profile device add gpu gpu0 gpu gputype=physical id=0
lxc profile device add gpu gpu1 gpu gputype=physical id=1
```
## Benefits of GPU Acceleration
With GPU acceleration enabled:
- **5-10x faster** inference compared to CPU
- **Higher context sizes** possible (8K-32K tokens)
- **Real-time responses** even with large models
- **Lower CPU usage** for other tasks
- **Support for larger models** (13B, 30B parameters)
## Next Steps
- [Installation Guide](./installation.md) - Complete BotServer setup
- [Quick Start](./quick-start.md) - Create your first bot
- [Configuration Reference](../chapter-02/gbot.md) - All GPU-related parameters
# NVIDIA GPU Setup for LXC

18
docs/src/chapter-01/overview.md
View file

@ -100,15 +100,15 @@ Each bot is a self-contained `.gbai` folder:
```
mybot.gbai/
├── mybot.gbot/ # Configuration
│ └── config.csv
├── mybot.gbdialog/ # Conversation scripts
│ ├── start.bas
│ └── tools/
├── mybot.gbkb/ # Knowledge base
│ └── documents/
└── mybot.gbtheme/ # Optional UI customization
└── styles/
mybot.gbot/ # Configuration
config.csv
mybot.gbdialog/ # Conversation scripts
start.bas
tools/
mybot.gbkb/ # Knowledge base
documents/
mybot.gbtheme/ # Optional UI customization
styles/
```
## Deployment Models

51
docs/src/chapter-01/quick-start.md
View file

@ -1,4 +1,4 @@
# BotServer Quick Start
# Quick Start
## Installation in 3 Steps
@ -44,6 +44,10 @@ Start chatting with your bot!
## What Just Happened?
### Bootstrap Flow
![Bootstrap Flow](./assets/quick-start-bootstrap.svg)
The **automatic bootstrap** process:
1. ✅ Detected your OS (Linux/macOS/Windows)
@ -71,16 +75,17 @@ DRIVE_SECRET=my-secret-key
---
## Create Your First Tool
## Step 2: Write a Simple Tool
### How Tools Work
![Tool Execution Flow](./assets/tool-execution-flow.svg)
Tools are just `.bas` files. Create `enrollment.bas`:
```bas
' Student enrollment tool
PARAM name AS string LIKE "John Smith" DESCRIPTION "Student name"
PARAM email AS string LIKE "john@example.com" DESCRIPTION "Email address"
PARAM course AS string LIKE "Computer Science" DESCRIPTION "Course to enroll"
PARAM name, email, course
DESCRIPTION "Processes student enrollment"
SAVE "enrollments.csv", name, email, course, NOW()
@ -91,7 +96,7 @@ The LLM automatically discovers this tool and knows when to call it!
---
## Add Knowledge Base
## Step 3: Add Knowledge Base
Drop documents in a `.gbkb/` folder:
@ -135,17 +140,7 @@ lxc-attach -n botserver
---
## Build from Source
```bash
git clone https://github.com/GeneralBots/BotServer.git
cd BotServer
cargo run
```
Same automatic bootstrap process!
---
## Optional Components
@ -164,17 +159,17 @@ After installation, add more features:
```
mybot.gbai/
├── mybot.gbdialog/ # Dialog scripts
│ ├── start.bas # Entry point (required)
│ ├── get-weather.bas # Tool (auto-discovered)
│ └── send-email.bas # Tool (auto-discovered)
├── mybot.gbkb/ # Knowledge base
│ ├── docs/ # Document collection
│ └── faq/ # FAQ collection
├── mybot.gbot/ # Configuration
│ └── config.csv # Bot parameters
└── mybot.gbtheme/ # UI theme (optional)
└── custom.css
mybot.gbdialog/ # Dialog scripts
start.bas # Entry point (required)
get-weather.bas # Tool (auto-discovered)
send-email.bas # Tool (auto-discovered)
mybot.gbkb/ # Knowledge base
docs/ # Document collection
faq/ # FAQ collection
mybot.gbot/ # Configuration
config.csv # Bot parameters
mybot.gbtheme/ # UI theme (optional)
custom.css
```
Deploy new bots by uploading to object storage (creates a new bucket), not the local filesystem. The `work/` folder is for internal use only.

327
docs/src/chapter-01/sessions.md
View file

@ -1 +1,326 @@
# Understanding Sessions
# Sessions and Channels
**Every conversation has memory.** Sessions are the beating heart of BotServer - they remember who you are, what you've said, and where you left off. Even if you close your browser and come back tomorrow.
## What Is a Session?
A session is a persistent conversation container that tracks:
- Who's talking (user identity)
- What's been said (message history)
- Current state (variables, context)
- Active tools and knowledge bases
- Bot configuration
Think of it like a phone call that can pause and resume anytime.
## How Sessions Start
### Web Interface
1. User opens `http://localhost:8080`
2. Browser gets a session token (UUID)
3. Token stored in localStorage
4. Session created in PostgreSQL
5. Cached in Valkey for speed
### API Access
```bash
# Get new session
curl -X POST http://localhost:8080/api/session
# Returns: {"session_id": "uuid-here", "token": "secret-token"}
# Use session
curl -H "Authorization: Bearer secret-token" \
http://localhost:8080/api/chat
```
### Anonymous vs Authenticated
- **Anonymous**: Auto-created, temporary identity
- **Authenticated**: Linked to user account, permanent history
## Session Lifecycle
```
![Session State Flow](./assets/session-states.svg)
```
### Timeouts
- **Active**: No timeout while chatting
- **Idle**: 30 minutes default (configurable)
- **Expired**: 7 days for anonymous, never for authenticated
## What Gets Stored
### In PostgreSQL (Permanent)
```sql
sessions:
id: uuid
user_id: optional reference
bot_id: which bot
created_at: timestamp
last_activity: timestamp
messages:
session_id: reference
role: user/assistant/system
content: text
timestamp: when sent
session_state:
session_id: reference
variables: jsonb (all BASIC variables)
context: current knowledge/tools
```
### In Valkey Cache (Fast Access)
```
session:uuid:messages # Recent messages
session:uuid:variables # Current state
session:uuid:context # Active KB/tools
session:uuid:last_activity
```
### Data Flow Diagram
```
![Session Manager Architecture](./assets/session-manager.svg)
```
## Session Variables
Variables set in BASIC scripts persist across messages:
```basic
' First message
name = HEAR
SET user_name = name
' Later message (minutes or days later)
GET user_name
TALK "Welcome back, " + user_name
```
Storage happens automatically:
- Write to cache immediately
- Persist to PostgreSQL every message
- Restore from DB if cache misses
## Context Management
Each session maintains its own context:
```basic
' Session A
USE KB "policies"
' Only this session sees policies
' Session B (different user)
USE KB "products"
' This session only sees products
```
Contexts include:
- Active knowledge bases
- Loaded tools
- LLM configuration
- Custom prompts
## Multi-Bot Sessions
Different bots = different sessions:
```
/default → session-uuid-1 → default.gbai
/support → session-uuid-2 → support.gbai
/sales → session-uuid-3 → sales.gbai
```
Each bot session is independent:
- Separate conversation history
- Different knowledge bases
- Unique configuration
- No data sharing
## Session Security
### Token Generation
- Cryptographically secure random
- 256-bit entropy
- URL-safe base64 encoded
- Unique per session
### Token Validation
```rust
// Every request validates:
1. Token exists
2. Token not expired
3. Token matches session
4. Session still active
```
### Security Features
- No session hijacking (tokens unguessable)
- No session fixation (new token each session)
- Automatic cleanup of old sessions
- Rate limiting per session
## Debugging Sessions
### View Current Session
```bash
# In BASIC script
session_id = GET "session.id"
TALK "Session: " + session_id
```
### Database Inspection
```sql
-- See all active sessions
SELECT id, user_id, last_activity
FROM sessions
WHERE last_activity > NOW() - INTERVAL '30 minutes';
-- View session messages
SELECT role, content, timestamp
FROM messages
WHERE session_id = 'uuid-here'
ORDER BY timestamp;
```
### Cache Inspection
```bash
# Using valkey-cli
valkey-cli
> KEYS session:*
> GET session:uuid:variables
```
## Session Limits
Default limits (configurable):
- **Message history**: Last 50 messages kept in context
- **Variable storage**: 1MB per session
- **File uploads**: 10MB per file
- **Concurrent sessions**: 1000 per server
- **Rate limit**: 60 messages per minute
## Advanced Features
### Session Handoff
Transfer conversation between channels:
```basic
' Start on web
TRANSFER_SESSION "email"
' Continue via email
```
### Session Merge
Combine anonymous session with login:
```basic
ON LOGIN
MERGE_SESSION anonymous_id, user_id
END
```
### Session Export
Download conversation history:
```basic
history = GET "session.history"
SAVE "conversation.txt", history
```
### Session Templates
Pre-configure sessions:
```basic
' In start.bas
LOAD_TEMPLATE "customer_support"
' Sets up context, tools, initial message
```
## How It Works Automatically
Sessions require zero configuration:
- **Creation**: Automatic on first request
- **Storage**: Automatic to database and cache
- **Cleanup**: Automatic after expiration
- **Security**: Automatic token generation
- **Multi-channel**: Automatic adapter selection
You never need to manage sessions directly - just use the conversation keywords and everything happens behind the scenes.
## Common Patterns
### Welcome Back
```basic
last_visit = GET_BOT_MEMORY("last_visit_" + session_id)
if last_visit
TALK "Welcome back! Last seen: " + last_visit
else
TALK "Welcome! First time here?"
end
SET_BOT_MEMORY "last_visit_" + session_id, NOW()
```
### Progressive Disclosure
```basic
msg_count = GET "session.message_count"
if msg_count < 3
TALK "I can help with basic questions"
else if msg_count < 10
TALK "Try our advanced features!"
else
TALK "You're a power user! Check tools menu"
end
```
### Session Persistence
```basic
' Save progress
SET checkpoint = "step_3_complete"
' Later, restore progress
GET checkpoint
if checkpoint == "step_3_complete"
TALK "Let's continue from step 4"
end
```
## Troubleshooting
**Session not persisting?**
- Check PostgreSQL is running
- Verify cache is accessible
- Look for disk space issues
**Session expired too soon?**
- Adjust timeout in config.csv
- Check clock synchronization
- Monitor for memory pressure
**Can't resume session?**
- Token might be invalid
- Session could be expired
- Database connection issue
## Write Once, Run Everywhere
The same BASIC script runs across all channels - web, mobile apps, WhatsApp, Teams, email. Your investment in dialog development pays off everywhere:
```basic
' This same script works on:
' • Web interface
' • Mobile apps (via web view)
' • WhatsApp Business
' • Microsoft Teams
' • Email conversations
' • Voice assistants
TALK "Hello! How can I help?"
answer = HEAR
TALK "I understand you need help with: " + answer
```
Each channel adapter handles the specifics - you just write the conversation logic once.
## Summary
Sessions and channels work together seamlessly in BotServer. Sessions handle state management automatically across any channel, persist data reliably, and scale efficiently. You focus on the conversation flow - the system handles memory and multi-channel delivery.

23
docs/src/chapter-02/README.md
View file

@ -25,28 +25,9 @@ BotServer uses a template-based approach:
4. **Storage Upload**: Template files are uploaded to object storage for persistence
5. **Runtime Loading**: Bots load their resources from storage when serving requests
### Package Structure
## Package Structure
Each `.gbai` package is a directory containing subdirectories:
```
botname.gbai/
├── botname.gbdialog/ # Dialog scripts
│ ├── start.bas # Entry point script
│ ├── auth.bas # Authentication flow
│ └── *.bas # Other dialog scripts
├── botname.gbkb/ # Knowledge base for LLM
│ ├── collection1/ # Document collection (USE KB "collection1")
│ └── collection2/ # Another collection (USE KB "collection2")
├── botname.gbdrive/ # File storage (not KB)
│ ├── uploads/ # User uploaded files
│ ├── exports/ # Generated files (SAVE AS)
│ └── templates/ # File templates
├── botname.gbot/ # Configuration
│ └── config.csv # Bot parameters
└── botname.gbtheme/ # UI theme (optional)
└── default.css # Theme CSS (CHANGE THEME "default")
```
![Package Structure](./assets/package-structure.svg)
## Included Templates

132
docs/src/chapter-02/assets/package-structure.svg Normal file
View file

@ -0,0 +1,132 @@
<svg width="800" height="600" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Package Structure</text>
<!-- Root Package -->
<rect x="300" y="60" width="200" height="50" fill="none" stroke="#4299E1" stroke-width="2" rx="8"/>
<text x="400" y="85" text-anchor="middle" font-family="monospace" font-size="14" font-weight="bold" fill="#63B3ED">my-bot.gbai/</text>
<text x="400" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#90CDF4">(Package Root)</text>
<!-- Connection Lines from Root -->
<g stroke="#888" stroke-width="1" fill="none">
<line x1="400" y1="110" x2="400" y2="140"/>
<!-- Horizontal spread -->
<line x1="400" y1="140" x2="150" y2="140"/>
<line x1="400" y1="140" x2="650" y2="140"/>
<!-- Vertical lines to components -->
<line x1="150" y1="140" x2="150" y2="180"/>
<line x1="280" y1="140" x2="280" y2="180"/>
<line x1="400" y1="140" x2="400" y2="180"/>
<line x1="520" y1="140" x2="520" y2="180"/>
<line x1="650" y1="140" x2="650" y2="180"/>
</g>
<!-- Component Folders -->
<g id="folders">
<!-- .gbdialog -->
<rect x="70" y="180" width="160" height="80" fill="none" stroke="#F6AD55" stroke-width="2" rx="6"/>
<text x="150" y="205" text-anchor="middle" font-family="monospace" font-size="13" font-weight="bold" fill="#FBD38D">.gbdialog</text>
<text x="150" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FED7AA">Dialog Scripts</text>
<text x="150" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">Conversation Logic</text>
<!-- .gbkb -->
<rect x="200" y="180" width="160" height="80" fill="none" stroke="#4FD1C5" stroke-width="2" rx="6"/>
<text x="280" y="205" text-anchor="middle" font-family="monospace" font-size="13" font-weight="bold" fill="#81E6D9">.gbkb</text>
<text x="280" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#B2F5EA">Knowledge Base</text>
<text x="280" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">Documents</text>
<!-- .gbot -->
<rect x="320" y="180" width="160" height="80" fill="none" stroke="#B794F4" stroke-width="2" rx="6"/>
<text x="400" y="205" text-anchor="middle" font-family="monospace" font-size="13" font-weight="bold" fill="#D6BCFA">.gbot</text>
<text x="400" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">Configuration</text>
<text x="400" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">Bot Settings</text>
<!-- .gbtheme -->
<rect x="440" y="180" width="160" height="80" fill="none" stroke="#FC8181" stroke-width="2" rx="6"/>
<text x="520" y="205" text-anchor="middle" font-family="monospace" font-size="13" font-weight="bold" fill="#FC8181">.gbtheme</text>
<text x="520" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FEB2B2">(optional)</text>
<text x="520" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">UI Theme</text>
<!-- .gbdrive -->
<rect x="570" y="180" width="160" height="80" fill="none" stroke="#68D391" stroke-width="2" rx="6"/>
<text x="650" y="205" text-anchor="middle" font-family="monospace" font-size="13" font-weight="bold" fill="#68D391">.gbdrive</text>
<text x="650" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#9AE6B4">(optional)</text>
<text x="650" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">File Storage</text>
</g>
<!-- Connection lines to file types -->
<g stroke="#888" stroke-width="1" fill="none" opacity="0.6">
<line x1="150" y1="260" x2="150" y2="300"/>
<line x1="280" y1="260" x2="280" y2="300"/>
<line x1="400" y1="260" x2="400" y2="300"/>
<line x1="520" y1="260" x2="520" y2="300"/>
<line x1="650" y1="260" x2="650" y2="300"/>
</g>
<!-- File Types -->
<g id="file-types">
<!-- Scripts -->
<rect x="80" y="300" width="140" height="60" fill="none" stroke="#F6AD55" stroke-width="1" rx="4" stroke-dasharray="3,3" opacity="0.7"/>
<text x="150" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#FBD38D">Scripts</text>
<text x="150" y="345" text-anchor="middle" font-family="monospace" font-size="11" fill="#A0AEC0">.bas files</text>
<!-- Documents -->
<rect x="210" y="300" width="140" height="60" fill="none" stroke="#4FD1C5" stroke-width="1" rx="4" stroke-dasharray="3,3" opacity="0.7"/>
<text x="280" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#81E6D9">Docs</text>
<text x="280" y="345" text-anchor="middle" font-family="monospace" font-size="11" fill="#A0AEC0">PDF/TXT</text>
<!-- Config -->
<rect x="330" y="300" width="140" height="60" fill="none" stroke="#B794F4" stroke-width="1" rx="4" stroke-dasharray="3,3" opacity="0.7"/>
<text x="400" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#D6BCFA">Config</text>
<text x="400" y="345" text-anchor="middle" font-family="monospace" font-size="11" fill="#A0AEC0">.csv</text>
<!-- Styles -->
<rect x="450" y="300" width="140" height="60" fill="none" stroke="#FC8181" stroke-width="1" rx="4" stroke-dasharray="3,3" opacity="0.7"/>
<text x="520" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#FC8181">Styles</text>
<text x="520" y="345" text-anchor="middle" font-family="monospace" font-size="11" fill="#A0AEC0">CSS/HTML</text>
<!-- Storage -->
<rect x="580" y="300" width="140" height="60" fill="none" stroke="#68D391" stroke-width="1" rx="4" stroke-dasharray="3,3" opacity="0.7"/>
<text x="650" y="325" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#68D391">Storage</text>
<text x="650" y="345" text-anchor="middle" font-family="monospace" font-size="11" fill="#A0AEC0">S3 Link</text>
</g>
<!-- Example Structure -->
<g id="example" transform="translate(100, 400)">
<text x="0" y="0" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#CBD5E0">Example Directory Structure:</text>
<g font-family="monospace" font-size="12" fill="#A0AEC0">
<text x="0" y="30">botname.gbai/</text>
<text x="20" y="50">├── botname.gbdialog/</text>
<text x="40" y="70">│ ├── start.bas</text>
<text x="40" y="90">│ ├── auth.bas</text>
<text x="40" y="110">│ └── tools/</text>
<text x="20" y="130">├── botname.gbkb/</text>
<text x="40" y="150">│ ├── collection1/</text>
<text x="40" y="170">│ └── collection2/</text>
<text x="20" y="190">├── botname.gbot/</text>
<text x="40" y="210">│ └── config.csv</text>
<text x="20" y="230">└── botname.gbtheme/</text>
<text x="40" y="250"> └── default.css</text>
</g>
</g>
<!-- Notes -->
<g id="notes" transform="translate(450, 430)">
<rect x="0" y="0" width="300" height="120" fill="none" stroke="#4A5568" stroke-width="1" rx="5" stroke-dasharray="2,2" opacity="0.5"/>
<text x="150" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#CBD5E0">Key Points</text>
<g font-family="Arial, sans-serif" font-size="11" fill="#A0AEC0">
<text x="10" y="45">• Folder name = Bot name</text>
<text x="10" y="65">• Only .gbdialog is required</text>
<text x="10" y="85">• start.bas is the entry point</text>
<text x="10" y="105">• Deploy by copying folder</text>
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 8.1 KiB

83
docs/src/chapter-02/assets/template-deployment-flow.svg Normal file
View file

@ -0,0 +1,83 @@
<svg width="600" height="800" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="300" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">Template Deployment Flow</text>
<!-- Templates folder -->
<rect x="225" y="60" width="150" height="50" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="300" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#90CDF4">templates/</text>
<text x="300" y="100" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#CBD5E0">Source folder</text>
<!-- Arrow down -->
<line x1="300" y1="110" x2="300" y2="140" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- SCAN -->
<rect x="200" y="140" width="200" height="70" fill="none" stroke="#F6AD55" stroke-width="2" rx="8"/>
<text x="300" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBD38D">SCAN</text>
<text x="300" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FED7AA">Find all .gbai folders</text>
<!-- Arrow down -->
<line x1="300" y1="210" x2="300" y2="240" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- VALIDATE -->
<rect x="200" y="240" width="200" height="90" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
<text x="300" y="265" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">VALIDATE</text>
<text x="300" y="285" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">Check required structure</text>
<text x="300" y="300" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• start.bas exists?</text>
<text x="300" y="315" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Folders match name?</text>
<!-- Arrow down -->
<line x1="300" y1="330" x2="300" y2="360" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- UPLOAD -->
<rect x="200" y="360" width="200" height="90" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
<text x="300" y="385" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">UPLOAD</text>
<text x="300" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#9AE6B4">Copy to object storage</text>
<text x="300" y="420" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Templates → S3/Drive</text>
<text x="300" y="435" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Assets → CDN paths</text>
<!-- Arrow down -->
<line x1="300" y1="450" x2="300" y2="480" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- INDEX -->
<rect x="200" y="480" width="200" height="90" fill="none" stroke="#4FD1C5" stroke-width="2" rx="8"/>
<text x="300" y="505" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#81E6D9">INDEX</text>
<text x="300" y="525" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#B2F5EA">Process knowledge base</text>
<text x="300" y="540" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Extract text</text>
<text x="300" y="555" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Generate embeddings</text>
<text x="300" y="570" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Store in Qdrant</text>
<!-- Arrow down -->
<line x1="300" y1="580" x2="300" y2="610" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- REGISTER -->
<rect x="200" y="610" width="200" height="90" fill="none" stroke="#FBBF24" stroke-width="2" rx="8"/>
<text x="300" y="635" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FCD34D">REGISTER</text>
<text x="300" y="655" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FDE68A">Create in database</text>
<text x="300" y="670" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Bot record</text>
<text x="300" y="685" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Configuration</text>
<text x="300" y="700" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• URL mapping</text>
<!-- Arrow down -->
<line x1="300" y1="710" x2="300" y2="740" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- ACTIVATE -->
<rect x="200" y="740" width="200" height="90" fill="none" stroke="#FC8181" stroke-width="2" rx="8"/>
<text x="300" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">ACTIVATE</text>
<text x="300" y="785" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FEB2B2">Start serving</text>
<text x="300" y="800" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• /bot-name endpoint</text>
<text x="300" y="815" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• WebSocket ready</text>
<text x="300" y="830" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">• Sessions enabled</text>
<!-- Process time indicator -->
<g id="time-indicator" transform="translate(450, 450)">
<circle cx="0" cy="0" r="40" fill="none" stroke="#4A5568" stroke-width="1" opacity="0.5"/>
<text x="0" y="0" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#CBD5E0">5-10s</text>
<text x="0" y="15" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#A0AEC0">per bot</text>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 6 KiB

382
docs/src/chapter-02/gbai.md
View file

@ -1,183 +1,291 @@
# .gbai Architecture
The `.gbai` extension defines a bot application package in the GeneralBots template system. It serves as the container directory for all bot-related resources including dialogs, knowledge bases, and configuration.
**A bot is just a folder.** The `.gbai` extension marks a directory as a BotServer package containing everything needed to run a conversational AI bot - scripts, documents, configuration, and themes.
## What is .gbai?
`.gbai` (General Bot Application Interface) is a directory-based package structure that contains all components needed to define a bot. During bootstrap, the system scans the `templates/` directory for folders ending in `.gbai` and automatically creates bot instances from them.
## Real .gbai Structure
A `.gbai` package is a directory containing subdirectories for different bot components:
## The Dead Simple Structure
```
my-bot.gbai/
├── my-bot.gbdialog/ # Dialog scripts (.bas files)
│ ├── start.bas
│ ├── auth.bas
│ └── *.bas
├── my-bot.gbkb/ # Knowledge base collections
│ ├── collection1/
│ └── collection2/
├── my-bot.gbot/ # Bot configuration
│ └── config.csv
└── my-bot.gbtheme/ # UI themes (optional)
├── css/
└── html/
my-bot.gbai/ # This folder = your entire bot
my-bot.gbdialog/ # BASIC conversation scripts
my-bot.gbkb/ # Documents for Q&A
my-bot.gbot/ # Configuration
my-bot.gbtheme/ # Optional UI customization
```
## Included Templates
That's it. No manifests, no build files, no dependencies. Copy the folder to deploy.
BotServer includes 21 template `.gbai` packages in the `/templates` directory:
### Visual Architecture
### Architecture
### default.gbai
![Package Structure](./assets/package-structure.svg)
The default bot template with minimal configuration:
- `default.gbot/config.csv` - Basic server and LLM configuration
## How Bootstrap Finds Bots
### announcements.gbai
At startup, BotServer scans `templates/` for any folder ending in `.gbai`:
A feature-rich example bot:
- `announcements.gbdialog/` - Multiple dialog scripts:
- `start.bas` - Initialization and context setup
- `auth.bas` - Authentication flow
- `change-subject.bas` - Topic switching
- `update-summary.bas` - Summary generation
- `announcements.gbkb/` - Knowledge base collections:
- `auxiliom/` - Auxiliom product information
- `news/` - News and announcements
- `toolbix/` - Toolbix product information
- `annoucements.gbot/` - Bot configuration
```
templates/
default.gbai/ → Creates bot at /default
support.gbai/ → Creates bot at /support
sales.gbai/ → Creates bot at /sales
```
## Package Components
Each `.gbai` becomes a URL endpoint automatically. Zero configuration.
### .gbdialog - Dialog Scripts
## What Goes Where
Contains BASIC-like scripts (`.bas` files) that define conversation logic:
- Simple English-like syntax
- Custom keywords: `TALK`, `HEAR`, `LLM`, `GET BOT MEMORY`, `SET CONTEXT`
- Control flow and variables
- Tool integration
### .gbdialog/ - Your Bot's Brain
Example from `announcements.gbai/announcements.gbdialog/start.bas`:
BASIC scripts that control conversation flow:
```
my-bot.gbdialog/
start.bas # Runs when session starts
auth.bas # Login flow
tools/ # Callable functions
book-meeting.bas
check-status.bas
handlers/ # Event responses
on-email.bas
```
Example `start.bas`:
```basic
resume1 = GET BOT MEMORY "resume"
resume2 = GET BOT MEMORY "auxiliom"
resume3 = GET BOT MEMORY "toolbix"
SET CONTEXT "general" AS resume1
SET CONTEXT "auxiliom" AS resume2
SET CONTEXT "toolbix" AS resume3
TALK resume1
TALK "You can ask me about any of the announcements or circulars."
TALK "Hi! I'm your assistant."
answer = HEAR
TALK "I can help you with: " + answer
```
### .gbkb - Knowledge Base
### .gbkb/ - Your Bot's Knowledge
Directory structure containing collections of documents for semantic search:
- Each subdirectory represents a collection
- Documents are indexed into vector database
- Used for context retrieval during conversations
Documents organized by topic:
### .gbot - Configuration
```
my-bot.gbkb/
policies/ # HR documents
vacation.pdf
handbook.docx
products/ # Product info
catalog.pdf
pricing.xlsx
support/ # Help docs
faq.md
```
Contains `config.csv` with bot parameters:
- Server settings (host, port)
- LLM configuration (API keys, model paths, URLs)
- Embedding model settings
- Email integration settings
- Database connection strings
- Component toggles (MCP server, LLM server)
Each folder becomes a searchable collection. Drop files in, bot learns automatically.
### .gbtheme - UI Theme (Optional)
### .gbot/ - Your Bot's Settings
Custom UI themes with CSS and HTML assets for the web interface.
Single `config.csv` file with key-value pairs:
## Bootstrap Process
```csv
llm-model,gpt-3.5-turbo
temperature,0.7
max-tokens,2000
welcome-message,Hello! How can I help?
session-timeout,1800
```
During the Auto Bootstrap process:
No complex JSON or YAML. Just simple CSV that opens in Excel.
1. **Template Scanning**: System scans `templates/` directory for `.gbai` folders
2. **Bot Creation**: Each `.gbai` folder generates a bot record in the database
- Folder name `default.gbai` → Bot name "Default"
- Folder name `announcements.gbai` → Bot name "Announcements"
3. **Configuration Loading**: Bot configuration from `.gbot/config.csv` is loaded
4. **Template Upload**: All template files are uploaded to object storage (drive)
5. **Dialog Loading**: BASIC scripts from `.gbdialog` are loaded and ready to execute
6. **KB Indexing**: Documents from `.gbkb` are indexed into vector database
### .gbtheme/ - Your Bot's Look (Optional)
## Creating Custom .gbai Packages
Custom web interface styling:
To create a custom bot:
```
my-bot.gbtheme/
styles.css # Custom CSS
logo.png # Brand assets
templates/ # HTML overrides
chat.html
```
1. Create a new directory in `templates/` with `.gbai` extension:
```bash
mkdir templates/mybot.gbai
```
If missing, uses default theme. Most bots don't need this.
2. Create the required subdirectories:
```bash
mkdir -p templates/mybot.gbai/mybot.gbdialog
mkdir -p templates/mybot.gbai/mybot.gbkb
mkdir -p templates/mybot.gbai/mybot.gbot
```
## Real Example: Support Bot
3. Add dialog scripts to `.gbdialog/`:
```bash
# Create start.bas with your conversation logic
touch templates/mybot.gbai/mybot.gbdialog/start.bas
```
Here's a complete customer support bot:
4. Add bot configuration to `.gbot/config.csv`:
```csv
name,value
server_host,0.0.0.0
server_port,8080
llm-key,your-api-key
llm-url,https://api.openai.com/v1
llm-model,gpt-4
```
```
support.gbai/
support.gbdialog/
start.bas
tools/
create-ticket.bas
check-status.bas
support.gbkb/
faqs/
common-questions.pdf
guides/
troubleshooting.docx
support.gbot/
config.csv
```
5. Add knowledge base documents to `.gbkb/`:
```bash
mkdir templates/mybot.gbai/mybot.gbkb/docs
# Copy your documents into this directory
```
`start.bas`:
```basic
USE KB "faqs"
USE KB "guides"
USE TOOL "create-ticket"
USE TOOL "check-status"
6. Restart BotServer - the bootstrap process will detect and create your bot
TALK "Support bot ready. How can I help?"
```
## Package Lifecycle
`create-ticket.bas`:
```basic
PARAM issue, priority
DESCRIPTION "Creates support ticket"
1. **Development**: Edit files in `templates/your-bot.gbai/`
2. **Bootstrap**: System creates bot from template
3. **Storage**: Files uploaded to object storage for persistence
4. **Runtime**: Bot loads dialogs and configuration from storage
5. **Updates**: Modify template files and restart to apply changes
ticket_id = GENERATE_ID()
SAVE "tickets.csv", ticket_id, issue, priority, NOW()
TALK "Ticket #" + ticket_id + " created"
```
## Multi-Bot Support
`config.csv`:
```csv
llm-model,gpt-3.5-turbo
bot-name,TechSupport
greeting,Welcome to support!
```
A single BotServer instance can host multiple bots:
- Each `.gbai` package creates a separate bot
- Bots run in isolation with separate configurations
- Each bot has its own knowledge base collections
- Session state is maintained per bot
## Deployment = Copy Folder
## Package Storage
### Local Development
```bash
cp -r my-bot.gbai/ templates/
./botserver restart
# Visit http://localhost:8080/my-bot
```
After bootstrap, packages are stored in:
- **Object Storage**: Template files and assets
- **Database**: Bot metadata and configuration
- **Vector Database**: Embeddings from knowledge bases
- **Cache**: Session and cache data
### Production Server
```bash
scp -r my-bot.gbai/ server:~/botserver/templates/
ssh server "cd botserver && ./botserver restart"
```
### Deployment
### LXC Container
```bash
lxc file push my-bot.gbai/ container/app/templates/
```
No build step. No compilation. Just copy files.
## Multi-Bot Hosting
One BotServer runs multiple bots:
```
templates/
support.gbai/ # support.example.com
sales.gbai/ # sales.example.com
internal.gbai/ # internal.example.com
public.gbai/ # www.example.com
```
Each bot:
- Gets own URL endpoint
- Has isolated sessions
- Runs independently
- Shares infrastructure
## Template Inheritance
Bots can share common resources:
```
templates/
_shared/
knowledge/ # Shared documents
tools/ # Shared functions
bot1.gbai/
bot1.gbot/
config.csv # includes: _shared
bot2.gbai/
bot2.gbot/
config.csv # includes: _shared
```
## Naming Conventions
- Package directory: `name.gbai`
- Dialog directory: `name.gbdialog`
- Knowledge base: `name.gbkb`
- Configuration: `name.gbot`
- Theme directory: `name.gbtheme`
### Required
- Folder must end with `.gbai`
- Subfolders must match: `botname.gbdialog`, `botname.gbkb`, etc.
- Main script must be `start.bas`
The `name` should be consistent across all subdirectories within a package.
### Recommended
- Use lowercase with hyphens: `customer-service.gbai`
- Group related bots: `support-tier1.gbai`, `support-tier2.gbai`
- Version in folder name if needed: `chatbot-v2.gbai`
## Bootstrap Process
When BotServer starts:
```
![Template Deployment Flow](./assets/template-deployment-flow.svg)
```
Takes about 5-10 seconds per bot.
## Hot Reload
Change files while running:
```bash
# Edit script
vim templates/my-bot.gbai/my-bot.gbdialog/start.bas
# Reload just that bot
curl http://localhost:8080/api/admin/reload/my-bot
# Or restart everything
./botserver restart
```
## Package Size Limits
Default limits (configurable):
- Total package: 100MB
- Single document: 10MB
- Number of files: 1000
- Script size: 1MB
- Collection count: 50
## Troubleshooting
**Bot not appearing?**
- Check folder ends with `.gbai`
- Verify subfolders match bot name
- Look for `start.bas` in `.gbdialog/`
**Documents not searchable?**
- Ensure files are in `.gbkb/` subfolder
- Check file format is supported
- Wait 30 seconds for indexing
**Scripts not running?**
- Validate BASIC syntax
- Check file has `.bas` extension
- Review logs for errors
## Best Practices
### Do's
✅ Keep packages under 50MB
✅ Organize knowledge by topic
✅ Use clear folder names
✅ Test locally first
### Don'ts
❌ Don't nest `.gbai` folders
❌ Don't mix test/prod in same folder
❌ Don't hardcode absolute paths
❌ Don't store secrets in scripts
## Summary
The `.gbai` architecture keeps bot development simple. No complex frameworks, no build systems, no deployment pipelines. Just organize your files in folders, and BotServer handles the rest. Focus on content and conversation, not configuration.
Next: Learn about [.gbdialog Dialogs](./gbdialog.md) for writing conversation scripts.

20
docs/src/chapter-02/gbdrive.md
View file

@ -16,16 +16,16 @@ Files are organized in a bucket-per-bot structure:
```
org-prefixbot-name.gbai/
├── .gbdialog/
│ └── [script files]
├── .gbkb/
│ └── [collection folders]
├── .gbot/
│ └── config.csv
├── .gbtheme/
│ └── [theme files]
└── user-uploads/
└── [user files]
.gbdialog/
[script files]
.gbkb/
[collection folders]
.gbot/
config.csv
.gbtheme/
[theme files]
user-uploads/
[user files]
```
## File Operations

14
docs/src/chapter-02/gbkb.md
View file

@ -16,13 +16,13 @@ Each `.gbkb` collection is organized as:
```
collection-name.gbkb/
├── documents/
│ ├── doc1.pdf
│ ├── doc2.txt
│ └── doc3.html
├── embeddings/ # Auto-generated
├── metadata.json # Collection info
└── index.json # Search indexes
documents/
doc1.pdf
doc2.txt
doc3.html
embeddings/ # Auto-generated
metadata.json # Collection info
index.json # Search indexes
```
## Supported Formats

6
docs/src/chapter-02/gbtheme.md
View file

@ -12,9 +12,9 @@ A theme is simply one or more CSS files in the `.gbtheme` folder:
```
botname.gbtheme/
└── default.css # Main theme file
└── dark.css # Alternative theme
└── holiday.css # Seasonal theme
default.css # Main theme file
dark.css # Alternative theme
holiday.css # Seasonal theme
```
## Using Themes

26
docs/src/chapter-02/templates.md
View file

@ -34,19 +34,19 @@ All templates follow this standard directory layout:
```
template-name.gbai/
├── template-name.gbdialog/ # BASIC dialog scripts
│ ├── start.bas # Entry point (required)
│ └── *.bas # Tool scripts (auto-discovered)
├── template-name.gbkb/ # Knowledge base collections
│ ├── collection1/ # Documents for USE KB "collection1"
│ └── collection2/ # Documents for USE KB "collection2"
├── template-name.gbdrive/ # File storage (not KB)
│ ├── uploads/ # User uploaded files
│ └── exports/ # Generated files
├── template-name.gbot/ # Configuration
│ └── config.csv # Bot parameters
└── template-name.gbtheme/ # UI theme (optional)
└── default.css # Theme CSS
template-name.gbdialog/ # BASIC dialog scripts
start.bas # Entry point (required)
*.bas # Tool scripts (auto-discovered)
template-name.gbkb/ # Knowledge base collections
collection1/ # Documents for USE KB "collection1"
collection2/ # Documents for USE KB "collection2"
template-name.gbdrive/ # File storage (not KB)
uploads/ # User uploaded files
exports/ # Generated files
template-name.gbot/ # Configuration
config.csv # Bot parameters
template-name.gbtheme/ # UI theme (optional)
default.css # Theme CSS
```
## Quick Start Guide

201
docs/src/chapter-03/caching.md
View file

@ -1,13 +1,30 @@
# Caching
BotServer includes automatic caching to improve response times and reduce redundant processing.
BotServer includes automatic caching to improve response times and reduce redundant processing, including semantic caching for LLM responses using Valkey (a Redis-compatible in-memory database).
## Features
- **Exact Match Caching**: Cache responses for identical prompts
- **Semantic Similarity Matching**: Find and reuse responses for semantically similar prompts
- **Configurable TTL**: Control how long cached responses remain valid
- **Per-Bot Configuration**: Enable/disable caching on a per-bot basis
- **Embedding-Based Similarity**: Use local embedding models for semantic matching
- **Statistics & Monitoring**: Track cache hits, misses, and performance metrics
## How Caching Works
Caching in BotServer is controlled by configuration parameters in `config.csv`. The system automatically caches LLM responses and manages conversation history.
When enabled, the semantic cache:
1. User asks a question
2. System checks if a semantically similar question was asked before
3. If similarity > threshold (0.95), returns cached response
4. Otherwise, generates new response and caches it
## Configuration
### Basic Cache Settings
From `default.gbai/default.gbot/config.csv`:
```csv
@ -17,6 +34,24 @@ llm-cache-semantic,true # Use semantic similarity for cache matching
llm-cache-threshold,0.95 # Similarity threshold for cache hits
```
### Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `llm-cache` | boolean | false | Enable/disable LLM response caching |
| `llm-cache-ttl` | integer | 3600 | Time-to-live for cached entries (in seconds) |
| `llm-cache-semantic` | boolean | true | Enable semantic similarity matching |
| `llm-cache-threshold` | float | 0.95 | Similarity threshold for semantic matches (0.0-1.0) |
### Embedding Service Configuration
For semantic similarity matching, ensure your embedding service is configured:
```csv
embedding-url,http://localhost:8082
embedding-model,../../../../data/llm/bge-small-en-v1.5-f32.gguf
```
## Conversation History Management
The system manages conversation context through these parameters:
@ -31,17 +66,36 @@ prompt-compact,4 # Compact conversation after N exchanges
- **prompt-history**: Keeps the last 2 exchanges in the conversation context
- **prompt-compact**: After 4 exchanges, older messages are summarized or removed to save tokens
## LLM Response Caching
## Cache Storage with Valkey
When `llm-cache` is enabled:
### Architecture
1. User asks a question
2. System checks if a semantically similar question was asked before
3. If similarity > threshold (0.95), returns cached response
4. Otherwise, generates new response and caches it
```
User Query → Generate Key → Check Valkey → Hit/Miss Decision
↓ ↓
Embedding Hash Return Cached / Generate New
↓ ↓
Semantic Search Store in Valkey with TTL
```
### Cache Key Structure
The cache uses a multi-level key structure:
- **Exact match**: Hash of the exact prompt
- **Semantic match**: Embedding vector stored with semantic index
### Valkey Integration
Valkey provides:
- **Fast in-memory storage**: Sub-millisecond response times
- **Automatic expiration**: TTL-based cache invalidation
- **Distributed caching**: Share cache across multiple bot instances
- **Persistence options**: Optional disk persistence for cache durability
## Example Usage
### Basic Caching
```basic
' Caching happens automatically when enabled
USE KB "policies"
@ -49,52 +103,119 @@ USE KB "policies"
' First user asks: "What's the vacation policy?"
' System generates response and caches it
' Second user asks: "Tell me about vacation days"
' System finds cached response (high semantic similarity)
' Returns instantly without calling LLM
' Second user asks: "Tell me about vacation rules"
' System finds semantic match (>0.95 similarity) and returns cached response
```
## Cache Storage
### Tool Response Caching
The cache is stored in the cache component (Valkey) when available, providing:
- Fast in-memory access
- Persistence across restarts
- Shared cache across sessions
```basic
' Tool responses can also be cached
USE TOOL "weather-api"
## Benefits
' First request: "What's the weather in NYC?"
' Makes API call, caches response for 1 hour
- **Faster responses** for common questions
- **Lower costs** by reducing LLM API calls
- **Consistent answers** for similar questions
- **Automatic management** with no code changes
' Second request within TTL: "NYC weather?"
' Returns cached response without API call
```
## Cache Management
The cache operates automatically based on your configuration settings. Cache entries are managed through TTL expiration and Valkey's memory policies.
## Best Practices
1. **Enable for FAQ bots** - High cache hit rate
2. **Adjust threshold** - Lower for more cache hits, higher for precision
3. **Set appropriate TTL** - Balance freshness vs performance
4. **Monitor cache hits** - Ensure it's providing value
### When to Enable Caching
Enable caching for:
- ✅ FAQ bots with repetitive questions
- ✅ Knowledge base queries
- ✅ API-heavy integrations
- ✅ High-traffic bots
Disable caching for:
- ❌ Real-time data queries
- ❌ Personalized responses
- ❌ Time-sensitive information
- ❌ Development/testing
### Tuning Cache Parameters
**TTL Settings**:
- Short (300s): News, weather, stock prices
- Medium (3600s): General knowledge, FAQs
- Long (86400s): Static documentation, policies
**Similarity Threshold**:
- High (0.95+): Strict matching, fewer false positives
- Medium (0.85-0.95): Balance between coverage and accuracy
- Low (<0.85): Broad matching, risk of incorrect responses
### Memory Management
Valkey automatically manages memory through:
- **Eviction policies**: LRU (Least Recently Used) by default
- **Max memory limits**: Configure in Valkey settings
- **Key expiration**: Automatic cleanup of expired entries
## Performance Impact
With caching enabled:
- Common questions: <50ms response time
- Cache misses: Normal LLM response time
- Memory usage: Minimal (only stores text responses)
Typical performance improvements with caching enabled:
## Clearing Cache
| Metric | Without Cache | With Cache | Improvement |
|--------|--------------|------------|-------------|
| Response Time | 2-5s | 50-200ms | 10-100x faster |
| API Calls | Every request | First request only | 90%+ reduction |
| Token Usage | Full context | Cached response | 95%+ reduction |
| Cost | $0.02/request | $0.001/request | 95% cost saving |
Cache is automatically cleared when:
- TTL expires (after 3600 seconds by default)
- Bot configuration changes
- Knowledge base is updated
- System restarts (if not using persistent cache)
## Troubleshooting
## Important Notes
### Cache Not Working
- Caching is transparent to dialog scripts
- No special commands needed
- Works with all LLM providers
- Respects conversation context
Check:
1. Valkey is running: `ps aux | grep valkey`
2. Cache enabled in config: `llm-cache,true`
3. TTL not expired
4. Similarity threshold not too high
Remember: Caching is configured in `config.csv`, not through BASIC commands!
### Clear Cache
To clear the cache manually:
```bash
# Connect to Valkey
valkey-cli
# Clear all bot cache
FLUSHDB
# Clear specific bot cache
DEL bot:cache:*
```
### Clear Cache
To clear the cache manually:
```bash
# Connect to Valkey
valkey-cli
# Clear all bot cache
FLUSHDB
# Clear specific bot cache
DEL bot:cache:*
```
## Summary
The semantic caching system in BotServer provides intelligent response caching that:
- Reduces response latency by 10-100x
- Cuts API costs by 90%+
- Maintains response quality through semantic matching
- Scales automatically with Valkey
Configure caching based on your bot's needs, monitor performance metrics, and tune parameters for optimal results.

8
docs/src/chapter-03/kb-and-tools.md
View file

@ -41,7 +41,7 @@ work/
2. **Process files** - Extracts text from PDF, DOCX, TXT, MD, CSV files
3. **Chunk text** - Splits into ~1000 character chunks with overlap
4. **Generate embeddings** - Creates vector representations
5. **Store in VectorDB** - Saves to Qdrant for similarity search
5. **Store in VectorDB** - Saves to vector database for similarity search
6. **Ready for queries** - KB available for semantic search
### Supported File Types
@ -239,7 +239,7 @@ ws.send({
## Implementation Details
### Vector Database (Qdrant)
### Vector Database
Configuration:
- **Collection**: Per bot instance
@ -257,7 +257,7 @@ Configuration:
3. Clean and normalize text
4. Split into chunks (1000 chars, 200 overlap)
5. Generate embeddings via OpenAI
6. Store in Qdrant with metadata
6. Store in vector database with metadata
7. Update session context
```
@ -434,7 +434,7 @@ rate_limit = 100
sandbox = true
[vectordb]
provider = "qdrant"
provider = "vector"
url = "http://localhost:6333"
collection_prefix = "botserver_"
```

43
docs/src/chapter-03/qdrant.md
View file

@ -1,43 +0,0 @@
# VectorDB Integration
GeneralBots uses **VectorDB** as the vector database for storing and searching embeddings. The Rust client for the configured VectorDB is used to communicate with the service.
## Configuration
The connection is configured via environment variables:
```env
VECTORDB_URL=http://localhost:6333
VECTORDB_API_KEY=your-api-key # optional
```
These values are read at startup and passed to the `VectorDBClient`.
## Collection Mapping
Each `.gbkb` collection maps to a VectorDB collection with the same name. For example, a knowledge base named `company-policies` becomes a VectorDB 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 VectorDB’s `hnsw` parameters in `VectorDBClient::new` if you need higher recall.
- Use the `FILTER` option to restrict searches by metadata (e.g., source file).
## Example `FIND` Usage
```basic
USE_KB "company-policies"
FIND "vacation policy" INTO RESULT
TALK RESULT
```
The keyword internally:
1. Generates an embedding for the query string.
2. Calls VectorDB’s `search` API.
3. Returns the most relevant chunk as `RESULT`.

231
docs/src/chapter-03/semantic-cache.md
View file

@ -1,231 +0,0 @@
# Semantic Cache with Valkey
## Overview
The BotServer now supports semantic caching for LLM responses using Valkey (cache component - a Redis-compatible in-memory database). This feature can significantly reduce response times and API costs by intelligently caching and reusing previous LLM responses.
## Features
- **Exact Match Caching**: Cache responses for identical prompts
- **Semantic Similarity Matching**: Find and reuse responses for semantically similar prompts
- **Configurable TTL**: Control how long cached responses remain valid
- **Per-Bot Configuration**: Enable/disable caching on a per-bot basis
- **Embedding-Based Similarity**: Use local embedding models for semantic matching
- **Statistics & Monitoring**: Track cache hits, misses, and performance metrics
## Configuration
### Enabling Semantic Cache
To enable semantic caching for a bot, add the following configuration to your bot's `config.csv` file:
```csv
llm-cache,true
llm-cache-ttl,3600
llm-cache-semantic,true
llm-cache-threshold,0.95
```
### Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `llm-cache` | boolean | false | Enable/disable LLM response caching |
| `llm-cache-ttl` | integer | 3600 | Time-to-live for cached entries (in seconds) |
| `llm-cache-semantic` | boolean | true | Enable semantic similarity matching |
| `llm-cache-threshold` | float | 0.95 | Similarity threshold for semantic matches (0.0-1.0) |
### Embedding Service Configuration
For semantic similarity matching, ensure your embedding service is configured:
```csv
embedding-url,http://localhost:8082
embedding-model,../../../../data/llm/bge-small-en-v1.5-f32.gguf
```
## How It Works
### 1. Cache Key Generation
When a request is made to the LLM, a cache key is generated using:
- The prompt text
- The conversation context/messages
- The model being used
The key is hashed using SHA-256 to ensure consistent and secure storage.
### 2. Cache Lookup Process
```mermaid
graph TD
A[LLM Request] --> B{Cache Enabled?}
B -->|No| C[Direct LLM Call]
B -->|Yes| D[Generate Cache Key]
D --> E{Exact Match?}
E -->|Yes| F[Return Cached Response]
E -->|No| G{Semantic Matching Enabled?}
G -->|No| H[Call LLM]
G -->|Yes| I[Get Prompt Embedding]
I --> J[Search Similar Cached Responses]
J --> K{Similarity > Threshold?}
K -->|Yes| L[Return Similar Response]
K -->|No| H
H --> M[Cache New Response]
M --> N[Return Response]
```
### 3. Semantic Similarity Matching
When semantic matching is enabled:
1. The prompt is converted to an embedding vector using the configured embedding model
2. Recent cache entries for the same model are retrieved
3. Cosine similarity is computed between the prompt embedding and cached embeddings
4. If similarity exceeds the threshold, the cached response is used
5. The best matching response (highest similarity) is returned
### 4. Cache Storage
Cached responses include:
- The response text
- Original prompt
- Message context
- Model information
- Timestamp
- Hit counter
- Optional embedding vector
## Performance Benefits
### Response Time Improvements
- **Exact matches**: ~1-5ms response time (vs 500-5000ms for LLM calls)
- **Semantic matches**: ~10-50ms response time (includes embedding computation)
- **Cache miss**: No performance penalty (parallel caching)
### Cost Savings
- Reduces API calls to external LLM services
- Lowers token consumption for repeated or similar queries
- Efficient memory usage with configurable TTL
## Use Cases
### 1. FAQ Bots
Perfect for bots that answer frequently asked questions where similar queries should return consistent responses.
### 2. Customer Support
Cache responses for common support queries, reducing response time and ensuring consistency.
### 3. Educational Bots
Reuse explanations and educational content for similar learning queries.
### 4. Translation Services
Cache translations for commonly translated phrases and sentences.
## Management
### Viewing Cache Statistics
The cache system provides statistics including:
- Total cache entries
- Total hits across all entries
- Storage size in bytes
- Distribution by model
### Clearing the Cache
To clear the cache programmatically:
- Clear all entries: Remove all cached responses
- Clear by model: Remove cached responses for a specific model
### Monitoring Cache Performance
Monitor these metrics:
- **Hit Rate**: Percentage of requests served from cache
- **Similarity Distribution**: Distribution of similarity scores for semantic matches
- **TTL Effectiveness**: How often entries expire before being used
## Best Practices
1. **Set Appropriate TTL**: Balance between freshness and cache effectiveness
- Short TTL (300-900s) for dynamic content
- Long TTL (3600-86400s) for stable content
2. **Tune Similarity Threshold**: Adjust based on your use case
- Higher threshold (0.95-0.99) for precise matching
- Lower threshold (0.85-0.95) for more flexible matching
3. **Monitor Cache Size**: Ensure Valkey has sufficient memory for your cache needs
4. **Use Semantic Matching Wisely**:
- Enable for conversational bots
- Disable for highly specific or technical queries
5. **Regular Cache Maintenance**: Periodically clear old or unused entries
## Troubleshooting
### Cache Not Working
1. Verify cache (Valkey) is running and accessible
2. Check `llm-cache` is set to `true` in config.csv
3. Ensure sufficient memory is available in Valkey
4. Check logs for connection errors
### Poor Semantic Matching
1. Verify embedding service is running
2. Check embedding model is appropriate for your language/domain
3. Adjust similarity threshold
4. Consider using a better embedding model
### High Memory Usage
1. Reduce TTL values
2. Limit max cache entries
3. Clear cache periodically
4. Monitor cache statistics
## Architecture
### Components
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Bot Module │────▶│ Cached LLM │────▶│ Valkey │
└─────────────┘ │ Provider │ └─────────────┘
└──────────────┘
│
▼
┌──────────────┐ ┌─────────────┐
│ LLM Provider │────▶│ LLM API │
└──────────────┘ └─────────────┘
│
▼
┌──────────────┐ ┌─────────────┐
│ Embedding │────▶│ Embedding │
│ Service │ │ Model │
└──────────────┘ └─────────────┘
```
### Cache Key Structure
```
llm_cache:{bot_id}:{model}:{content_hash}
```
Example:
```
llm_cache:550e8400-e29b-41d4-a716-446655440000:gpt-4:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
```
## Future Enhancements
- **Multi-level Caching**: L1 (memory) and L2 (disk) cache layers
- **Distributed Caching**: Share cache across multiple BotServer instances
- **Smart Eviction**: LRU/LFU strategies for cache management
- **Cache Warming**: Pre-populate cache with common queries
- **Analytics Dashboard**: Visual monitoring of cache performance
- **Compression**: Compress cached responses for memory efficiency

4
docs/src/chapter-03/summary.md
View file

@ -1,6 +1,6 @@
# Chapter 03 – Knowledge‑Base (VectorDB) Documentation Overview
This chapter explains how GeneralBots manages knowledge‑base collections, indexing, caching, and semantic search. The implementation now references a generic **VectorDB** (instead of a specific Qdrant instance) and highlights the use of the **.gbdrive** package for storage when needed.
This chapter explains how GeneralBots manages knowledge‑base collections, indexing, caching, and semantic search. The implementation uses vector databases for semantic search and highlights the use of the **.gbdrive** package for storage when needed.
| Document | File | Description |
|----------|------|-------------|
@ -8,7 +8,7 @@ This chapter explains how GeneralBots manages knowledge‑base collections, inde
| **Caching** | [caching.md](caching.md) | Optional in‑memory and persistent SQLite caching to speed up frequent `FIND` queries. |
| **Context Compaction** | [context-compaction.md](context-compaction.md) | Techniques to keep the LLM context window within limits (summarization, memory pruning, sliding window). |
| **Indexing** | [indexing.md](indexing.md) | Process of extracting, chunking, embedding, and storing document vectors in the VectorDB. |
| **VectorDB Integration** | [qdrant.md](qdrant.md) | (Renamed) Details the VectorDB connection, collection mapping, and operations. References to **Qdrant** have been generalized to **VectorDB**. |
| **Semantic Caching** | [caching.md](caching.md) | Intelligent caching with Valkey for LLM responses, including semantic similarity matching. |
| **Semantic Search** | [semantic-search.md](semantic-search.md) | How the `FIND` keyword performs meaning‑based retrieval using the VectorDB. |
| **Vector Collections** | [vector-collections.md](vector-collections.md) | Definition and management of vector collections, including creation, document addition, and usage in dialogs. |

96
docs/src/chapter-03/vector-collections.md
View file

@ -49,6 +49,61 @@ Documents are indexed automatically when:
- `USE KB` is called for the first time
- The system detects new or modified files
### Indexing Flow
```
.gbkb/policies/
│
├── vacation.pdf
├── handbook.docx
└── rules.txt
│
▼
┌─────────────────────┐
│ File Detection │
│ • New files found │
│ • Hash comparison │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Text Extraction │
│ • PDF → Text │
│ • DOCX → Text │
│ • HTML → Text │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Chunking │
│ • Split by size │
│ • Overlap windows │
│ • ~500 tokens each │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Generate Embeddings│
│ • BGE Model │
│ • 384 dimensions │
│ • Batch processing │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Store in Vector DB │
│ • Vector storage │
│ • Metadata tags │
│ • Collection index │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Ready to Use │
│ USE KB "policies" │
└─────────────────────┘
```
## Website Indexing
To keep web content updated, schedule regular crawls:
@ -71,6 +126,47 @@ When `USE KB` is active:
**Important**: Search happens automatically - you don't need to call any search function. Just activate the KB with `USE KB` and ask questions naturally.
### Search Pipeline
```
"What's the vacation policy?"
│
▼
┌────────────────┐
│ Query Embed │
│ BGE Model │
└───────┬────────┘
│ [0.2, -0.5, 0.8, ...]
▼
┌────────────────┐
│ Vector Search │
│ Vector DB │
│ Cosine Sim │
└───────┬────────┘
│
├─► Match 1: "Vacation days: 15 annually" (0.92)
├─► Match 2: "PTO policy applies to..." (0.87)
└─► Match 3: "Time off requests via..." (0.83)
│
▼
┌──────────────────────┐
│ Context Building │
│ • Top 5 matches │
│ • 2000 tokens max │
│ • Relevance sorted │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ LLM Call │
│ Context + Question │
│ "Based on docs..." │
└──────────┬───────────┘
│
▼
"You get 15 vacation days per year..."
```
## Embeddings Configuration
The system uses BGE embeddings by default:

448
docs/src/chapter-04/console-mode.md
View file

@ -1,392 +1,130 @@
# Console Mode
BotServer includes a powerful terminal-based UI for monitoring, debugging, and managing bots directly from the console.
The BotServer console mode provides a text-based interface for monitoring your bot's operation directly in the terminal.
## Overview
Console mode (`--console`) provides a text-based user interface (TUI) using the terminal for full system control without a web browser.
## Launching Console Mode
## Starting Console Mode
```bash
# Start BotServer with console UI
./botserver --console
# Console with specific bot
./botserver --console --bot edu
# Console with custom refresh rate
./botserver --console --refresh 500
```
## UI Tree Structure
## Console Interface
The console interface uses a tree-based layout for navigation and display:
The console displays real-time information about your running BotServer instance:
```
┌─ BotServer Console ────────────────────────────────┐
│ │
│ ▼ System Status │
│ ├─ CPU: 45% │
│ ├─ Memory: 2.3GB / 8GB │
│ ├─ Uptime: 2d 14h 23m │
│ └─ Active Sessions: 127 │
│ │
│ ▼ Bots │
│ ├─ ● default (8 sessions) │
│ ├─ ● edu (45 sessions) │
│ ├─ ○ crm (offline) │
│ └─ ● announcements (74 sessions) │
│ │
│ ▶ Services │
│ ▶ Logs │
│ ▶ Sessions │
│ │
└─────────────────────────────────────────────────────┘
[q]uit [↑↓]navigate [←→]expand [enter]select [h]elp
```
## Navigation
### Keyboard Controls
| Key | Action |
|-----|--------|
| `↑` `↓` | Navigate up/down |
| `←` `→` | Collapse/expand nodes |
| `Enter` | Select/activate item |
| `Tab` | Switch panels |
| `Space` | Toggle item |
| `q` | Quit console |
| `h` | Show help |
| `f` | Filter/search |
| `r` | Refresh display |
| `/` | Quick search |
| `Esc` | Cancel operation |
### Mouse Support
When terminal supports mouse:
- Click to select items
- Double-click to expand/collapse
- Scroll wheel for navigation
- Right-click for context menu
## Console Components
### System Monitor
Real-time system metrics display:
```
System Resources
├─ CPU
│ ├─ Core 0: 23%
│ ├─ Core 1: 45%
│ ├─ Core 2: 67%
│ └─ Core 3: 12%
├─ Memory
│ ├─ Used: 4.2GB
│ ├─ Free: 3.8GB
│ └─ Swap: 0.5GB
└─ Disk
├─ /: 45GB/100GB
└─ /data: 234GB/500GB
```
### Bot Manager
Interactive bot control panel:
```
Bots Management
├─ default.gbai [RUNNING]
│ ├─ Status: Active
│ ├─ Sessions: 23
│ ├─ Memory: 234MB
│ ├─ Requests/min: 45
│ └─ Actions
│ ├─ [R]estart
│ ├─ [S]top
│ ├─ [C]onfig
│ └─ [L]ogs
```
### Service Dashboard
Monitor all services:
```
Services
├─ Database [✓]
│ ├─ Type: PostgreSQL
│ ├─ Connections: 12/100
│ └─ Response: 2ms
├─ Cache [✓]
│ ├─ Type: Valkey
│ ├─ Memory: 234MB
│ └─ Hit Rate: 94%
├─ Storage [✓]
│ ├─ Type: Drive (S3-compatible)
│ ├─ Buckets: 21
│ └─ Usage: 45GB
└─ Vector DB [✗]
└─ Status: Offline
```
### Session Viewer
Live session monitoring:
```
Active Sessions
├─ Session #4f3a2b1c
│ ├─ User: john@example.com
│ ├─ Bot: edu
│ ├─ Duration: 00:12:34
│ ├─ Messages: 23
│ └─ State: active
├─ Session #8d9e7f6a
│ ├─ User: anonymous
│ ├─ Bot: default
│ ├─ Duration: 00:03:21
│ ├─ Messages: 7
│ └─ State: idle
```
### Log Viewer
Filtered log display with levels:
```
Logs [ERROR|WARN|INFO|DEBUG]
├─ 12:34:56 [INFO] Bot 'edu' started
├─ 12:34:57 [DEBUG] Session created: 4f3a2b1c
├─ 12:34:58 [WARN] Cache miss for key: user_123
├─ 12:35:01 [ERROR] Database connection timeout
│ └─ Details: Connection pool exhausted
├─ 12:35:02 [INFO] Reconnecting to database...
╔════════════════════════════════════════════════════════════╗
║ BotServer Console ║
╠════════════════════════════════════════════════════════════╣
║ Status: Running ║
║ Uptime: 2h 34m 12s ║
║ Port: 8080 ║
║ ║
║ Components: ║
║ PostgreSQL: ✓ Connected ║
║ Valkey: ✓ Connected ║
║ Storage: ✓ Connected ║
║ Vectors: ✓ Connected ║
║ ║
║ Active Sessions: 12 ║
║ Messages Today: 1,234 ║
║ ║
║ Press 'q' to quit, 'r' to refresh ║
╚════════════════════════════════════════════════════════════╝
```
## Console Features
### Real-time Updates
### Status Overview
- Server status (Running/Stopped)
- Uptime counter
- Port information
- Component health checks
- Auto-refresh configurable (100ms - 10s)
- WebSocket-based live data
- Efficient diff rendering
- Smooth scrolling
### Session Information
- Count of active sessions
- Daily message count
- Recent activity indicators
### Interactive Commands
### Component Status
Real-time status of all components:
- Database connectivity
- Cache status
- Storage availability
- Vector database status
## Keyboard Controls
| Key | Action |
|-----|--------|
| `q` | Quit console mode |
| `r` | Force refresh display |
| `c` | Clear console |
| `h` | Show help |
## Console Output
The console provides basic logging output:
```
Commands (press : to enter command mode)
:help Show help
:quit Exit console
:restart <bot> Restart specific bot
:stop <bot> Stop bot
:start <bot> Start bot
:clear Clear screen
:export <file> Export logs
:filter <pattern> Filter display
:connect <session> Connect to session
[2024-01-15 10:23:45] Server started on port 8080
[2024-01-15 10:23:46] Database connected
[2024-01-15 10:23:47] Cache initialized
[2024-01-15 10:23:48] Storage mounted
[2024-01-15 10:24:01] New session: abc123
[2024-01-15 10:24:15] Message processed
```
### BASIC Debugger Integration
## Using Console Mode
Debug BASIC scripts directly in console:
```
BASIC Debugger - enrollment.bas
├─ Breakpoints
│ ├─ Line 12: PARAM validation
│ └─ Line 34: SAVE operation
├─ Variables
│ ├─ name: "John Smith"
│ ├─ email: "john@example.com"
│ └─ course: "Computer Science"
├─ Call Stack
│ ├─ main()
│ ├─ validate_input()
│ └─ > save_enrollment()
└─ Controls
[F5]Run [F10]Step [F11]Into [F9]Break
```
### Development
Console mode is useful during development to monitor:
- Component initialization
- Connection status
- Error messages
- Session activity
### Performance Monitoring
### Production
In production, console mode can help with:
- Quick status checks
- Basic monitoring
- Troubleshooting connection issues
```
Performance Metrics
├─ Response Times
│ ├─ P50: 45ms
│ ├─ P90: 123ms
│ ├─ P95: 234ms
│ └─ P99: 567ms
├─ Throughput
│ ├─ Current: 234 req/s
│ ├─ Average: 189 req/s
│ └─ Peak: 456 req/s
└─ Errors
├─ Rate: 0.02%
└─ Last: 2 min ago
```
## Limitations
## Console Layouts
Console mode provides basic monitoring only. For detailed analytics:
- Check PostgreSQL directly for session data
- Use system logs for detailed error information
- Monitor Valkey for cache statistics
- Review application logs for debugging
### Split Views
## Terminal Requirements
```
┌─ Bots ─────────┬─ Logs ──────────┐
│ │ │
│ ● default │ [INFO] Ready │
│ ● edu │ [DEBUG] Session │
│ │ │
├─ Sessions ─────┼─ Metrics ────────┤
│ │ │
│ 4f3a2b1c │ CPU: 45% │
│ 8d9e7f6a │ RAM: 2.3GB │
│ │ │
└────────────────┴──────────────────┘
```
- Supports any terminal with basic text output
- UTF-8 support recommended for box drawing
- Minimum 80 columns width recommended
- Works over SSH connections
### Focus Mode
## Tips
Press `F` to focus on single component:
```
┌─ Focused: Log Viewer ───────────────┐
│ │
│ 12:35:01 [ERROR] Connection failed │
│ Stack trace: │
│ at connect() line 234 │
│ at retry() line 123 │
│ at main() line 45 │
│ │
│ 12:35:02 [INFO] Retrying... │
│ │
└──────────────────────────────────────┘
[ESC] to exit focus mode
```
## Color Schemes
### Default Theme
- Background: Terminal default
- Text: White
- Headers: Cyan
- Success: Green
- Warning: Yellow
- Error: Red
- Selection: Blue background
### Custom Themes
Configure in `~/.botserver/console.toml`:
```toml
[colors]
background = "#1e1e1e"
foreground = "#d4d4d4"
selection = "#264f78"
error = "#f48771"
warning = "#dcdcaa"
success = "#6a9955"
```
## Console Configuration
### Settings File
`~/.botserver/console.toml`:
```toml
[general]
refresh_rate = 500
mouse_support = true
unicode_borders = true
time_format = "24h"
[layout]
default = "split"
show_tree_lines = true
indent_size = 2
[shortcuts]
quit = "q"
help = "h"
filter = "f"
```
## Performance Considerations
### Terminal Requirements
- Minimum 80x24 characters
- 256 color support recommended
- UTF-8 encoding for borders
- Fast refresh rate capability
### Optimization Tips
- Use `--refresh 1000` for slower terminals
- Disable unicode with `--ascii`
- Limit log tail with `--log-lines 100`
- Filter unnecessary components
## Remote Console
### SSH Access
```bash
# SSH with console auto-start
ssh user@server -t "./botserver --console"
# Persistent session with tmux
ssh user@server -t "tmux attach || tmux new './botserver --console'"
```
### Security
- Read-only mode: `--console-readonly`
- Audit logging of console actions
- Session timeout configuration
- IP-based access control
- Console mode is read-only - it doesn't accept bot commands
- For interactive bot testing, use the web interface at http://localhost:8080
- Console refreshes automatically every few seconds
- Output is buffered for performance
## Troubleshooting
### Console Not Updating
- Check terminal compatibility
- Ensure proper permissions
- Verify components are running
### Display Issues
1. **Garbled characters**
- Set `TERM=xterm-256color`
- Ensure UTF-8 locale
- Try `--ascii` mode
2. **Slow refresh**
- Increase refresh interval
- Reduce displayed components
- Check network latency (remote)
3. **Colors not working**
- Verify terminal color support
- Check TERM environment
- Try different terminal emulator
## Integration with Development Tools
### VSCode Integration
- Terminal panel for console
- Task runner integration
- Debug console connection
### Tmux/Screen
- Persistent console sessions
- Multiple console windows
- Session sharing for collaboration
## Console API
### Programmatic Access
```python
# Python example
from botserver_console import Console
console = Console("localhost:8080")
console.connect()
# Get system stats
stats = console.get_system_stats()
print(f"CPU: {stats.cpu}%")
# Monitor sessions
for session in console.watch_sessions():
print(f"Session {session.id}: {session.state}")
```
- Try a different terminal emulator
- Check terminal encoding (should be UTF-8)
- Resize terminal window if text is cut off
## Summary
Console mode provides a powerful, efficient interface for managing BotServer without leaving the terminal. Perfect for server administration, debugging, and monitoring in headless environments or over SSH connections.
Console mode provides a simple, lightweight way to monitor BotServer status without needing a web browser. It's ideal for quick checks and basic monitoring, but for full functionality, use the web interface.

9
docs/src/chapter-04/desktop-mode.md
View file

@ -352,15 +352,6 @@ location /desktop {
- Valid manifest.json
- Service worker registered
## Future Enhancements
- Native mobile apps (React Native)
- Desktop app (Electron)
- AR/VR interfaces
- Voice-only mode
- Collaborative whiteboards
- Plugin marketplace
## Summary
Desktop mode transforms BotServer from a simple chatbot platform into a comprehensive AI-powered workspace. With mobile PWA support, users can access all features from any device while maintaining a consistent, responsive experience.

452
docs/src/chapter-05/README.md
View file

@ -1,312 +1,230 @@
# BASIC Dialogs
# Chapter 05: BASIC Dialogs
BotServer uses a simplified version of BASIC (Beginner's All-purpose Symbolic Instruction Code) as its primary scripting language for creating conversational flows. This chapter covers everything you need to know about writing BASIC dialogs for your bots.
**Write chatbots like it's 1985.** BotServer uses BASIC - yes, that BASIC - for conversation scripts. Simple English-like commands that anyone can write. No frameworks, no callbacks, no async/await complexity.
## Why BASIC?
BASIC was chosen for BotServer because:
- **Simplicity**: Easy to learn, even for non-programmers
- **Readability**: Clear, English-like syntax
- **Proven**: Decades of use in automation and scripting
- **Extensible**: Easy to add custom keywords
- **Accessible**: No complex programming concepts required
Because `TALK "Hello"` is clearer than `await ctx.send(Message(content="Hello"))`. We chose simplicity over sophistication. Your grandmother could write these scripts.
## Core Concepts
## The 5-Minute Tutorial
### Scripts vs Tools
### Your First Script
**Scripts** (`.bas` files in `.gbdialog/`):
- Define conversation flows
- Handle user interactions
- Manage bot behavior
- Run sequentially
**Tools** (`.bas` files in `.gbdialog/tools/`):
- Callable functions for the LLM
- Reusable logic modules
- Parameter support
- Described for AI understanding
### Execution Model
BASIC scripts in BotServer:
1. Start with `start.bas` for each new session
2. Execute line by line
3. Can call other scripts with `RUN`
4. Can load tools with `USE TOOL`
5. Support event handlers with `ON`
## Language Features
### Variables
Create `start.bas`:
```basic
TALK "Hi! What's your name?"
HEAR name
TALK "Nice to meet you, " + name
```
That's a working chatbot. Three lines.
### Add Knowledge
```basic
USE KB "documentation"
TALK "You can ask me anything about our documentation!"
TALK "What would you like to know?"
HEAR question
```
The bot now has access to your documents and can answer questions about them.
### Add Tools
```basic
USE TOOL "weather"
TALK "I can check the weather for you."
TALK "Which city?"
HEAR location
```
Tools are automatically discovered and can be called by the AI as needed.
## Core Commands
The essential BASIC commands you need:
| Command | Purpose | Example |
|---------|---------|---------|
| TALK | Send message | `TALK "Hello"` |
| HEAR | Get input | `HEAR name` |
| USE KB | Load knowledge | `USE KB "docs"` |
| USE TOOL | Enable function | `USE TOOL "weather"` |
## Real Examples from Templates
### Weather Bot (from default.gbai)
```basic
TALK "I can check the weather for any city."
TALK "Which location?"
HEAR location
USE TOOL "weather"
```
### Email Tool (from default.gbai)
```basic
TALK "I can help you send an email."
TALK "Who would you like to email?"
HEAR recipient
TALK "What's the subject?"
HEAR subject
TALK "What's the message?"
HEAR message
USE TOOL "send-email"
```
## Variables
Simple variable assignment:
```basic
' No declaration needed
name = "John"
age = 25
is_valid = TRUE
' String concatenation
message = "Hello, " + name
' Arrays
items = ["apple", "banana", "orange"]
```
### Control Flow
```basic
' IF statements
IF age >= 18 THEN
TALK "You are an adult"
ELSE
TALK "You are a minor"
END IF
## Conditionals
' FOR loops
FOR i = 1 TO 10
TALK "Count: " + STR(i)
Basic IF/THEN logic:
```basic
HEAR answer
IF answer = "yes" THEN
TALK "Great!"
ELSE
TALK "No problem!"
END IF
```
## Loops
Simple FOR loops:
```basic
FOR i = 1 TO 3
TALK "Count: " + i
NEXT
' FOR EACH loops
FOR EACH item IN items
TALK "Item: " + item
NEXT
' WHILE loops
WHILE counter < 10
counter = counter + 1
WEND
```
### Functions
```basic
FUNCTION CalculateTotal(price, quantity)
total = price * quantity
RETURN total
END FUNCTION
## Session Memory
' Call the function
result = CalculateTotal(10.50, 3)
Store and retrieve session data:
```basic
SET BOT MEMORY "user_name" = name
preference = GET BOT MEMORY "user_name"
```
## Conversation Keywords
## Knowledge Base
### Basic Interaction
- **TALK**: Send message to user
- **HEAR**: Wait for user input
- **WAIT**: Pause execution
### Suggestions
- **ADD SUGGESTION**: Add quick reply button
- **CLEAR SUGGESTIONS**: Remove all buttons
### Knowledge Base
- **USE KB**: Load knowledge base
- **CLEAR KB**: Unload knowledge base
- **FIND**: Search in loaded KBs
### Tools
- **USE TOOL**: Make tool available to LLM
- **CLEAR TOOLS**: Remove all tools
### Memory
- **SET**: Store session variable
- **GET**: Retrieve session variable
- **SET BOT MEMORY**: Store persistent data
- **GET BOT MEMORY**: Retrieve persistent data
### Context
- **SET CONTEXT**: Add context for LLM
- **SET USER**: Set user information
### Scheduling
- **SET SCHEDULE**: Schedule recurring task
### Communication
- **SEND MAIL**: Send email
- **SEND FILE**: Send file attachment
### AI Integration
- **LLM**: Query language model
## Writing Effective Dialogs
### 1. Start Simple
Work with document collections:
```basic
' start.bas - Minimal bot
TALK "Hello! How can I help you?"
answer = HEAR
response = LLM "Answer this question: " + answer
TALK response
USE KB "policies"
USE KB "procedures"
TALK "I now have access to company policies and procedures."
TALK "What would you like to know?"
```
### 2. Add Structure
## Tools from Templates
BotServer includes these ready-to-use tools:
### From default.gbai:
- **weather.vbs** - Get weather for any city
- **send-email.vbs** - Send emails
- **send-sms.vbs** - Send SMS messages
- **translate.vbs** - Translate text
- **calculate.vbs** - Perform calculations
### Usage:
```basic
' start.bas - Structured conversation
CLEAR SUGGESTIONS
ADD SUGGESTION "Sales" AS "sales"
ADD SUGGESTION "Support" AS "support"
ADD SUGGESTION "Other" AS "other"
USE TOOL "weather"
USE TOOL "send-email"
' Tools are now available for the AI to call
```
choice = HEAR "What brings you here today?"
## Bot Examples
IF choice = "sales" THEN
RUN "sales_flow.bas"
ELSE IF choice = "support" THEN
RUN "support_flow.bas"
### Simple Q&A Bot
```basic
USE KB "faq"
TALK "Welcome! I can answer questions from our FAQ."
TALK "What would you like to know?"
loop:
HEAR question
TALK "Let me find that for you..."
GOTO loop
```
### Interactive Assistant
```basic
TALK "Hello! I'm your assistant."
TALK "How can I help you today?"
HEAR request
IF INSTR(request, "weather") > 0 THEN
USE TOOL "weather"
TALK "Which city?"
HEAR city
ELSE IF INSTR(request, "email") > 0 THEN
USE TOOL "send-email"
TALK "I'll help you send an email."
ELSE
RUN "general_help.bas"
TALK "I can help with weather or email."
END IF
```
### 3. Use Context
```basic
' Load relevant information
USE KB "product_catalog"
USE KB "pricing"
## File Structure
' Set context for better responses
user_type = GET "user_type"
SET CONTEXT "customer_type" AS user_type
Your bot's dialog scripts go in the `.gbdialog` folder:
' Now LLM has access to KBs and context
answer = LLM "What products match this need: " + user_request
```
mybot.gbai/
mybot.gbdialog/
start.bas # Entry point
tools/ # Optional tools folder
custom.vbs # Custom tools
```
### 4. Handle Errors
## Writing Tools
Tools are BASIC scripts with parameters:
```basic
TRY
result = CALL_API(endpoint, data)
TALK "Success: " + result
CATCH
TALK "Sorry, something went wrong. Please try again."
LOG ERROR_MESSAGE
END TRY
PARAM name AS STRING
PARAM email AS STRING
DESCRIPTION "Save contact information"
SAVE "contacts.csv", name, email
TALK "Contact saved!"
```
## Best Practices
## Important Notes
### 1. Keep Scripts Focused
Each script should handle one specific flow or feature.
- BASIC is case-insensitive
- Comments start with `'` or `REM`
- Strings use double quotes
- Line continuation with `_`
- No semicolons needed
- No async/await complexity
### 2. Use Meaningful Names
```basic
' Good
customer_name = HEAR "What's your name?"
## Quick Reference
' Bad
x = HEAR "What's your name?"
```
### Essential Keywords
- `TALK` - Output message
- `HEAR` - Get input
- `USE KB` - Load knowledge base
- `USE TOOL` - Load tool
- `SET BOT MEMORY` - Store data
- `GET BOT MEMORY` - Retrieve data
- `IF/THEN/ELSE` - Conditionals
- `FOR/NEXT` - Loops
- `GOTO` - Jump to label
### 3. Add Comments
```basic
' Check if user is authenticated
auth_status = GET SESSION "authenticated"
IF auth_status <> "true" THEN
' Redirect to login flow
RUN "auth.bas"
END IF
```
### 4. Validate Input
```basic
age = HEAR "Please enter your age:"
IF NOT IS_NUMERIC(age) THEN
TALK "Please enter a valid number"
' Ask again
ELSE IF VAL(age) < 0 OR VAL(age) > 120 THEN
TALK "Please enter a realistic age"
END IF
```
### 5. Provide Feedback
```basic
TALK "Processing your request..."
' Long operation
result = PROCESS_DATA()
TALK "Complete! Here's your result: " + result
```
## Common Patterns
### Menu System
```basic
FUNCTION ShowMenu()
CLEAR SUGGESTIONS
ADD SUGGESTION "Option 1" AS "1"
ADD SUGGESTION "Option 2" AS "2"
ADD SUGGESTION "Back" AS "back"
choice = HEAR "Select an option:"
RETURN choice
END FUNCTION
```
### Data Collection
```basic
' Collect user information
name = HEAR "What's your name?"
SET "name", name
email = HEAR "What's your email?"
WHILE NOT IS_VALID_EMAIL(email)
email = HEAR "Please enter a valid email:"
WEND
SET "email", email
```
### Confirmation
```basic
FUNCTION Confirm(message)
CLEAR SUGGESTIONS
ADD SUGGESTION "Yes" AS "yes"
ADD SUGGESTION "No" AS "no"
answer = HEAR message
RETURN answer = "yes"
END FUNCTION
IF Confirm("Do you want to proceed?") THEN
' Continue
ELSE
' Cancel
END IF
```
## Debugging
### Debug Output
```basic
DEBUG "Variable value: " + variable
DEBUG SHOW SESSION
DEBUG SHOW CONTEXT
```
### Logging
```basic
LOG "User selected: " + choice
LOG ERROR "Failed to process: " + error_message
```
### Testing
```basic
' Test mode flag
test_mode = GET BOT MEMORY "test_mode"
IF test_mode = "true" THEN
' Use test data
api_url = "https://test-api.example.com"
ELSE
' Use production data
api_url = "https://api.example.com"
END IF
```
## Next Steps
- [BASIC Syntax Reference](./basics.md) - Complete language reference
- [Keywords Documentation](./keywords.md) - All available keywords
- [Real Examples](./real-basic-examples.md) - Production-ready scripts
- [Templates](./templates.md) - Common dialog templates
### Data Types
- Strings: `"text"`
- Numbers: `42`
- Boolean: True/False
- Variables: Simple assignment with `=`
## Summary
BASIC in BotServer provides a powerful yet simple way to create conversational AI applications. Its English-like syntax, combined with powerful keywords for AI integration, makes it accessible to both programmers and non-programmers alike. Start simple, iterate quickly, and build sophisticated bots without complex code.
BASIC in BotServer brings conversational AI back to simplicity. No complex frameworks, just straightforward commands that read like English. Focus on the conversation, not the code.
Next: [BASIC Keywords Reference](./keywords.md)

99
docs/src/chapter-05/assets/basic-execution-flow.svg Normal file
View file

@ -0,0 +1,99 @@
<svg width="700" height="600" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#888"/>
</marker>
</defs>
<!-- Title -->
<text x="350" y="30" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#CBD5E0">BASIC Script Execution Flow</text>
<!-- start.bas (Raw Text) -->
<rect x="250" y="60" width="200" height="60" fill="none" stroke="#63B3ED" stroke-width="2" rx="8"/>
<text x="350" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#90CDF4">start.bas</text>
<text x="350" y="105" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#CBD5E0">(Raw Text)</text>
<!-- Arrow down -->
<line x1="350" y1="120" x2="350" y2="150" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Tokenizer -->
<rect x="200" y="150" width="300" height="80" fill="none" stroke="#F6AD55" stroke-width="2" rx="8"/>
<text x="350" y="175" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FBD38D">Tokenizer (Rhai)</text>
<text x="350" y="195" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FED7AA">• Split into tokens</text>
<text x="350" y="210" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FED7AA">• Identify keywords</text>
<!-- Arrow down -->
<line x1="350" y1="230" x2="350" y2="260" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Parser -->
<rect x="200" y="260" width="300" height="80" fill="none" stroke="#B794F4" stroke-width="2" rx="8"/>
<text x="350" y="285" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#D6BCFA">Parser (AST)</text>
<text x="350" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">• Build syntax tree</text>
<text x="350" y="320" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#E9D8FD">• Validate structure</text>
<!-- Arrow down -->
<line x1="350" y1="340" x2="350" y2="370" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Keyword Mapping -->
<rect x="200" y="370" width="300" height="80" fill="none" stroke="#48BB78" stroke-width="2" rx="8"/>
<text x="350" y="395" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#68D391">Keyword Mapping</text>
<text x="350" y="415" text-anchor="middle" font-family="monospace" font-size="10" fill="#9AE6B4">TALK → talk_handler</text>
<text x="350" y="430" text-anchor="middle" font-family="monospace" font-size="10" fill="#9AE6B4">HEAR → hear_handler</text>
<!-- Arrow down -->
<line x1="350" y1="450" x2="350" y2="480" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- Runtime Execution -->
<rect x="100" y="480" width="500" height="150" fill="none" stroke="#4A5568" stroke-width="2" rx="10" stroke-dasharray="5,5" opacity="0.6"/>
<text x="350" y="505" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#A0AEC0">Runtime Execution</text>
<!-- Execution boxes inside -->
<g id="execution-flow">
<!-- Line 1: TALK -->
<rect x="140" y="530" width="100" height="40" fill="none" stroke="#63B3ED" stroke-width="1" rx="5"/>
<text x="190" y="545" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#90CDF4">Line 1</text>
<text x="190" y="560" text-anchor="middle" font-family="monospace" font-size="10" fill="#CBD5E0">TALK</text>
<!-- Arrow -->
<line x1="240" y1="550" x2="280" y2="550" stroke="#888" stroke-width="1" marker-end="url(#arrow)"/>
<!-- Line 2: HEAR -->
<rect x="280" y="530" width="100" height="40" fill="none" stroke="#F6AD55" stroke-width="1" rx="5"/>
<text x="330" y="545" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#FBD38D">Line 2</text>
<text x="330" y="560" text-anchor="middle" font-family="monospace" font-size="10" fill="#CBD5E0">HEAR</text>
<!-- Arrow down -->
<line x1="330" y1="570" x2="330" y2="580" stroke="#888" stroke-width="1" marker-end="url(#arrow)"/>
<!-- Line 3: IF/THEN -->
<rect x="280" y="580" width="100" height="40" fill="none" stroke="#B794F4" stroke-width="1" rx="5"/>
<text x="330" y="595" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#D6BCFA">Line 3</text>
<text x="330" y="610" text-anchor="middle" font-family="monospace" font-size="10" fill="#CBD5E0">IF/THEN</text>
<!-- Arrow -->
<line x1="380" y1="600" x2="420" y2="600" stroke="#888" stroke-width="1" marker-end="url(#arrow)"/>
<!-- Line 4: Action -->
<rect x="420" y="580" width="100" height="40" fill="none" stroke="#48BB78" stroke-width="1" rx="5"/>
<text x="470" y="595" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#68D391">Line 4</text>
<text x="470" y="610" text-anchor="middle" font-family="monospace" font-size="10" fill="#CBD5E0">Action</text>
</g>
<!-- Arrow down from Runtime -->
<line x1="350" y1="630" x2="350" y2="660" stroke="#888" stroke-width="2" marker-end="url(#arrow)"/>
<!-- User Response -->
<rect x="250" y="660" width="200" height="60" fill="none" stroke="#FC8181" stroke-width="2" rx="8"/>
<text x="350" y="685" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#FC8181">User Response</text>
<text x="350" y="705" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#FEB2B2">Output/Interaction</text>
<!-- Process steps on the side -->
<g id="process-steps" font-family="Arial, sans-serif" font-size="12" fill="#718096">
<text x="50" y="90" text-anchor="end">1. Source</text>
<text x="50" y="190" text-anchor="end">2. Tokenize</text>
<text x="50" y="300" text-anchor="end">3. Parse</text>
<text x="50" y="410" text-anchor="end">4. Map</text>
<text x="50" y="550" text-anchor="end">5. Execute</text>
<text x="50" y="690" text-anchor="end">6. Output</text>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 6.1 KiB

14
docs/src/chapter-05/basics.md
View file

@ -4,27 +4,29 @@ BASIC dialogs are plain‑text scripts that the GeneralBots engine compiles into
## 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 { … }`).
* **Lines** – Each line is either a command (`TALK`, `HEAR`, etc.) or a comment (`REM` or `'`).
* **Variables** – Simple assignment with `name = value`. Types are inferred at runtime.
* **Control Flow** – `IF … THEN … END IF`, `FOR … NEXT`.
* **Comments** – Start with `REM` or apostrophe `'`.
## Example Script (`start.bas`)
```basic
REM Simple greeting dialog
SET user_name = "Guest"
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
END IF
```
## Execution Model
![BASIC Script Execution Flow](./assets/basic-execution-flow.svg)
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.

110
docs/src/chapter-05/keyword-add-member.md
View file

@ -1,110 +0,0 @@
# ADD MEMBER
Add users to groups or teams within the bot system.
## Syntax
```basic
ADD MEMBER group_id, user_email, role
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `group_id` | String | Unique identifier or name of the group |
| `user_email` | String | Email address of the user to add |
| `role` | String | Role to assign to the user in the group (e.g., "member", "admin", "moderator") |
## Description
The `ADD MEMBER` keyword manages group membership by adding users to specified groups with defined roles. This keyword:
- Validates user existence in the system
- Checks group permissions
- Assigns appropriate role-based access
- Sends notification to the new member
- Updates group analytics
## Examples
### Add Regular Member
```basic
ADD MEMBER "engineering-team", "developer@company.com", "member"
```
### Add Group Administrator
```basic
ADD MEMBER "project-alpha", "manager@company.com", "admin"
```
### Dynamic Group Assignment
```basic
group_name = "support-" + DEPARTMENT
user = GET_USER_EMAIL()
ADD MEMBER group_name, user, "agent"
```
### Bulk Member Addition
```basic
team_members = ["alice@example.com", "bob@example.com", "carol@example.com"]
FOR EACH member IN team_members
ADD MEMBER "dev-team", member, "developer"
NEXT
```
## Return Value
Returns a membership object containing:
- `membership_id`: Unique identifier for the membership
- `group_id`: Group identifier
- `user_id`: User identifier
- `role`: Assigned role
- `joined_at`: Timestamp of when the user was added
- `status`: "active", "pending", or "error"
## Error Handling
- Validates email format before processing
- Checks if user already exists in the group
- Verifies current user has permission to add members
- Returns error if group doesn't exist
- Handles role validation against allowed roles
## Permissions
The user executing this command must have one of the following:
- Group admin privileges
- System administrator role
- Explicit "add_member" permission for the group
## Related Database Tables
- `users`: User information
- `groups`: Group definitions
- `group_members`: Membership associations
- `roles`: Role definitions and permissions
## Best Practices
1. **Verify Permissions**: Always check if the executing user has rights to add members
2. **Validate Roles**: Ensure the role exists and is valid for the group type
3. **Send Notifications**: Notify both the new member and group admins
4. **Audit Trail**: Log all membership changes for compliance
5. **Handle Duplicates**: Check for existing membership before adding
## See Also
- [CREATE TASK](./keyword-create-task.md) - Assign tasks to group members
- [SEND MAIL](./keyword-send-mail.md) - Send group notifications
- [SET USER](./keyword-set-user.md) - Set user context
## Implementation
Located in `src/basic/keywords/add_member.rs`
The implementation uses:
- Database transactions for atomic operations
- Email validation via regex
- Role-based access control (RBAC)
- Async notification dispatch

176
docs/src/chapter-05/keyword-add-suggestion.md
View file

@ -1,176 +0,0 @@
# ADD SUGGESTION
Add conversational suggestions or quick reply options for user interactions.
## Syntax
```basic
ADD SUGGESTION text AS value
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | String | Display text shown to the user |
| `value` | String | Value sent when suggestion is clicked |
## Description
The `ADD SUGGESTION` keyword adds quick reply buttons or suggestion chips to the conversation interface. These provide users with:
- Quick action buttons
- Common response options
- Guided conversation paths
- Menu-like interactions
- Context-aware suggestions
Suggestions appear as clickable elements in supported channels (web, WhatsApp, Teams, etc.).
## Examples
### Basic Suggestions
```basic
ADD SUGGESTION "Yes" AS "confirm"
ADD SUGGESTION "No" AS "decline"
ADD SUGGESTION "Maybe later" AS "postpone"
answer = HEAR "Would you like to proceed?"
```
### Dynamic Suggestions from Data
```basic
departments = ["Sales", "Support", "Billing", "Technical"]
FOR EACH dept IN departments
ADD SUGGESTION dept AS dept
NEXT
selection = HEAR "Which department do you need?"
```
### Context-Based Suggestions
```basic
IF user_type = "new" THEN
ADD SUGGESTION "Get Started" AS "onboarding"
ADD SUGGESTION "View Tutorial" AS "tutorial"
ADD SUGGESTION "Contact Support" AS "help"
ELSE
ADD SUGGESTION "Check Status" AS "status"
ADD SUGGESTION "New Request" AS "create"
ADD SUGGESTION "View History" AS "history"
END IF
```
### Menu System
```basic
' Main menu
CLEAR SUGGESTIONS
ADD SUGGESTION "Products" AS "menu_products"
ADD SUGGESTION "Services" AS "menu_services"
ADD SUGGESTION "Support" AS "menu_support"
ADD SUGGESTION "About Us" AS "menu_about"
choice = HEAR "What would you like to know about?"
IF choice = "menu_products" THEN
CLEAR SUGGESTIONS
ADD SUGGESTION "Pricing" AS "product_pricing"
ADD SUGGESTION "Features" AS "product_features"
ADD SUGGESTION "Compare" AS "product_compare"
ADD SUGGESTION "Back" AS "menu_main"
END IF
```
## Channel Support
| Channel | Display Type | Limitations |
|---------|-------------|-------------|
| Web | Buttons/Chips | Up to 10 suggestions |
| WhatsApp | Reply Buttons | Max 3 buttons |
| Teams | Hero Cards | Unlimited |
| Slack | Block Actions | Up to 5 per block |
| SMS | Numbered List | Text-only fallback |
## Suggestion Persistence
Suggestions remain active until:
- User clicks one
- `CLEAR SUGGESTIONS` is called
- New suggestions replace them
- Conversation ends
- Timeout occurs (configurable)
## Styling and Appearance
Suggestions adapt to channel capabilities:
- **Rich Channels**: Styled buttons with icons
- **Basic Channels**: Numbered text options
- **Voice**: Read as options list
## Return Value
The keyword itself returns `true` if suggestion was added successfully, `false` otherwise.
When user clicks a suggestion, the value is returned to the next `HEAR` command.
## Memory Management
Suggestions are stored in session cache:
- Each session maintains its own suggestion list
- Cleared automatically on session end
- Can store up to 50 suggestions per session
## Best Practices
1. **Clear Before Adding**: Always clear old suggestions when changing context
2. **Limit Options**: Keep to 3-5 suggestions for better UX
3. **Descriptive Text**: Make suggestion text clear and actionable
4. **Meaningful Values**: Use values that are easy to handle in code
5. **Provide Escape**: Always include a "Back" or "Cancel" option
6. **Mobile First**: Consider mobile screen sizes
## Advanced Features
### Suggestion Groups
```basic
' Group related suggestions
ADD SUGGESTION "Small ($10)" AS "size:small"
ADD SUGGESTION "Medium ($15)" AS "size:medium"
ADD SUGGESTION "Large ($20)" AS "size:large"
```
### Conditional Display
```basic
IF has_permission("admin") THEN
ADD SUGGESTION "Admin Panel" AS "admin"
END IF
```
### Localized Suggestions
```basic
language = GET_USER_LANGUAGE()
IF language = "es" THEN
ADD SUGGESTION "Sí" AS "yes"
ADD SUGGESTION "No" AS "no"
ELSE
ADD SUGGESTION "Yes" AS "yes"
ADD SUGGESTION "No" AS "no"
END IF
```
## Error Handling
- Silently fails if suggestion limit exceeded
- Logs warning if value is too long
- Falls back to text input if channel doesn't support suggestions
## Related Keywords
- [CLEAR SUGGESTIONS](./keyword-clear-suggestions.md) - Remove all suggestions
- [HEAR](./keyword-hear.md) - Wait for user input (including suggestion clicks)
- [TALK](./keyword-talk.md) - Send message with suggestions
- [FORMAT](./keyword-format.md) - Format suggestion text
## Implementation
Located in `src/basic/keywords/add_suggestion.rs`
Uses cache component for storage when available, falls back to in-memory storage.

86
docs/src/chapter-05/keyword-book.md
View file

@ -1,86 +0,0 @@
# BOOK
Schedule meetings and calendar events with attendees.
## Syntax
```basic
BOOK attendees, subject, duration
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `attendees` | String/Array | Email address(es) of attendees. Can be a single email or array of emails |
| `subject` | String | Meeting subject/title |
| `duration` | String | Duration of the meeting (e.g., "30m", "1h", "90m") |
## Description
The `BOOK` keyword creates calendar events and schedules meetings with specified attendees. It integrates with the calendar engine to:
- Find available time slots for all attendees
- Create calendar invitations
- Send meeting notifications
- Handle timezone conversions
- Support recurring meetings
## Examples
### Single Attendee Meeting
```basic
BOOK "john@example.com", "Project Review", "30m"
```
### Multiple Attendees
```basic
attendees = ["alice@example.com", "bob@example.com", "carol@example.com"]
BOOK attendees, "Team Standup", "15m"
```
### Dynamic Meeting Scheduling
```basic
email = GET_USER_EMAIL()
BOOK email, "1-on-1 Discussion", "45m"
```
## Integration Points
- **Calendar Engine**: Uses `calendar_engine` module for availability checking
- **Email Notifications**: Sends invitations via email integration
- **User Sessions**: Respects user timezone preferences
- **Meeting Rooms**: Can optionally reserve physical/virtual rooms
## Return Value
Returns a meeting object containing:
- `meeting_id`: Unique identifier for the meeting
- `start_time`: Scheduled start time
- `end_time`: Scheduled end time
- `meeting_link`: Virtual meeting URL (if applicable)
- `status`: Booking status ("confirmed", "tentative", "failed")
## Error Handling
- Returns error if no common availability found
- Validates email addresses before sending invites
- Checks for calendar permissions
- Handles timezone mismatches gracefully
## Best Practices
1. **Check Availability First**: Consider using availability checks for critical meetings
2. **Provide Context**: Include meaningful subject lines
3. **Respect Working Hours**: System checks business hours by default
4. **Handle Conflicts**: Implement retry logic for failed bookings
## See Also
- [CREATE_TASK](./keyword-create-task.md) - Create tasks instead of meetings
- [SET_SCHEDULE](./keyword-set-schedule.md) - Schedule recurring events
- [SEND_MAIL](./keyword-send-mail.md) - Send email notifications
## Implementation
Located in `src/basic/keywords/book.rs`

84
docs/src/chapter-05/keyword-change-theme.md
View file

@ -1,84 +0,0 @@
# CHANGE THEME
## Syntax
```basic
CHANGE THEME theme-name
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| theme-name | String | Name of the CSS theme file (without .css extension) |
## Description
Changes the visual theme of the bot interface by loading a different CSS file from the `.gbtheme` folder. The change applies immediately to all connected users.
## Examples
### Basic Theme Switch
```basic
' Switch to dark mode
CHANGE THEME "dark"
' Back to default
CHANGE THEME "default"
' Retro Windows 95 style
CHANGE THEME "3dbevel"
```
### Conditional Theme
```basic
hour = HOUR(NOW())
IF hour >= 18 OR hour < 6 THEN
CHANGE THEME "dark"
ELSE
CHANGE THEME "light"
END IF
```
### User Preference
```basic
TALK "Which theme would you prefer?"
ADD SUGGESTION "default" AS "Default"
ADD SUGGESTION "dark" AS "Dark Mode"
ADD SUGGESTION "3dbevel" AS "Retro Style"
HEAR choice
CHANGE THEME choice
SET BOT MEMORY "user_theme" AS choice
TALK "Theme changed!"
```
### Seasonal Themes
```basic
month = MONTH(NOW())
IF month = 12 THEN
CHANGE THEME "holiday"
ELSE IF month >= 6 AND month <= 8 THEN
CHANGE THEME "summer"
ELSE
CHANGE THEME "default"
END IF
```
## Notes
- Theme files must be in the `.gbtheme` folder
- Don't include the `.css` extension in the theme name
- Changes apply to all connected users immediately
- If theme file doesn't exist, falls back to default
## Related
- [Chapter 04: gbtheme Reference](../chapter-04/README.md)
- [CSS Customization](../chapter-04/css.md)

4
docs/src/chapter-05/keyword-clear-kb.md
View file

@ -101,7 +101,7 @@ END IF
## Performance Considerations
- Clearing KBs immediately frees session memory
- Does not delete the actual KB from Qdrant
- Does not delete the actual KB from vector database
- Only removes the session association
- Clearing all KBs is faster than clearing individually
@ -138,7 +138,7 @@ END IF
- Clearing only affects the current session
- Other sessions maintain their own KB associations
- KBs remain in Qdrant for future use
- KBs remain in vector database for future use
- Can reload cleared KBs anytime with `USE KB`
## Monitoring Active KBs

223
docs/src/chapter-05/keyword-clear-suggestions.md
View file

@ -1,223 +0,0 @@
# CLEAR SUGGESTIONS
Remove all active suggestions from the current conversation interface.
## Syntax
```basic
CLEAR SUGGESTIONS
```
## Parameters
This keyword takes no parameters.
## Description
The `CLEAR SUGGESTIONS` keyword removes all quick reply buttons and suggestion chips from the user interface. This is useful when you want to:
- Reset the conversation interface
- Change context and provide new options
- Remove outdated suggestions
- Clean up the interface after user selection
## Examples
### Basic Usage
```basic
CLEAR SUGGESTIONS
TALK "All suggestions have been cleared"
```
### Replace Suggestions
```basic
' Clear old suggestions before adding new ones
CLEAR SUGGESTIONS
ADD SUGGESTION "Option A" AS "a"
ADD SUGGESTION "Option B" AS "b"
ADD SUGGESTION "Option C" AS "c"
```
### Context Change
```basic
' Initial menu
ADD SUGGESTION "Sales" AS "sales"
ADD SUGGESTION "Support" AS "support"
choice = HEAR "Select department:"
' Clear and show department-specific options
CLEAR SUGGESTIONS
IF choice = "sales" THEN
ADD SUGGESTION "Pricing" AS "pricing"
ADD SUGGESTION "Demo" AS "demo"
ELSE IF choice = "support" THEN
ADD SUGGESTION "Technical" AS "tech"
ADD SUGGESTION "Billing" AS "billing"
END IF
```
### Clean Interface
```basic
' Show suggestions for initial choice
ADD SUGGESTION "Yes" AS "yes"
ADD SUGGESTION "No" AS "no"
answer = HEAR "Would you like to continue?"
' Clear suggestions after selection
CLEAR SUGGESTIONS
IF answer = "yes" THEN
TALK "Great! Let's proceed..."
ELSE
TALK "No problem. Goodbye!"
END IF
```
### Multi-Level Menu
```basic
FUNCTION ShowMainMenu()
CLEAR SUGGESTIONS
ADD SUGGESTION "Products" AS "products"
ADD SUGGESTION "Services" AS "services"
ADD SUGGESTION "About" AS "about"
ADD SUGGESTION "Exit" AS "exit"
END FUNCTION
FUNCTION ShowProductMenu()
CLEAR SUGGESTIONS
ADD SUGGESTION "Catalog" AS "catalog"
ADD SUGGESTION "Search" AS "search"
ADD SUGGESTION "Back" AS "main"
END FUNCTION
' Usage
ShowMainMenu()
choice = HEAR "What would you like to explore?"
IF choice = "products" THEN
ShowProductMenu()
ELSE IF choice = "exit" THEN
CLEAR SUGGESTIONS
TALK "Thank you for visiting!"
END IF
```
## Channel Support
The effect varies by communication channel:
| Channel | Behavior |
|---------|----------|
| Web | Removes all button/chip elements |
| WhatsApp | Clears reply buttons |
| Teams | Removes suggested actions |
| Slack | Clears interactive elements |
| SMS | No effect (text only) |
## Best Practices
1. **Clear Before Adding**: Always clear old suggestions before adding new ones
```basic
CLEAR SUGGESTIONS
' Add new suggestions here
```
2. **Clear After Selection**: Remove suggestions after user makes a choice
```basic
choice = HEAR "Select an option:"
CLEAR SUGGESTIONS
' Process choice
```
3. **Error Handling**: Clear suggestions when errors occur
```basic
TRY
' Some operation
CATCH
CLEAR SUGGESTIONS
TALK "An error occurred. Please type your request."
END TRY
```
4. **Timeout Handling**: Clear stale suggestions
```basic
ON TIMEOUT
CLEAR SUGGESTIONS
TALK "Session timed out. Please start over."
END ON
```
## Session Management
- Suggestions are session-specific
- Clearing affects only current user's interface
- Suggestions automatically clear when session ends
- No persistence across conversations
## Memory Usage
Clearing suggestions:
- Frees memory allocated for suggestion storage
- Reduces session state size
- Improves performance in long conversations
## Return Value
Returns `true` if suggestions were successfully cleared, `false` if there were no suggestions to clear.
## Error Handling
The keyword handles errors gracefully:
- Succeeds silently if no suggestions exist
- Logs warnings for channel communication errors
- Never throws exceptions
## Use Cases
### Wizard/Step Navigation
```basic
' Step 1
CLEAR SUGGESTIONS
ADD SUGGESTION "Next" AS "step2"
ADD SUGGESTION "Cancel" AS "cancel"
' Step 2
CLEAR SUGGESTIONS
ADD SUGGESTION "Back" AS "step1"
ADD SUGGESTION "Next" AS "step3"
ADD SUGGESTION "Cancel" AS "cancel"
```
### Dynamic Menus
```basic
options = GET_AVAILABLE_OPTIONS(user_role)
CLEAR SUGGESTIONS
FOR EACH option IN options
ADD SUGGESTION option.label AS option.value
NEXT
```
### Conversation Reset
```basic
FUNCTION ResetConversation()
CLEAR SUGGESTIONS
CLEAR KB ALL
SET CONTEXT ""
TALK "Let's start fresh. How can I help you?"
END FUNCTION
```
## Related Keywords
- [ADD SUGGESTION](./keyword-add-suggestion.md) - Add new suggestions
- [HEAR](./keyword-hear.md) - Wait for user input with suggestions
- [TALK](./keyword-talk.md) - Send messages with suggestions
## Implementation
Located in `src/basic/keywords/clear_suggestions.rs`
The implementation:
- Maintains suggestion list in session cache
- Sends clear command to channel adapter
- Updates UI state asynchronously
- Handles multiple channel types

4
docs/src/chapter-05/keyword-create-task.md
View file

@ -38,8 +38,8 @@ CREATE_TASK "Review proposal", "Review and provide feedback on Q4 proposal", "jo
### Task with Current User
```basic
user_email = GET_USER_EMAIL()
CREATE_TASK "Follow up", "Contact customer about renewal", user_email, "tomorrow", "medium"
user_email = GET "user.email"
CREATE TASK "Follow up", "Contact customer about renewal", user_email, "tomorrow", "medium"
```
### Bulk Task Creation

250
docs/src/chapter-05/keyword-find.md
View file

@ -1 +1,251 @@
# FIND
**Search for specific data in storage or knowledge bases.** The FIND keyword performs targeted searches in bot memory, databases, or document collections to locate specific information.
## Syntax
```basic
result = FIND(pattern)
result = FIND(pattern, location)
result = FIND(pattern, location, options)
```
## Parameters
- `pattern` - Search pattern or query string
- `location` - Where to search (optional, defaults to current KB)
- `options` - Search options like case sensitivity, limit (optional)
## Description
FIND searches for data matching a pattern. Unlike semantic search with LLM, FIND does exact or pattern-based matching. Useful for structured data, IDs, specific values.
## Search Locations
### Bot Memory
```basic
' Find in bot's permanent storage
user_data = FIND("user_*", "BOT_MEMORY")
' Returns all keys starting with "user_"
```
### Session Variables
```basic
' Find in current session
form_fields = FIND("form_*", "SESSION")
' Returns all form-related variables
```
### Knowledge Base
```basic
' Find specific documents
policies = FIND("*.pdf", "policies")
' Returns all PDFs in policies collection
```
### Database
```basic
' Find in database tables
orders = FIND("status:pending", "orders")
' Returns pending orders
```
## Examples
### Basic Search
```basic
' Find a specific user
user = FIND("email:john@example.com")
if user
TALK "Found user: " + user.name
else
TALK "User not found"
end
```
### Pattern Matching
```basic
' Find all items matching pattern
items = FIND("SKU-2024-*")
FOR EACH item IN items
TALK item.name + ": " + item.price
END
```
### Multi-Criteria Search
```basic
' Complex search with multiple conditions
results = FIND("type:invoice AND status:unpaid AND date>2024-01-01")
total = 0
FOR EACH invoice IN results
total = total + invoice.amount
END
TALK "Total unpaid: $" + total
```
### Search with Options
```basic
' Limited, case-insensitive search
matches = FIND("john", "customers", {
case_sensitive: false,
limit: 10,
fields: ["name", "email"]
})
```
## Return Values
FIND returns different types based on matches:
- **Single match** - Returns the item directly
- **Multiple matches** - Returns array of items
- **No matches** - Returns null or empty array
- **Error** - Returns null with error in ERROR variable
## Common Patterns
### Check Existence
```basic
exists = FIND("id:" + user_id)
if exists
TALK "User already registered"
else
' Create new user
end
```
### Filter Results
```basic
all_products = FIND("*", "products")
in_stock = []
FOR EACH product IN all_products
if product.quantity > 0
in_stock.append(product)
end
END
```
### Aggregate Data
```basic
sales = FIND("date:" + TODAY(), "transactions")
daily_total = 0
FOR EACH sale IN sales
daily_total = daily_total + sale.amount
END
TALK "Today's sales: $" + daily_total
```
### Search History
```basic
' Find previous conversations
history = FIND("session:" + user_id, "messages", {
sort: "timestamp DESC",
limit: 50
})
TALK "Your last conversation:"
FOR EACH message IN history
TALK message.timestamp + ": " + message.content
END
```
## Performance Tips
### Use Specific Patterns
```basic
' Good - Specific pattern
orders = FIND("order_2024_01_*")
' Bad - Too broad
everything = FIND("*")
```
### Limit Results
```basic
' Get only what you need
recent = FIND("*", "logs", {limit: 100})
```
### Cache Repeated Searches
```basic
' Cache for session
if not cached_products
cached_products = FIND("*", "products")
end
' Use cached_products instead of searching again
```
## Error Handling
```basic
try
results = FIND(user_query)
if results
TALK "Found " + LENGTH(results) + " matches"
else
TALK "No results found"
end
catch error
TALK "Search failed. Please try again."
LOG "FIND error: " + error
end
```
## Comparison with Other Keywords
| Keyword | Purpose | Use When |
|---------|---------|----------|
| FIND | Exact/pattern search | Looking for specific values |
| LLM | Semantic search | Understanding meaning |
| GET | Direct retrieval | Know exact key |
| USE KB | Activate knowledge | Need document context |
## Advanced Usage
### Dynamic Location
```basic
department = GET user.department
data = FIND("*", department + "_records")
```
### Compound Searches
```basic
' Find in multiple places
local = FIND(query, "local_db")
remote = FIND(query, "remote_api")
results = MERGE(local, remote)
```
### Conditional Fields
```basic
search_fields = ["name"]
if advanced_mode
search_fields.append(["email", "phone", "address"])
end
results = FIND(term, "contacts", {fields: search_fields})
```
## Best Practices
✅ **Be specific** - Use precise patterns to avoid large result sets
✅ **Handle empty results** - Always check if FIND returned data
✅ **Use appropriate location** - Search where data actually lives
✅ **Limit when possible** - Don't retrieve more than needed
❌ **Don't search everything** - Avoid FIND("*") without limits
❌ **Don't assume order** - Results may not be sorted unless specified
❌ **Don't ignore errors** - Wrap in try/catch for production
## See Also
- [GET](./keyword-get.md) - Direct key retrieval
- [SET](./keyword-set.md) - Store data
- [USE KB](./keyword-use-kb.md) - Semantic document search
- [LLM](./keyword-llm.md) - AI-powered search

35
docs/src/chapter-05/keyword-llm.md
View file

@ -1,34 +1 @@
# 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.
# LLM

259
docs/src/chapter-05/keyword-remember.md
View file

@ -1,259 +0,0 @@
# REMEMBER
Store information in bot's long-term memory for future conversations.
## Syntax
```basic
REMEMBER key, value
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | String | Memory key/identifier |
| `value` | String | Information to remember |
## Description
The `REMEMBER` keyword stores information persistently across conversations. Unlike session variables that expire, remembered data persists:
- Across multiple conversations
- Between user sessions
- After bot restarts
- Indefinitely until explicitly forgotten
This enables bots to build user profiles, track preferences, and maintain context over time.
## Examples
### Store User Preferences
```basic
name = HEAR "What's your name?"
REMEMBER "user_name", name
TALK "Nice to meet you, " + name + ". I'll remember that!"
```
### Remember User Choices
```basic
language = HEAR "Preferred language? (English/Spanish/French)"
REMEMBER "preferred_language", language
TALK "I'll communicate in " + language + " from now on"
```
### Build User Profile
```basic
REMEMBER "signup_date", TODAY()
REMEMBER "user_tier", "premium"
REMEMBER "last_contact", NOW()
REMEMBER "interaction_count", interaction_count + 1
```
### Store Complex Information
```basic
' Store JSON-like data
preferences = "{theme: 'dark', notifications: true, timezone: 'EST'}"
REMEMBER "user_preferences", preferences
' Store lists
interests = "technology, science, sports"
REMEMBER "interests", interests
```
## Retrieval
Use `RECALL` to retrieve remembered information:
```basic
' In a future conversation
name = RECALL("user_name")
IF name != "" THEN
TALK "Welcome back, " + name + "!"
ELSE
TALK "Hello! I don't think we've met before."
END IF
```
## Memory Scope
Memories are scoped by:
- User ID (each user has separate memory)
- Bot ID (memories don't cross bots)
- Optional namespace (for organizing memories)
## Memory Management
### List All Memories
```basic
memories = GET_ALL_MEMORIES()
FOR EACH memory IN memories
PRINT memory.key + ": " + memory.value
NEXT
```
### Forget Specific Memory
```basic
FORGET "temporary_data"
```
### Clear All Memories
```basic
CLEAR_ALL_MEMORIES()
TALK "Memory wiped clean!"
```
### Memory with Expiration
```basic
' Remember for 30 days
REMEMBER_TEMP "trial_status", "active", 30
```
## Use Cases
### Customer Service
```basic
' Remember customer issues
issue = HEAR "What problem are you experiencing?"
REMEMBER "last_issue", issue
REMEMBER "issue_date", TODAY()
' In follow-up conversation
last_issue = RECALL("last_issue")
IF last_issue != "" THEN
TALK "Following up on your issue: " + last_issue
END IF
```
### Personal Assistant
```basic
' Remember important dates
birthday = HEAR "When is your birthday?"
REMEMBER "birthday", birthday
' Check on birthday
IF TODAY() = RECALL("birthday") THEN
TALK "Happy Birthday! 🎉"
END IF
```
### Learning System
```basic
' Track user corrections
correction = HEAR "Actually, that's not correct..."
REMEMBER "correction_" + topic, correction
corrections_count = RECALL("total_corrections") + 1
REMEMBER "total_corrections", corrections_count
```
### Preferences Tracking
```basic
' Remember communication preferences
IF time_of_day = "morning" AND response_time < 5 THEN
REMEMBER "active_time", "morning"
END IF
preferred_channel = GET_CHANNEL()
REMEMBER "preferred_channel", preferred_channel
```
## Performance Considerations
- Memories are indexed for fast retrieval
- Large values (>1MB) should be stored as files
- Frequently accessed memories are cached
- Memory operations are asynchronous
## Privacy and Security
### Data Protection
- Memories are encrypted at rest
- PII should be marked as sensitive
- Comply with data retention policies
- Support user data deletion requests
### GDPR Compliance
```basic
' Allow users to export their data
IF request = "export_my_data" THEN
data = EXPORT_USER_MEMORIES()
SEND_MAIL user_email, "Your Data", data
END IF
' Allow users to delete their data
IF request = "forget_me" THEN
DELETE_USER_MEMORIES()
TALK "Your data has been deleted"
END IF
```
## Best Practices
1. **Use descriptive keys**: Make memory keys self-documenting
2. **Validate before storing**: Check data quality
3. **Handle missing memories**: Always check if memory exists
4. **Organize with namespaces**: Group related memories
5. **Clean up old data**: Remove outdated memories
6. **Respect privacy**: Ask permission for sensitive data
7. **Document memories**: Keep track of what's stored
## Advanced Features
### Structured Memory
```basic
' Store structured data
user_profile = CREATE_MAP()
user_profile["name"] = name
user_profile["age"] = age
user_profile["interests"] = interests
REMEMBER "profile", JSON_STRINGIFY(user_profile)
' Retrieve and parse
profile_json = RECALL("profile")
profile = JSON_PARSE(profile_json)
```
### Memory Search
```basic
' Search memories by pattern
matching_memories = SEARCH_MEMORIES("pref_*")
FOR EACH mem IN matching_memories
PRINT mem.key + ": " + mem.value
NEXT
```
### Memory Analytics
```basic
' Track memory usage
stats = GET_MEMORY_STATS()
PRINT "Total memories: " + stats.count
PRINT "Storage used: " + stats.size_mb + "MB"
PRINT "Oldest memory: " + stats.oldest_date
```
## Error Handling
```basic
TRY
REMEMBER "important_data", data
CATCH "storage_full"
' Clean up old memories
DELETE_OLD_MEMORIES(30) ' Delete memories older than 30 days
RETRY
CATCH "invalid_data"
LOG "Cannot store invalid data"
END TRY
```
## Related Keywords
- [GET_BOT_MEMORY](./keyword-get-bot-memory.md) - Session-scoped memory
- [SET_BOT_MEMORY](./keyword-set-bot-memory.md) - Temporary memory
- [SET_USER](./keyword-set-user.md) - Set user context
- [SET_CONTEXT](./keyword-set-context.md) - Set conversation context
## Implementation
Located in `src/basic/keywords/remember.rs`
Uses persistent storage (PostgreSQL) with caching layer (cache component) for performance.

255
docs/src/chapter-05/keyword-save-from-unstructured.md
View file

@ -1,255 +0,0 @@
# SAVE_FROM_UNSTRUCTURED
Extract and save structured data from unstructured text content.
## Syntax
```basic
SAVE_FROM_UNSTRUCTURED text, schema, destination
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | String | Unstructured text to process |
| `schema` | String | Schema name or definition for extraction |
| `destination` | String | Where to save extracted data (table, file, variable) |
## Description
The `SAVE_FROM_UNSTRUCTURED` keyword uses AI to extract structured information from free-form text like emails, documents, conversations, or web content. It:
- Identifies relevant data points
- Validates against schema
- Transforms to structured format
- Saves to specified destination
- Handles various text formats
## Examples
### Extract Contact Information
```basic
email_text = "Hi, I'm John Smith from Acme Corp. You can reach me at john@acme.com or 555-1234."
SAVE_FROM_UNSTRUCTURED email_text, "contact_schema", "contacts_table"
' Extracts: name, company, email, phone
```
### Process Invoice Data
```basic
invoice_text = GET_FILE_CONTENT("invoice.pdf")
SAVE_FROM_UNSTRUCTURED invoice_text, "invoice_schema", "invoices_db"
' Extracts: invoice_number, date, amount, items, tax
```
### Extract Meeting Notes
```basic
transcript = "Meeting on Jan 15. Present: Alice, Bob. Discussed Q1 targets of $1M. Action: Bob to prepare report by Friday."
SAVE_FROM_UNSTRUCTURED transcript, "meeting_schema", meeting_data
' Extracts: date, attendees, topics, actions, deadlines
```
### Parse Customer Feedback
```basic
review = HEAR "Please tell us about your experience"
SAVE_FROM_UNSTRUCTURED review, "feedback_schema", "reviews_table"
' Extracts: sentiment, rating, issues, suggestions
```
## Schema Definition
### Predefined Schemas
Common schemas available out-of-the-box:
- `contact_schema` - Name, email, phone, company
- `address_schema` - Street, city, state, zip, country
- `invoice_schema` - Number, date, items, amounts
- `meeting_schema` - Date, attendees, agenda, actions
- `feedback_schema` - Sentiment, topics, ratings
- `resume_schema` - Skills, experience, education
- `product_schema` - Name, price, features, specs
### Custom Schema
```basic
' Define custom extraction schema
schema = {
"fields": [
{"name": "customer_id", "type": "string", "required": true},
{"name": "issue_type", "type": "enum", "values": ["billing", "technical", "other"]},
{"name": "priority", "type": "enum", "values": ["low", "medium", "high"]},
{"name": "description", "type": "string"}
]
}
SAVE_FROM_UNSTRUCTURED support_ticket, schema, "tickets_table"
```
## Destinations
### Database Table
```basic
SAVE_FROM_UNSTRUCTURED text, "schema", "table_name"
' Saves to database table
```
### Variable
```basic
SAVE_FROM_UNSTRUCTURED text, "schema", extracted_data
' Saves to variable for further processing
```
### File
```basic
SAVE_FROM_UNSTRUCTURED text, "schema", "output.json"
' Saves as JSON file
```
### Multiple Destinations
```basic
' Extract once, save multiple places
data = EXTRACT_STRUCTURED(text, "schema")
SAVE_TO_DB data, "table"
SAVE_TO_FILE data, "backup.json"
SEND_TO_API data, "https://api.example.com/data"
```
## Return Value
Returns extraction result object:
- `success`: Boolean indicating success
- `extracted_count`: Number of records extracted
- `data`: Extracted structured data
- `confidence`: Extraction confidence score (0-1)
- `errors`: Any validation errors
## Advanced Features
### Batch Processing
```basic
documents = GET_ALL_FILES("inbox/*.txt")
FOR EACH doc IN documents
SAVE_FROM_UNSTRUCTURED doc.content, "contract_schema", "contracts_table"
NEXT
```
### Validation Rules
```basic
schema_with_rules = {
"fields": [...],
"validation": {
"email": "must be valid email",
"phone": "must be 10 digits",
"amount": "must be positive number"
}
}
SAVE_FROM_UNSTRUCTURED text, schema_with_rules, destination
```
### Confidence Threshold
```basic
result = SAVE_FROM_UNSTRUCTURED text, schema, destination, min_confidence=0.8
IF result.confidence < 0.8 THEN
' Manual review needed
SEND_FOR_REVIEW text, result
END IF
```
### Multi-Language Support
```basic
' Process text in different languages
spanish_text = "Nombre: Juan, Teléfono: 555-1234"
SAVE_FROM_UNSTRUCTURED spanish_text, "contact_schema", "contacts", language="es"
```
## Use Cases
### CRM Data Entry
```basic
' Auto-populate CRM from emails
email = GET_LATEST_EMAIL()
SAVE_FROM_UNSTRUCTURED email.body, "lead_schema", "crm_leads"
TALK "New lead added to CRM"
```
### Document Processing
```basic
' Process uploaded documents
document = UPLOAD_FILE()
text = EXTRACT_TEXT(document)
SAVE_FROM_UNSTRUCTURED text, detect_schema(document.type), "documents_db"
```
### Form Automation
```basic
' Convert free-text to form submission
user_input = HEAR "Describe your issue"
SAVE_FROM_UNSTRUCTURED user_input, "ticket_schema", "support_tickets"
ticket_id = GET_LAST_INSERT_ID()
TALK "Ticket #" + ticket_id + " created"
```
### Data Migration
```basic
' Migrate unstructured data to structured database
old_notes = GET_LEGACY_NOTES()
FOR EACH note IN old_notes
SAVE_FROM_UNSTRUCTURED note, "modern_schema", "new_database"
NEXT
```
## Error Handling
```basic
TRY
SAVE_FROM_UNSTRUCTURED text, schema, destination
CATCH "invalid_schema"
LOG "Schema validation failed"
CATCH "extraction_failed"
LOG "Could not extract required fields"
' Fall back to manual processing
CREATE_MANUAL_TASK text
CATCH "save_failed"
LOG "Database save failed"
' Save to backup location
SAVE_TO_FILE text, "failed_extractions.log"
END TRY
```
## Performance Considerations
- Large texts are processed in chunks
- Extraction is cached for identical inputs
- Schema validation happens before AI processing
- Batch operations are optimized
- Background processing for large datasets
## Best Practices
1. **Define clear schemas**: Be specific about expected fields
2. **Validate important data**: Add validation rules for critical fields
3. **Set confidence thresholds**: Require human review for low confidence
4. **Handle errors gracefully**: Have fallback procedures
5. **Test with samples**: Verify extraction accuracy
6. **Monitor performance**: Track extraction success rates
7. **Document schemas**: Keep schema documentation updated
8. **Version schemas**: Track schema changes over time
## Limitations
- Accuracy depends on text quality
- Complex nested structures may need preprocessing
- Very long texts may need chunking
- Ambiguous data requires human review
- Processing time increases with text length
## Related Keywords
- [GET](./keyword-get.md) - Fetch unstructured content
- [FIND](./keyword-find.md) - Search extracted data
- [FORMAT](./keyword-format.md) - Format extracted data
- [LLM](./keyword-llm.md) - Process with language model
## Implementation
Located in `src/basic/keywords/save_from_unstructured.rs`
Uses LLM for intelligent extraction with schema validation and multiple storage backends.

4
docs/src/chapter-05/keyword-send-mail.md
View file

@ -95,9 +95,9 @@ END ON
### Bulk Email with Personalization
```basic
subscribers = GET_SUBSCRIBERS()
subscribers = GET "subscribers.list"
FOR EACH email IN subscribers
name = GET_USER_NAME(email)
name = GET "user.name"
body = "Dear " + name + ", here's your weekly update..."
SEND MAIL email, "Weekly Newsletter", body
WAIT 1 ' Rate limiting

1
docs/src/chapter-05/keyword-set-context.md
View file

@ -59,7 +59,6 @@ TALK "Support mode activated. Please describe your issue."
## Related Keywords
- [`SET_USER`](keyword-set-user.md) — Defines the active user for the session.
- [`SET_BOT_MEMORY`](keyword-set-bot-memory.md) — Stores persistent data for the bot or user.
- [`GET_BOT_MEMORY`](keyword-get-bot-memory.md) — Retrieves stored memory entries.
- [`SET_SCHEDULE`](keyword-set-schedule.md) — Defines scheduled tasks that may depend on context.

70
docs/src/chapter-05/keyword-set-user.md
View file

@ -1,69 +1 @@
# SET_USER Keyword
The **SET_USER** keyword defines the active user context for the current bot session.
It associates all subsequent actions, memory entries, and responses with a specific user identity.
---
## Syntax
```basic
SET_USER "user-id"
```
---
## Parameters
- `"user-id"` — A unique identifier (UUID or username) representing the user.
This value is used to link session data, memory, and logs to the correct user record.
---
## Description
`SET_USER` updates the bot’s internal session to reflect the specified user identity.
This is typically used after authentication or when switching between users in multi-user environments.
Once set, all commands such as `SET_CONTEXT`, `SET_BOT_MEMORY`, and `FIND` operate within the scope of that user.
If the user ID does not exist in the database, the system automatically creates a new user record.
The command ensures that the session token and memory cache are properly synchronized.
---
## Example
```basic
' Set the active user for the session
SET_USER "john_doe"
' Store personalized memory
SET_BOT_MEMORY "preferred_language" "English"
' Retrieve user-specific data
FIND "recent orders"
```
---
## Implementation Notes
- Implemented in Rust under `src/session/mod.rs` and `src/org/mod.rs`.
- The keyword interacts with the session manager to update the active user ID.
- It ensures that all subsequent operations are scoped to the correct user context.
- If cache component or database caching is enabled, the user ID is stored for persistence across sessions.
---
## Related Keywords
- [`SET_CONTEXT`](keyword-set-context.md) — Defines the operational context for the session.
- [`SET_BOT_MEMORY`](keyword-set-bot-memory.md) — Stores persistent data for the bot or user.
- [`GET_BOT_MEMORY`](keyword-get-bot-memory.md) — Retrieves stored memory entries.
---
## Summary
`SET_USER` is essential for maintaining user-specific state and personalization in GeneralBots.
It ensures that each session operates independently and securely under the correct user identity.
# SET USER

2
docs/src/chapter-05/keyword-set.md
View file

@ -252,8 +252,6 @@ SET big_data = null ' Free memory
- [HEAR](./keyword-hear.md) - Get user input into variable
- [FORMAT](./keyword-format.md) - Format values for assignment
- [SET_BOT_MEMORY](./keyword-set-bot-memory.md) - Persistent storage
- [SET_USER](./keyword-set-user.md) - Set user context
## Implementation Notes
Variables are stored in the BASIC engine's scope map and persist for the duration of the dialog execution. The `SET` keyword is syntactic sugar - the parser treats both `SET x = y` and `x = y` identically.

288
docs/src/chapter-05/keyword-use-kb.md
View file

@ -1 +1,289 @@
# USE KB
**Activate a knowledge base for semantic search.** The USE KB keyword loads a document collection from `.gbkb/` folders, making it available for the LLM to search and reference when answering questions.
## Syntax
```basic
USE KB collection_name
USE KB "collection_name"
```
## Parameters
- `collection_name` - Name of the folder inside `.gbkb/` to activate
## Description
USE KB activates a knowledge base collection for the current session. Once activated, the LLM automatically searches this collection when generating responses, finding relevant information without explicit search commands.
## How It Works
1. **Collection Loading**: Reads documents from `.gbkb/collection_name/`
2. **Vector Search**: Finds semantically similar content to user queries
3. **Context Injection**: Adds relevant chunks to LLM context
4. **Automatic**: No explicit search needed - happens behind the scenes
## Examples
### Basic Usage
```basic
USE KB "policies"
' Now the bot can answer questions about policies
answer = HEAR
' Knowledge is automatically available to the conversation
TALK "Let me search the policies for: " + answer
```
### Multiple Collections
```basic
USE KB "products"
USE KB "pricing"
USE KB "support"
' All three collections are now searchable
```
### Conditional Loading
```basic
department = GET user_department
if department == "HR"
USE KB "hr_policies"
else if department == "IT"
USE KB "it_documentation"
else
USE KB "general"
end
```
### Dynamic Collection Names
```basic
topic = HEAR
USE KB topic ' Load collection based on user input
```
## Collection Structure
Knowledge bases are organized as folders:
```
bot.gbkb/
├── policies/
│ ├── vacation-policy.pdf
│ ├── code-of-conduct.docx
│ └── employee-handbook.txt
├── products/
│ ├── catalog-2024.pdf
│ └── specifications.xlsx
└── support/
├── faq.md
└── troubleshooting.pdf
```
Each folder becomes a named collection accessible via USE KB.
## Supported File Types
- **PDF** - Automatic text extraction
- **DOCX/DOC** - Word documents
- **TXT** - Plain text files
- **MD** - Markdown files
- **HTML** - Web pages
- **CSV** - Structured data
- **JSON** - Configuration and data files
## Search Behavior
When USE KB is active:
1. **User asks**: "What's the vacation policy?"
2. **System searches**: Finds relevant chunks in policies collection
3. **Context built**: Adds top 5 matching chunks to context
4. **LLM responds**: Uses found information to answer accurately
## Managing Active Collections
### View Active Collections
```basic
collections = LIST_KB()
TALK "Active KBs: " + collections
```
### Clear Specific Collection
```basic
CLEAR KB "policies"
' Policies collection no longer searched
```
### Clear All Collections
```basic
CLEAR KB
' All collections deactivated
```
## Performance Considerations
### Memory Usage
Each collection uses ~50MB RAM when active. Load only what's needed:
```basic
' Good - Load for specific task
USE KB "troubleshooting"
' ... handle support issue ...
CLEAR KB "troubleshooting"
' Bad - Load everything
USE KB "collection1"
USE KB "collection2"
USE KB "collection3"
' ... memory intensive ...
```
### Search Speed
- First search: 100-200ms (cold cache)
- Subsequent: 20-50ms (warm cache)
- More collections = slower search
## Advanced Usage
### Scoped Knowledge
```basic
' Customer service flow
ON "customer_service"
USE KB "products"
USE KB "policies"
USE KB "returns"
END
' Technical support flow
ON "tech_support"
CLEAR KB
USE KB "documentation"
USE KB "known_issues"
END
```
### Dynamic Reloading
```basic
' Refresh collection with new documents
CLEAR KB "news"
ADD WEBSITE "https://example.com/news"
USE KB "news"
```
### Collection Validation
```basic
try
USE KB user_requested_collection
catch error
TALK "Sorry, that knowledge base doesn't exist"
collections = LIST_AVAILABLE_KB()
TALK "Available: " + collections
end
```
## Integration with Other Keywords
### With SET CONTEXT
```basic
USE KB "technical_docs"
SET CONTEXT "You are a technical expert" AS prompt
' LLM now searches technical docs with expert perspective
```
### With USE TOOL
```basic
USE KB "inventory"
USE TOOL "check_stock"
' Tool can access inventory knowledge when executing
```
### With ADD WEBSITE
```basic
ADD WEBSITE "https://docs.example.com" TO "documentation"
USE KB "documentation"
' Fresh web content now searchable
```
## Best Practices
### Do's
✅ Load collections relevant to conversation topic
✅ Clear unused collections to save memory
✅ Organize documents into logical collections
✅ Use descriptive collection names
### Don'ts
❌ Don't load all collections at once
❌ Don't assume collections exist - handle errors
❌ Don't mix unrelated documents in one collection
❌ Don't forget to clear when switching contexts
## Common Patterns
### Role-Based Knowledge
```basic
role = GET user_role
switch role
case "manager"
USE KB "management"
USE KB "reports"
case "developer"
USE KB "documentation"
USE KB "apis"
case "customer"
USE KB "products"
USE KB "support"
end
```
### Time-Based Collections
```basic
month = GET_MONTH()
USE KB "updates_" + month
' Load current month's updates
```
### Fallback Strategy
```basic
primary_kb = "detailed_docs"
fallback_kb = "general_info"
try
USE KB primary_kb
catch
USE KB fallback_kb
TALK "Using general information"
end
```
## Error Handling
Common errors and solutions:
**Collection not found**
```basic
Error: Knowledge base 'unknown' not found
Solution: Check collection exists in .gbkb/ folder
```
**Empty collection**
```basic
Warning: Collection 'new' has no documents
Solution: Add documents to the folder
```
**Index not ready**
```basic
Info: Indexing collection 'large'...
Solution: Wait for indexing to complete (automatic)
```
## See Also
- [CLEAR KB](./keyword-clear-kb.md) - Deactivate knowledge bases
- [ADD WEBSITE](./keyword-add-website.md) - Add web content to KB
- [Knowledge Base Guide](../chapter-03/README.md) - Complete KB documentation
- [Vector Collections](../chapter-03/vector-collections.md) - How collections work

264
docs/src/chapter-05/keyword-weather.md
View file

@ -1,264 +0,0 @@
# WEATHER
Get current weather information for any location.
## Syntax
```basic
WEATHER location
```
## Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `location` | String | City name, coordinates, or zip code |
## Description
The `WEATHER` keyword retrieves real-time weather information from weather services. It provides:
- Current temperature
- Weather conditions
- Humidity and pressure
- Wind speed and direction
- Feels-like temperature
- Forecast data
## Examples
### Basic Weather Query
```basic
weather = WEATHER "New York"
TALK weather
```
### Weather with User Location
```basic
city = HEAR "What city are you in?"
current_weather = WEATHER city
TALK "The weather in " + city + " is: " + current_weather
```
### Conditional Weather Responses
```basic
weather_data = WEATHER "London"
temp = EXTRACT_TEMP(weather_data)
IF temp < 10 THEN
TALK "It's cold in London (" + temp + "°C). Bundle up!"
ELSE IF temp > 25 THEN
TALK "It's warm in London (" + temp + "°C). Perfect for outdoor activities!"
ELSE
TALK "Mild weather in London: " + temp + "°C"
END IF
```
### Multiple Location Weather
```basic
cities = ["Tokyo", "Paris", "Sydney", "Cairo"]
FOR EACH city IN cities
weather = WEATHER city
TALK city + ": " + weather
WAIT 1
NEXT
```
## Return Format
The keyword returns a formatted string with weather details:
```
"New York: 72°F (22°C), Partly Cloudy, Humidity: 65%, Wind: 10 mph NW"
```
For programmatic access, use the extended version:
```basic
data = WEATHER_DATA "San Francisco"
' Returns object with properties:
' data.temperature
' data.condition
' data.humidity
' data.wind_speed
' data.wind_direction
' data.pressure
' data.feels_like
```
## Location Formats
Supported location formats:
- City name: `"Paris"`
- City, Country: `"Paris, France"`
- Coordinates: `"48.8566, 2.3522"`
- Zip/Postal code: `"10001"` (US), `"SW1A 1AA"` (UK)
- Airport code: `"LAX"`
## Configuration
Configure weather service in `config.csv`:
```csv
weatherApiKey,your-api-key
weatherProvider,openweather
weatherUnits,metric
weatherLanguage,en
```
Supported providers:
- OpenWeather
- WeatherAPI
- AccuWeather
- DarkSky (legacy)
## Error Handling
```basic
TRY
weather = WEATHER location
TALK weather
CATCH "location_not_found"
TALK "I couldn't find weather for " + location
CATCH "api_error"
TALK "Weather service is temporarily unavailable"
CATCH "rate_limit"
TALK "Too many weather requests. Please try again later."
END TRY
```
## Advanced Usage
### Weather Alerts
```basic
alerts = WEATHER_ALERTS "Miami"
IF alerts != "" THEN
TALK "⚠️ Weather Alert: " + alerts
END IF
```
### Forecast
```basic
' Get 5-day forecast
forecast = WEATHER_FORECAST "Seattle", 5
FOR EACH day IN forecast
TALK day.date + ": " + day.high + "/" + day.low + " - " + day.condition
NEXT
```
### Historical Weather
```basic
' Get weather for specific date
historical = WEATHER_HISTORY "Chicago", "2024-01-15"
TALK "Weather on Jan 15: " + historical
```
### Weather Comparison
```basic
city1_weather = WEATHER_DATA "Los Angeles"
city2_weather = WEATHER_DATA "New York"
temp_diff = city1_weather.temperature - city2_weather.temperature
TALK "LA is " + ABS(temp_diff) + " degrees " +
IF(temp_diff > 0, "warmer", "cooler") + " than NYC"
```
## Caching
Weather data is cached to reduce API calls:
- Current weather: 10 minutes
- Forecast: 1 hour
- Historical: 24 hours
Force refresh with:
```basic
fresh_weather = WEATHER location, refresh=true
```
## Localization
Weather descriptions are localized based on user language:
```basic
SET_LANGUAGE "es"
weather = WEATHER "Madrid"
' Returns: "Madrid: 25°C, Parcialmente nublado..."
```
## Units
Temperature units based on configuration or override:
```basic
' Force Fahrenheit
weather_f = WEATHER "Toronto", units="imperial"
' Force Celsius
weather_c = WEATHER "Toronto", units="metric"
```
## Integration Examples
### Travel Assistant
```basic
destination = HEAR "Where are you traveling to?"
weather = WEATHER destination
TALK "Current weather at " + destination + ": " + weather
IF weather CONTAINS "rain" THEN
TALK "Don't forget an umbrella!"
ELSE IF weather CONTAINS "snow" THEN
TALK "Pack warm clothes and boots!"
END IF
```
### Event Planning
```basic
event_date = HEAR "When is your event?"
location = HEAR "Where will it be held?"
forecast = WEATHER_FORECAST location, event_date
IF forecast CONTAINS "rain" OR forecast CONTAINS "storm" THEN
TALK "Consider an indoor venue - rain is expected"
ELSE
TALK "Weather looks good for an outdoor event!"
END IF
```
### Agriculture Bot
```basic
farm_location = "Iowa"
weather_data = WEATHER_DATA farm_location
IF weather_data.temperature < 32 THEN
TALK "Frost warning! Protect sensitive crops"
END IF
IF weather_data.humidity < 30 THEN
TALK "Low humidity - increase irrigation"
END IF
```
## Performance Tips
1. **Cache responses**: Avoid repeated API calls
2. **Batch requests**: Get multiple locations at once
3. **Use coordinates**: More accurate than city names
4. **Handle timeouts**: Set reasonable timeout values
5. **Rate limit**: Respect API limits
## Limitations
- Requires valid API key
- Subject to rate limits
- Accuracy depends on provider
- Some locations may not be available
- Historical data may be limited
## Related Keywords
- [GET](./keyword-get.md) - Fetch data from URLs
- [SET_SCHEDULE](./keyword-set-schedule.md) - Schedule weather updates
- [FORMAT](./keyword-format.md) - Format weather display
## Implementation
Located in `src/basic/keywords/weather.rs`
Integrates with multiple weather API providers and includes fallback mechanisms.

87
docs/src/chapter-05/templates.md
View file

@ -1,77 +1,24 @@
# Templates System
# Template Examples
The **Templates** directory is the foundation for the `templates.html` interface in GeneralBots.
It contains all official `.gbai` template packages used to generate bot dialogs, announcements, and default automation flows.
For template examples and detailed documentation, please see [Chapter 2: Templates](../chapter-02/templates.md).
---
## Available Templates
## Overview
BotServer includes 21 pre-built templates in the `templates/` directory:
Templates define reusable bot configurations, dialog flows, and knowledge bases.
Each template package is stored under the `templates/` directory and follows a consistent structure:
- **default.gbai** - Basic bot with weather, email, and calculation tools
- **edu.gbai** - Educational bot for course management
- **crm.gbai** - Customer relationship management
- **announcements.gbai** - Broadcast messaging system
- **whatsapp.gbai** - WhatsApp Business integration
- And many more...
```
templates/
├── default.gbai/
│ ├── default.gbot/
│ ├── default.gbdialog/
│ └── default.gbkb/
└── announcements.gbai/
├── announcements.gbot/
├── announcements.gbdialog/
└── announcements.gbkb/
```
## Using Templates
Each `.gbai` folder represents a **template group**, containing:
- `.gbdialog/` — BASIC dialog scripts defining conversational flows.
- `.gbkb/` — Knowledge base files used for contextual responses.
- `.gbot/` — Bot configuration files defining behavior and metadata.
Templates provide ready-to-use bot configurations. Each template includes:
- Dialog scripts (`.gbdialog`)
- Knowledge bases (`.gbkb`)
- Configuration (`.gbot`)
- Optional themes (`.gbtheme`)
---
## Template Groups
### `default.gbai`
The **Default Template** provides the base configuration for new bots and general automation.
It includes standard dialogs, system prompts, and basic workflows used across all bots.
**Contents:**
- `default.gbot/` — Core bot configuration.
- `default.gbdialog/` — Default dialog scripts (e.g., greetings, help, onboarding).
- `default.gbkb/` — Default knowledge base entries.
**Purpose:**
Used as the starting point for new bot instances and as the fallback template when no specific configuration is provided.
---
### `announcements.gbai`
The **Announcements Template** defines dialogs and content for broadcasting messages or system updates.
It is used by bots that handle notifications, alerts, or scheduled announcements.
**Contents:**
- `announcements.gbot/` — Announcement bot configuration.
- `announcements.gbdialog/` — Dialog scripts for announcement delivery.
- `announcements.gbkb/` — Knowledge base entries related to announcements.
**Purpose:**
Used for bots that send periodic updates, news, or system-wide messages.
---
## Implementation Notes
- Templates are modular and can be extended by adding new `.gbai` folders.
- Each template group must include at least one `.gbdialog` and `.gbot` directory.
- The bot engine automatically detects and loads templates at startup.
- Custom templates can be created by duplicating an existing `.gbai` folder and modifying its contents.
---
## Summary
The `templates/` directory is the backbone of the GeneralBots template system.
Each `.gbai` package encapsulates dialogs, knowledge bases, and configurations for specific bot behaviors.
See [Chapter 2: Templates](../chapter-02/templates.md) for complete documentation on using and customizing templates.

855
docs/src/chapter-05/universal-messaging.md
View file

@ -1,763 +1,150 @@
# General Bots BASIC - Universal Messaging & Multi-Channel Documentation
# Universal Messaging & Multi-Channel
## Table of Contents
- [Universal Messaging Keywords](#universal-messaging-keywords)
- [Channel Configuration](#channel-configuration)
- [URA System](#ura-system)
- [Complete BASIC Language Reference](#complete-basic-language-reference)
BotServer automatically handles conversations across different channels (Web, WhatsApp, Email, etc.) using the same BASIC scripts. Write once, deploy everywhere.
---
## How It Works
## Universal Messaging Keywords
Your BASIC scripts don't need to know which channel they're running on. The same `TALK` and `HEAR` commands work universally:
The universal messaging system allows seamless communication across multiple channels (WhatsApp, Instagram, Teams, Web, Email) using intelligent channel detection and routing.
### TALK TO - Universal Message Sending
Send messages to any recipient across any supported channel.
#### Syntax
```basic
TALK TO recipient, message
TALK "Hello! How can I help you?"
HEAR response
TALK "You said: " + response
```
#### Auto-Detection Examples
This script works identically whether the user is:
- Chatting via web browser
- Messaging on WhatsApp
- Sending emails
- Using Microsoft Teams
## Supported Channels
### Web (Default)
The primary channel. Users access via browser at `http://localhost:8080`.
### WhatsApp Business
Requires WhatsApp Business API configuration. Messages are automatically formatted for WhatsApp's constraints.
### Email
Bots can receive and respond to emails. Each email thread becomes a conversation session.
### Microsoft Teams
Deploy bots directly to Teams channels and direct messages.
## Channel Detection
BotServer automatically detects the channel based on the session context. No special code needed:
```basic
' WhatsApp - Auto-detected by phone number format
TALK TO "+5511999999999", "Hello via WhatsApp"
TALK TO "5511999999999", "Message to WhatsApp"
' Email - Auto-detected by email format
TALK TO "user@example.com", "Hello via Email"
' Teams - Auto-detected by domain
TALK TO "user@teams.ms", "Hello via Teams"
TALK TO "user@microsoft.com", "Teams message"
' Web Session - For logged-in users
TALK TO user.id, "Welcome back!"
' This works on ALL channels
TALK "Welcome to our service!"
TALK "What's your name?"
HEAR name
TALK "Nice to meet you, " + name
```
#### Explicit Channel Specification
## Channel-Specific Formatting
While your code stays the same, BotServer automatically handles channel-specific formatting:
### Web
- Full HTML support
- Rich formatting
- Images and media
- Interactive elements
### WhatsApp
- Plain text with emoji
- Media as attachments
- Quick reply buttons
- 1024 character limit per message
### Email
- HTML email format
- Subject line handling
- Attachments
- Proper threading
### Teams
- Adaptive cards
- @mentions
- Channel vs DM detection
- Teams-specific formatting
## Media Handling
Send files and media universally:
```basic
' Format: "channel:recipient"
TALK TO "whatsapp:+5511999999999", "WhatsApp message"
TALK TO "teams:user@company.com", "Teams message"
TALK TO "instagram:username", "Instagram DM"
TALK TO "web:session_id", "Web notification"
TALK TO "email:user@example.com", "Email message"
' Works on all channels that support files
SEND FILE "report.pdf"
TALK "I've sent you the report."
```
### SEND FILE TO - Universal File Sharing
Each channel handles files appropriately:
- Web: Download link
- WhatsApp: Document attachment
- Email: Email attachment
- Teams: File card
Send files to any recipient across channels with automatic media handling.
## Session Management
#### Syntax
```basic
SEND FILE TO recipient, file
SEND FILE TO recipient, file, caption
```
Each channel maintains its own session handling:
#### Examples
```basic
' Send file with auto-detection
SEND FILE TO "+5511999999999", document
SEND FILE TO "user@example.com", report_pdf
- **Web**: Cookie-based sessions
- **WhatsApp**: Phone number as session ID
- **Email**: Thread ID as session
- **Teams**: User/channel context
' Send with caption
SEND FILE TO "+5511999999999", image, "Product photo"
SEND FILE TO "teams:project-channel", spreadsheet, "Monthly report"
## Configuration
' From file path
file = "reports/monthly.pdf"
SEND FILE TO "email:manager@company.com", file, "Monthly Report Attached"
' From generated content
data = FIND "sales.xlsx"
pdf = data AS PDF
SEND FILE TO "+5511999999999", pdf, "Sales Report"
```
### BROADCAST - Multi-Recipient Messaging
Send messages to multiple recipients simultaneously.
#### Syntax
```basic
BROADCAST message TO recipient_list
```
#### Examples
```basic
' Broadcast to contact list
contacts = FIND "contacts.csv"
BROADCAST "Newsletter: New features available!" TO contacts
' Broadcast with filtering
customers = FIND "customers.xlsx", "status='active'"
BROADCAST "Special offer for active customers" TO customers
' Mixed channel broadcast
recipients = ["+5511999999999", "user@email.com", "teams:channel-id"]
BROADCAST "Important announcement" TO recipients
```
### SEND TO - Explicit Channel Routing
Direct channel specification for advanced routing scenarios.
#### Syntax
```basic
SEND TO "channel:recipient", message
```
#### Examples
```basic
' Force specific channel
SEND TO "whatsapp:+5511999999999", "WhatsApp only message"
SEND TO "email:user@example.com", "Email notification"
' Conditional channel selection
IF urgent THEN
SEND TO "whatsapp:" + customer.phone, alert_message
ELSE
SEND TO "email:" + customer.email, notification
END IF
```
---
## Channel Configuration
### Configuration Files Location
All channel configurations are stored in the bot configuration database and can be managed via `config.csv`:
```
.gbot/
├── config.csv # Main configuration
├── ura.csv # URA routing rules
└── menu.csv # Interactive menus
```
### WhatsApp Configuration
Add to `config.csv`:
```csv
whatsapp-access-token,YOUR_FACEBOOK_ACCESS_TOKEN
whatsapp-phone-id,YOUR_PHONE_NUMBER_ID
whatsapp-verify-token,YOUR_WEBHOOK_VERIFY_TOKEN
```
### Instagram Configuration
Add to `config.csv`:
```csv
instagram-access-token,YOUR_INSTAGRAM_ACCESS_TOKEN
instagram-page-id,YOUR_PAGE_ID
instagram-verify-token,YOUR_WEBHOOK_VERIFY_TOKEN
instagram-admin-id,ADMIN_USER_ID
```
### Teams Configuration
Add to `config.csv`:
```csv
teams-app-id,YOUR_TEAMS_APP_ID
teams-app-password,YOUR_TEAMS_APP_PASSWORD
teams-service-url,https://smba.trafficmanager.net/br/
teams-tenant-id,YOUR_TENANT_ID
teams-support-channel,SUPPORT_CHANNEL_ID
```
### Email Configuration
Add to `config.csv`:
```csv
email-smtp-host,smtp.gmail.com
email-smtp-port,587
email-smtp-user,your-email@gmail.com
email-smtp-password,YOUR_APP_PASSWORD
email-from-address,your-email@gmail.com
email-from-name,Your Bot Name
```
---
## URA System
The URA (Unidade de Resposta Audível) system provides intelligent message routing and automatic responses.
### URA Configuration (ura.csv)
Format: `rule_type,condition,action_type,action_value`
#### Examples
Channel configuration is done in the bot's `config.csv`:
```csv
keyword,ajuda;help;suporte,transfer,teams
keyword,vendas;orçamento,transfer,sales
time,08:00-18:00,continue,
time,18:01-07:59,message,Estamos fora do horário de atendimento
channel,whatsapp,menu,main_menu
channel,instagram,message,Bem-vindo ao Instagram! Como posso ajudar?
keyword,urgente;emergência,transfer,priority_support
```
### Menu Configuration (menu.csv)
Format: `menu_id,option_key,option_label,action_type,action_value`
#### Examples
```csv
main_menu,1,Suporte Técnico,transfer,technical
main_menu,2,Vendas,transfer,sales
main_menu,3,Financeiro,transfer,finance
main_menu,4,Falar com Atendente,transfer,human
main_menu,0,Encerrar,message,Obrigado por entrar em contato!
```
### Central Attendance Flow
```basic
' Example attendance flow implementation
SET HEAR ON whatsapp
main:
HEAR user_message
' Check URA rules
IF user_message CONTAINS "urgente" THEN
TALK TO "teams:emergency-support", "Urgent: " + user_message
TALK "You've been transferred to priority support"
GOTO main
END IF
' Business hours check
IF TIME() < "08:00" OR TIME() > "18:00" THEN
TALK "We're currently closed. Business hours: 8AM-6PM"
GOTO main
END IF
' Show menu
TALK "Choose an option:"
TALK "1 - Technical Support"
TALK "2 - Sales"
TALK "3 - Human Agent"
HEAR option
SELECT CASE option
CASE "1"
TALK TO "teams:tech-support", "New ticket from " + user.phone
CASE "2"
TALK TO "teams:sales", "Sales inquiry from " + user.phone
CASE "3"
TALK TO "teams:human-agents", "Transfer request from " + user.phone
TALK "You're being transferred to a human agent..."
END SELECT
GOTO main
```
---
## Complete BASIC Language Reference
### User Interaction Commands
| Command | Description | Example |
|---------|-------------|---------|
| `HEAR variable` | Wait for user input | `HEAR name` |
| `TALK message` | Send message to current user | `TALK "Hello " + name` |
| `TALK TO recipient, message` | Send to specific recipient | `TALK TO "+5511999999999", "Hello"` |
| `WAIT seconds` | Pause execution | `WAIT 5` |
### Input Validation
| Command | Description | Example |
|---------|-------------|---------|
| `HEAR var AS EMAIL` | Validate email input | `HEAR email AS EMAIL` |
| `HEAR var AS DATE` | Validate date input | `HEAR birthdate AS DATE` |
| `HEAR var AS NAME` | Validate name input | `HEAR fullname AS NAME` |
| `HEAR var AS INTEGER` | Validate integer | `HEAR age AS INTEGER` |
| `HEAR var AS BOOLEAN` | Validate true/false | `HEAR agree AS BOOLEAN` |
| `HEAR var AS HOUR` | Validate time | `HEAR appointment AS HOUR` |
| `HEAR var AS MONEY` | Validate currency | `HEAR amount AS MONEY` |
| `HEAR var AS MOBILE` | Validate phone | `HEAR phone AS MOBILE` |
| `HEAR var AS ZIPCODE` | Validate ZIP | `HEAR zip AS ZIPCODE` |
| `HEAR var AS "opt1", "opt2"` | Menu selection | `HEAR choice AS "Yes", "No", "Maybe"` |
| `HEAR var AS LANGUAGE` | Language code | `HEAR lang AS LANGUAGE` |
| `HEAR var AS QRCODE` | QR code scan | `HEAR code AS QRCODE` |
| `HEAR var AS FILE` | File upload | `HEAR document AS FILE` |
| `HEAR var AS AUDIO` | Audio upload | `HEAR recording AS AUDIO` |
### Data Operations
| Command | Description | Example |
|---------|-------------|---------|
| `FIND file/table` | Query data | `FIND "customers.xlsx"` |
| `FIND file/table, filter` | Query with filter | `FIND "users", "age>18"` |
| `SAVE table, data` | Save to database | `SAVE "orders", order_data` |
| `GET url` | HTTP GET request | `data = GET "https://api.example.com"` |
| `POST url, data` | HTTP POST request | `POST "https://api.example.com", data` |
| `SELECT ... FROM ...` | SQL operations | `SELECT name, SUM(sales) FROM data GROUP BY name` |
### File Operations
| Command | Description | Example |
|---------|-------------|---------|
| `SEND FILE TO recipient, file` | Send file | `SEND FILE TO "+5511999999999", report` |
| `SAVE file AS path` | Save to disk | `SAVE document AS "reports/monthly.pdf"` |
| `UPLOAD file` | Upload to cloud | `UPLOAD "report.pdf"` |
| `DOWNLOAD url` | Download file | `file = DOWNLOAD "https://example.com/file.pdf"` |
| `INCLUDE file` | Include script | `INCLUDE "functions.gbdialog"` |
| `DIR path` | List directory | `files = DIR "documents/"` |
| `FILL template, data` | Fill template | `doc = FILL "template.docx", customer_data` |
### Data Conversion
| Command | Description | Example |
|---------|-------------|---------|
| `data AS IMAGE` | Convert to image | `chart = data AS IMAGE` |
| `data AS PDF` | Convert to PDF | `report = data AS PDF` |
| `CHART type, data, labels` | Create chart | `img = CHART "pie", [10,20,30], "A;B;C"` |
| `CHART PROMPT data, prompt` | AI chart generation | `chart = CHART PROMPT sales, "monthly bar chart"` |
| `QRCODE text` | Generate QR code | `qr = QRCODE "https://example.com"` |
| `FORMAT value, format` | Format value | `date = FORMAT today, "YYYY-MM-DD"` |
| `CONVERT file` | Convert file format | `html = CONVERT "design.ai"` |
### Web Automation
| Command | Description | Example |
|---------|-------------|---------|
| `OPEN url` | Open webpage | `page = OPEN "https://example.com"` |
| `OPEN url AS session` | Named session | `page = OPEN "https://example.com" AS #login` |
| `GET page, selector` | Get element | `text = GET page, "#title"` |
| `SET page, selector, value` | Set field value | `SET page, "#username", "user123"` |
| `CLICK page, selector` | Click element | `CLICK page, "#submit"` |
| `SCREENSHOT selector` | Take screenshot | `img = SCREENSHOT "body"` |
| `PRESS ENTER ON page` | Press Enter key | `PRESS ENTER ON page` |
### Advanced Operations
| Command | Description | Example |
|---------|-------------|---------|
| `TABLE name ON connection` | Define table | `TABLE "sales" ON "production_db"` |
| `NEW OBJECT` | Create object | `data = NEW OBJECT` |
| `NEW ARRAY` | Create array | `list = NEW ARRAY` |
| `ADD NOTE text` | Add to notes | `ADD NOTE "Customer requested callback"` |
| `ALLOW ROLE role` | Check authorization | `ALLOW ROLE "admin"` |
| `CONTINUATION TOKEN` | Get token | `token = CONTINUATION TOKEN` |
| `SET PARAM name AS value` | Store parameter | `SET PARAM last_contact AS today` |
| `GET PARAM name` | Retrieve parameter | `last = GET PARAM last_contact` |
### Configuration Commands
| Command | Description | Example |
|---------|-------------|---------|
| `SET SCHEDULE cron` | Schedule execution | `SET SCHEDULE "0 9 * * *"` |
| `SET LANGUAGE code` | Set language | `SET LANGUAGE "pt-BR"` |
| `SET TRANSLATOR state` | Toggle translation | `SET TRANSLATOR ON` |
| `SET THEME theme` | Set visual theme | `SET THEME "dark"` |
| `SET MAX LINES n` | Limit output | `SET MAX LINES 100` |
| `SET OPERATOR op` | Set default operator | `SET OPERATOR OR` |
| `SET FILTER TYPE types` | Set filter types | `SET FILTER TYPE date, string` |
| `SET PAGED mode` | Set pagination | `SET PAGED "auto"` |
| `SET WHOLE WORD bool` | Word matching | `SET WHOLE WORD TRUE` |
| `SET HEAR ON channel` | Switch input channel | `SET HEAR ON "+5511999999999"` |
### HTTP Configuration
| Command | Description | Example |
|---------|-------------|---------|
| `SET HTTP HEADER key = value` | Set header | `SET HTTP HEADER Authorization = "Bearer token"` |
| `SET HTTP USERNAME = value` | Set auth user | `SET HTTP USERNAME = "api_user"` |
| `SET HTTP PASSWORD = value` | Set auth pass | `SET HTTP PASSWORD = "secret"` |
### Control Flow
| Command | Description | Example |
|---------|-------------|---------|
| `IF condition THEN` | Conditional | `IF age > 18 THEN TALK "Adult" END IF` |
| `FOR EACH item IN list` | Loop through list | `FOR EACH customer IN customers` |
| `DO WHILE condition` | While loop | `DO WHILE count < 10` |
| `SELECT CASE variable` | Switch statement | `SELECT CASE option` |
| `EXIT` | Exit script | `EXIT` |
| `EXIT FOR` | Exit loop | `EXIT FOR` |
| `GOTO label` | Jump to label | `GOTO menu` |
### Database Connections
Configure external databases in `config.csv`:
```csv
# PostgreSQL
mydb-driver,postgres
mydb-host,localhost
mydb-port,5432
mydb-database,production
mydb-username,dbuser
mydb-password,dbpass
# MySQL/MariaDB
mysql-driver,mysql
mysql-host,localhost
mysql-port,3306
mysql-database,myapp
mysql-username,root
mysql-password,pass
# SQL Server
mssql-driver,mssql
mssql-host,server.database.windows.net
mssql-port,1433
mssql-database,mydb
mssql-username,sa
mssql-password,pass
```
Then use in BASIC:
```basic
TABLE customers ON mydb
id AS integer PRIMARY KEY
name AS string(100)
email AS string(255)
created_at AS datetime
' Use the table
SAVE customers, customer_data
results = FIND customers, "created_at > '2024-01-01'"
```
## Complete Examples
### Multi-Channel Customer Service Bot
```basic
' Customer service bot with channel routing
SET SCHEDULE "0 9-18 * * 1-5" ' Business hours only
' Main entry point
main:
SET HEAR ON whatsapp ' Default to WhatsApp
HEAR initial_message AS TEXT
' Detect urgency
IF initial_message CONTAINS "urgent" OR initial_message CONTAINS "emergency" THEN
' Route to priority support
TALK TO "teams:priority-support", "URGENT from " + user.channel + ": " + initial_message
TALK "Your request has been marked as urgent. An agent will contact you shortly."
' Send notification to multiple channels
SEND TO "email:manager@company.com", "Urgent request received"
SEND TO "whatsapp:+5511999999999", "Urgent support needed"
END IF
' Show menu based on channel
IF user.channel == "whatsapp" THEN
TALK "Welcome! Please select an option:"
HEAR choice AS "1-Support", "2-Sales", "3-Agent", "0-Exit"
ELSE IF user.channel == "instagram" THEN
TALK "Hi! How can we help you today?"
HEAR choice AS "Support", "Sales", "Human Agent"
ELSE
TALK "Hello! Type 'help' for options."
HEAR choice
END IF
' Process choice
SELECT CASE choice
CASE "1-Support", "Support", "help"
GOTO technical_support
CASE "2-Sales", "Sales"
GOTO sales_inquiry
CASE "3-Agent", "Human Agent", "agent"
GOTO human_transfer
CASE "0-Exit", "Exit", "bye"
TALK "Thank you for contacting us!"
EXIT
CASE ELSE
TALK "Invalid option. Please try again."
GOTO main
END SELECT
' Technical support flow
technical_support:
TALK "Please describe your technical issue:"
HEAR issue AS TEXT
' Log to database
ticket = NEW OBJECT
ticket.customer = user.id
ticket.channel = user.channel
ticket.issue = issue
ticket.timestamp = NOW()
SAVE "support_tickets", ticket
' Notify support team
TALK TO "teams:tech-support", "New ticket from " + user.channel + ": " + issue
TALK "Ticket created. Our team will contact you within 24 hours."
' Send confirmation
IF user.channel == "whatsapp" THEN
SEND FILE TO user.id, ticket AS PDF, "Your support ticket"
ELSE IF user.channel == "email" THEN
SEND TO user.id, "Ticket #" + ticket.id + " created: " + issue
END IF
GOTO main
' Sales inquiry flow
sales_inquiry:
TALK "What product are you interested in?"
HEAR product AS TEXT
' Get product information
products = FIND "products.xlsx", "name LIKE '" + product + "'"
IF products.length > 0 THEN
' Send product catalog
catalog = products AS PDF
SEND FILE TO user.id, catalog, "Product Information"
TALK "I've sent you our product catalog. Would you like to speak with sales?"
HEAR confirm AS BOOLEAN
IF confirm THEN
GOTO human_transfer
END IF
ELSE
TALK "Product not found. Let me connect you with sales."
GOTO human_transfer
END IF
GOTO main
' Human transfer flow
human_transfer:
TALK "Connecting you to a human agent..."
' Find available agent based on channel
agent = GET "https://api.company.com/next-available-agent"
IF agent.available THEN
' Create bridge between customer and agent
TALK TO agent.channel + ":" + agent.id, "New customer from " + user.channel
TALK TO agent.channel + ":" + agent.id, "Customer: " + user.id
TALK TO agent.channel + ":" + agent.id, "Initial message: " + initial_message
TALK "You've been connected to " + agent.name
' Bridge messages
bridge_loop:
HEAR customer_msg
IF customer_msg == "end chat" THEN
TALK "Chat ended. Thank you!"
GOTO main
END IF
TALK TO agent.channel + ":" + agent.id, customer_msg
GOTO bridge_loop
ELSE
TALK "All agents are busy. We'll contact you within 1 hour."
' Queue for callback
callback = NEW OBJECT
callback.customer = user.id
callback.channel = user.channel
callback.requested_at = NOW()
SAVE "callback_queue", callback
END IF
GOTO main
```
### Broadcasting Campaign System
```basic
' Marketing campaign broadcaster
SET MAX LINES 1000
' Load campaign data
campaign = FIND "campaign.xlsx"
customers = FIND "customers.csv", "opt_in=true"
' Segment customers by channel preference
whatsapp_list = SELECT * FROM customers WHERE preferred_channel = 'whatsapp'
email_list = SELECT * FROM customers WHERE preferred_channel = 'email'
teams_list = SELECT * FROM customers WHERE preferred_channel = 'teams'
' Prepare personalized messages
FOR EACH customer IN customers
message = "Hi " + customer.name + "! " + campaign.message
' Add personalized offer
IF customer.tier == "gold" THEN
message = message + " As a Gold member, you get 20% extra discount!"
END IF
' Send via preferred channel
IF customer.preferred_channel == "whatsapp" AND customer.phone != "" THEN
SEND FILE TO customer.phone, campaign.image, message
ELSE IF customer.preferred_channel == "email" AND customer.email != "" THEN
SEND TO "email:" + customer.email, message
ELSE IF customer.preferred_channel == "teams" AND customer.teams_id != "" THEN
SEND TO "teams:" + customer.teams_id, message
END IF
' Log delivery
log = NEW OBJECT
log.customer_id = customer.id
log.campaign_id = campaign.id
log.channel = customer.preferred_channel
log.sent_at = NOW()
SAVE "campaign_log", log
' Rate limiting
WAIT 1
NEXT
' Generate report
report = SELECT
channel,
COUNT(*) as total_sent,
SUM(CASE WHEN status='delivered' THEN 1 ELSE 0 END) as delivered
FROM campaign_log
GROUP BY channel
' Send report to management
report_pdf = report AS PDF
SEND FILE TO "email:marketing@company.com", report_pdf, "Campaign Report"
TALK TO "teams:marketing-channel", "Campaign completed. " + customers.length + " messages sent."
```
### Web Automation with Multi-Channel Notifications
```basic
' Price monitoring with notifications
SET SCHEDULE "0 */6 * * *" ' Every 6 hours
products = FIND "monitor_products.csv"
FOR EACH product IN products
' Open product page
page = OPEN product.url AS #monitor
' Get current price
current_price = GET page, product.price_selector
current_price = PARSE_NUMBER(current_price)
' Check for price change
IF current_price < product.last_price THEN
discount = ((product.last_price - current_price) / product.last_price) * 100
message = "PRICE DROP! " + product.name + " is now $" + current_price
message = message + " (" + discount + "% off)"
' Notify via multiple channels based on discount level
IF discount > 20 THEN
' Big discount - notify everywhere
BROADCAST message TO product.watchers
' Send to Telegram group
TALK TO "telegram:price-alerts", message
' Send to WhatsApp broadcast list
FOR EACH watcher IN product.whatsapp_watchers
TALK TO watcher, message
SEND FILE TO watcher, SCREENSHOT product.price_selector, "Price proof"
NEXT
ELSE
' Small discount - email only
FOR EACH watcher IN product.email_watchers
SEND TO "email:" + watcher, message
NEXT
END IF
' Update database
product.last_price = current_price
product.last_check = NOW()
SAVE "monitor_products", product
END IF
WAIT 5 ' Rate limiting between checks
NEXT
TALK TO "teams:monitoring", "Price check completed at " + NOW()
```
## Error Handling
```basic
' Robust error handling example
TRY
result = GET "https://api.example.com/data"
IF result.error THEN
THROW "API returned error: " + result.error
END IF
SAVE "api_data", result
CATCH error
' Log error
error_log = NEW OBJECT
error_log.message = error
error_log.timestamp = NOW()
error_log.user = user.id
SAVE "error_log", error_log
' Notify administrators
TALK TO "teams:tech-support", "Error occurred: " + error
TALK TO "email:admin@company.com", "System error logged"
' Inform user
TALK "An error occurred. Our team has been notified."
FINALLY
' Cleanup
CLOSE page
END TRY
channel-web,enabled
channel-whatsapp,enabled
channel-email,enabled
channel-teams,disabled
```
## Best Practices
1. **Channel Detection**: Let the system auto-detect channels when possible
2. **Fallback Channels**: Always have a fallback communication method
3. **Rate Limiting**: Use WAIT between bulk operations
4. **Error Recovery**: Implement try-catch for external operations
5. **Logging**: Log all cross-channel communications
6. **User Preferences**: Store and respect user channel preferences
7. **Business Hours**: Check business hours before routing to human agents
8. **Message Templates**: Use templates for consistent multi-channel messaging
9. **Testing**: Test each channel individually before broadcasting
10. **Compliance**: Ensure opt-in consent for each communication channel
1. **Keep messages concise** - Some channels have length limits
2. **Use simple formatting** - Not all channels support rich text
3. **Test on target channels** - Ensure your bot works well on each
4. **Handle media gracefully** - Not all channels support all file types
5. **Consider response times** - Email is async, chat is real-time
## Webhook Endpoints
## Channel Limitations
After configuration, set up these webhook endpoints in each platform:
| Channel | Message Length | Media Support | Rich Text | Real-time |
|---------|---------------|---------------|-----------|-----------|
| Web | Unlimited | Full | Yes | Yes |
| WhatsApp | 1024 chars | Images, Docs | Limited | Yes |
| Email | Unlimited | Attachments | HTML | No |
| Teams | 28KB | Full | Adaptive Cards | Yes |
- **WhatsApp**: `https://your-domain/api/channels/whatsapp/webhook`
- **Instagram**: `https://your-domain/api/channels/instagram/webhook`
- **Teams**: `https://your-domain/api/channels/teams/messages`
## Example: Multi-Channel Bot
## Support
```basic
' start.bas - Works on ALL channels
TALK "Welcome to Customer Support!"
TALK "How can I help you today?"
For additional support and updates, visit:
- GitHub: https://github.com/GeneralBots/BotServer
- Documentation: https://docs.generalbots.com
- Community: https://community.generalbots.com
HEAR request
IF INSTR(request, "order") > 0 THEN
TALK "I'll help you with your order."
TALK "What's your order number?"
HEAR order_number
' Process order inquiry
ELSE
TALK "Let me connect you with an agent."
' Transfer to human
END IF
```
## Summary
Universal messaging means your BASIC scripts work across all channels without modification. BotServer handles the complexity of channel-specific formatting and delivery, letting you focus on the conversation logic.

146
docs/src/chapter-06/architecture.md
View file

@ -4,37 +4,131 @@ BotServer follows a modular architecture designed for scalability, maintainabili
## Core Architecture
### System Architecture Diagram
```
BotServer
├── Core Engine
│ ├── BASIC Interpreter
│ ├── Session Manager
│ ├── Context Manager
│ └── Bootstrap System
├── AI & NLP Layer
│ ├── LLM Integration
│ ├── Prompt Management
│ ├── Knowledge Base
│ └── Vector Search
├── Communication Layer
│ ├── Multi-Channel Support
│ ├── WebSocket Server
│ ├── REST API
│ └── Event Bus
├── Storage Layer
│ ├── PostgreSQL
│ ├── Drive (S3-compatible)
│ ├── Cache (Valkey)
│ └── Qdrant Vector DB
└── Services Layer
├── Authentication
├── Email Service
├── Calendar Engine
└── Task Engine
┌─────────────────────────────────────────────────────────────────────────┐
│ BotServer (Binary) │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Core Engine │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ BASIC │ │ Session │ │ Context │ │ │
│ │ │ Interpreter │ │ Manager │ │ Manager │ │ │
│ │ │ (Rhai) │ │ (Tokio) │ │ (Memory) │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ └─────────┼──────────────────┼──────────────────┼───────────────────┘ │
│ │ │ │ │
│ ┌─────────▼──────────────────▼──────────────────▼───────────────────┐ │
│ │ AI & NLP Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ LLM │ │ Embeddings │ │ Knowledge │ │ │
│ │ │ Integration │ │ (BGE) │ │ Base │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ └─────────┼──────────────────┼──────────────────┼───────────────────┘ │
│ │ │ │ │
│ ┌─────────▼──────────────────▼──────────────────▼───────────────────┐ │
│ │ Communication Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ WebSocket │ │ REST API │ │ Channels │ │ │
│ │ │ Server │ │ (Axum) │ │ Adapters │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ └─────────┼──────────────────┼──────────────────┼───────────────────┘ │
│ │ │ │ │
│ ┌─────────▼──────────────────▼──────────────────▼───────────────────┐ │
│ │ Storage Layer │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │PostgreSQL│ │ Valkey │ │ SeaweedFS│ │ Qdrant │ │ │
│ │ │ (Diesel) │ │ Cache │ │ S3 │ │ Vectors │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
### Module Dependency Graph
```
main.rs
│
▼
bootstrap/
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
package_manager/ config/ database/
│ │ │
│ └──────┬───────────┘
│ │
▼ ▼
web_server/ ◄──────────── session/
│ │
├──────┬──────┬──────────┤
│ │ │ │
▼ ▼ ▼ ▼
channels/ bot/ basic/ auth/
│ │ │ │
└──────┴──────┼──────────┘
│
▼
llm/
│
▼
context/
```
## Module Organization
### Data Flow Through Modules
```
User Input
│
▼
┌─────────────────┐
│ web_server/ │ Axum HTTP Server
│ channels/ │ Route to channel
└────────┬────────┘
│
▼
┌─────────────────┐
│ session/ │ Load/Create Session
│ │ Validate Token
└────────┬────────┘
│
▼
┌─────────────────┐
│ auth/ │ Check Permissions
│ │ Apply RBAC
└────────┬────────┘
│
▼
┌─────────────────┐
│ bot/ │ Route to Bot Instance
│ │ Load Configuration
└────────┬────────┘
│
▼
┌─────────────────┐
│ basic/ │ Execute BASIC Script
│ │ Parse Keywords
└────────┬────────┘
│
├────────────┬────────────┬────────────┐
▼ ▼ ▼ ▼
┌─────────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ context/ │ │ drive/ │ │database/│ │ llm/ │
│ Load KB │ │Get Files│ │Query DB │ │Call AI │
└─────────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │ │
└────────────┴────────────┴────────────┘
│
▼
Bot Response
```
### Core Modules
#### `auth/`

7
docs/src/chapter-06/prompt-manager.md
View file

@ -257,10 +257,3 @@ match manager.get_prompt("custom", "missing") {
}
```
## Future Enhancements
- **A/B Testing**: Compare prompt effectiveness
- **Auto-optimization**: ML-based prompt improvement
- **Multi-language**: Prompt localization support
- **Prompt Chains**: Complex multi-step prompts
- **Visual Editor**: Web-based prompt management UI

2
docs/src/chapter-08/external-apis.md
View file

@ -254,4 +254,4 @@ TALK report
## Summary
While BotServer's external API capabilities are currently limited to GET requests, creative use of the LLM for response processing and bot memory for state management enables integration with many third-party services. For more complex API interactions, consider using proxy services or waiting for future enhancements to the platform.
While BotServer's external API capabilities are currently limited to GET requests, creative use of response processing and bot memory for state management enables integration with many third-party services. For more complex API interactions, consider using proxy services or custom integrations.

9
docs/src/chapter-08/mcp-format.md
View file

@ -215,15 +215,6 @@ MCP tools are validated during compilation:
- Descriptions cannot be empty
- Tool name must be unique per bot
## Future Enhancements
Potential MCP format extensions:
- Optional parameters support
- Array and object types
- Validation constraints
- Output schema definition
- Async execution hints
## Summary
The MCP format provides a structured way to expose BASIC scripts as callable tools for LLMs. By generating MCP-compatible definitions, BotServer enables seamless tool discovery and invocation within conversational flows.

287
docs/src/chapter-08/nvidia-gpu-setup.md Normal file
View file

@ -0,0 +1,287 @@
# NVIDIA GPU Setup for LXC Containers
This guide covers setting up NVIDIA GPU passthrough for BotServer running in LXC containers, enabling hardware acceleration for local LLM inference.
## Prerequisites
- NVIDIA GPU (RTX 3060 or better with 12GB+ VRAM recommended)
- NVIDIA drivers installed on the host system
- LXD/LXC installed
- CUDA-capable GPU
## LXD Configuration (Interactive Setup)
When initializing LXD, use these settings:
```bash
sudo lxd init
```
Answer the prompts as follows:
- **Would you like to use LXD clustering?** → `no`
- **Do you want to configure a new storage pool?** → `no` (will create `/generalbots` later)
- **Would you like to connect to a MAAS server?** → `no`
- **Would you like to create a new local network bridge?** → `yes`
- **What should the new bridge be called?** → `lxdbr0`
- **What IPv4 address should be used?** → `auto`
- **What IPv6 address should be used?** → `auto`
- **Would you like the LXD server to be available over the network?** → `no`
- **Would you like stale cached images to be updated automatically?** → `no`
- **Would you like a YAML "lxd init" preseed to be printed?** → `no`
### Storage Configuration
- **Storage backend name:** → `default`
- **Storage backend driver:** → `zfs`
- **Create a new ZFS pool?** → `yes`
## NVIDIA GPU Configuration
### On the Host System
Create a GPU profile and attach it to your container:
```bash
# Create GPU profile
lxc profile create gpu
# Add GPU device to profile
lxc profile device add gpu gpu gpu gputype=physical
# Apply GPU profile to your container
lxc profile add gb-system gpu
```
### Inside the Container
Configure NVIDIA driver version pinning and install drivers:
1. **Pin NVIDIA driver versions** to ensure stability:
```bash
cat > /etc/apt/preferences.d/nvidia-drivers << 'EOF'
Package: *nvidia*
Pin: version 560.35.05-1
Pin-Priority: 1001
Package: cuda-drivers*
Pin: version 560.35.05-1
Pin-Priority: 1001
Package: libcuda*
Pin: version 560.35.05-1
Pin-Priority: 1001
Package: libxnvctrl*
Pin: version 560.35.05-1
Pin-Priority: 1001
Package: libnv*
Pin: version 560.35.05-1
Pin-Priority: 1001
EOF
```
2. **Install NVIDIA drivers and CUDA toolkit:**
```bash
# Update package lists
apt update
# Install NVIDIA driver and nvidia-smi
apt install -y nvidia-driver nvidia-smi
# Add CUDA repository
wget https://developer.download.nvidia.com/compute/cuda/repos/debian12/x86_64/cuda-keyring_1.1-1_all.deb
dpkg -i cuda-keyring_1.1-1_all.deb
# Install CUDA toolkit
apt-get update
apt-get -y install cuda-toolkit-12-8
apt-get install -y cuda-drivers
```
## Verify GPU Access
After installation, verify GPU is accessible:
```bash
# Check GPU is visible
nvidia-smi
# Should show your GPU with driver version 560.35.05
```
## Configure BotServer for GPU
Update your bot's `config.csv` to use GPU acceleration:
```csv
name,value
llm-server-gpu-layers,35
```
The number of layers depends on your GPU memory:
- **RTX 3060 (12GB):** 20-35 layers
- **RTX 3070 (8GB):** 15-25 layers
- **RTX 4070 (12GB):** 30-40 layers
- **RTX 4090 (24GB):** 50-99 layers
## Troubleshooting
### GPU Not Detected
If `nvidia-smi` doesn't show the GPU:
1. Check host GPU drivers:
```bash
# On host
nvidia-smi
lxc config device list gb-system
```
2. Verify GPU passthrough:
```bash
# Inside container
ls -la /dev/nvidia*
```
3. Check kernel modules:
```bash
lsmod | grep nvidia
```
### Driver Version Mismatch
If you encounter driver version conflicts:
1. Ensure host and container use the same driver version
2. Remove the version pinning file and install matching drivers:
```bash
rm /etc/apt/preferences.d/nvidia-drivers
apt update
apt install nvidia-driver-560
```
### CUDA Library Issues
If CUDA libraries aren't found:
```bash
# Add CUDA to library path
echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf.d/cuda.conf
ldconfig
# Add to PATH
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
## Custom llama.cpp Compilation
If you need custom CPU/GPU optimizations or specific hardware support, compile llama.cpp from source:
### Prerequisites
```bash
sudo apt update
sudo apt install build-essential cmake git
```
### Compilation Steps
```bash
# Clone llama.cpp repository
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
# Create build directory
mkdir build
cd build
# Configure with CUDA support
cmake .. -DLLAMA_CUDA=ON -DLLAMA_CURL=OFF
# Compile using all available cores
make -j$(nproc)
```
### Compilation Options
For different hardware configurations:
```bash
# CPU-only build (no GPU)
cmake .. -DLLAMA_CURL=OFF
# CUDA with specific compute capability
cmake .. -DLLAMA_CUDA=ON -DLLAMA_CUDA_FORCE_COMPUTE=75
# ROCm for AMD GPUs
cmake .. -DLLAMA_HIPBLAS=ON
# Metal for Apple Silicon
cmake .. -DLLAMA_METAL=ON
# AVX2 optimizations for modern CPUs
cmake .. -DLLAMA_AVX2=ON
# F16C for half-precision support
cmake .. -DLLAMA_F16C=ON
```
### After Compilation
```bash
# Copy compiled binary to BotServer
cp bin/llama-server /path/to/botserver-stack/bin/llm/
# Update config.csv to use custom build
llm-server-path,/path/to/botserver-stack/bin/llm/
```
### Benefits of Custom Compilation
- **Hardware-specific optimizations** for your exact CPU/GPU
- **Custom CUDA compute capabilities** for newer GPUs
- **AVX/AVX2/AVX512** instructions for faster CPU inference
- **Reduced binary size** by excluding unused features
- **Support for experimental features** not in releases
## Performance Optimization
### Memory Settings
For optimal LLM performance with GPU:
```csv
name,value
llm-server-gpu-layers,35
llm-server-mlock,true
llm-server-no-mmap,false
llm-server-ctx-size,4096
```
### Multiple GPUs
For systems with multiple GPUs, specify which GPU to use:
```bash
# List available GPUs
lxc profile device add gpu gpu0 gpu gputype=physical id=0
lxc profile device add gpu gpu1 gpu gputype=physical id=1
```
## Benefits of GPU Acceleration
With GPU acceleration enabled:
- **5-10x faster** inference compared to CPU
- **Higher context sizes** possible (8K-32K tokens)
- **Real-time responses** even with large models
- **Lower CPU usage** for other tasks
- **Support for larger models** (13B, 30B parameters)
## Next Steps
- [Installation Guide](./installation.md) - Complete BotServer setup
- [Quick Start](./quick-start.md) - Create your first bot
- [Configuration Reference](../chapter-02/gbot.md) - All GPU-related parameters

9
docs/src/chapter-08/openai-format.md
View file

@ -247,15 +247,6 @@ To debug OpenAI function calls:
4. Review execution logs
5. Test with manual invocation
## Future Enhancements
Planned improvements:
- Optional parameters
- Complex type support
- Streaming function results
- Batch function calls
- Function versioning
## Summary
The OpenAI function format enables seamless integration between BASIC scripts and OpenAI's GPT models. By automatically generating compatible function definitions, BotServer allows natural language interactions to trigger complex business logic implementations.

74
docs/src/chapter-08/tool-definition.md
View file

@ -8,6 +8,50 @@ In BotServer, a **tool** is simply a `.bas` file. That's it!
2. **The LLM automatically discovers it** and can call it when needed
3. **No manual registration required** - it just works!
### Tool Discovery and Execution Flow
```
User: "Send an email to John about the meeting"
│
▼
┌─────────────────────┐
│ LLM Analyzes │
│ "Need email tool" │
└──────────┬──────────┘
│
▼
┌─────────────────────────────────┐
│ Tool Discovery │
│ ┌──────────────────────┐ │
│ │ Scan .gbdialog/ │ │
│ │ • send-email.bas ✓ │ │
│ │ • create-task.bas │ │
│ │ • get-weather.bas │ │
│ └──────────┬───────────┘ │
└─────────────┼───────────────────┘
│
▼
┌──────────────────────────────────┐
│ Parameter Collection │
│ │
│ PARAM to → "John" │
│ PARAM subject → "Meeting" │
│ PARAM body → (generated) │
└──────────┬───────────────────────┘
│
▼
┌─────────────────────┐
│ Execute Tool │
│ send-email.bas │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Return Result │
│ "Email sent!" │
└─────────────────────┘
```
## Simple Example
Create `get-weather.bas`:
@ -97,6 +141,36 @@ BotServer automatically converts your `.bas` tools to:
You never write these formats manually - just write `.bas` files!
### Conversion Pipeline
```
send-email.bas
│
▼
┌─────────────────────┐
│ BASIC Parser │
│ • Extract PARAM │
│ • Parse DESCRIPTION │
│ • Analyze code │
└──────────┬──────────┘
│
├──────────────┬──────────────┬──────────────┐
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ MCP │ │ OpenAI │ │ Claude │ │ Local │
│ Format │ │ Function │ │ Tool │ │ Model │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │
└──────────────┴──────────────┴──────────────┘
│
▼
┌──────────────┐
│ LLM Provider │
│ Receives │
│ Native Format│
└──────────────┘
```
## Complete Example
Here's a real tool from the codebase - `enrollment.bas`:

8
docs/src/chapter-09/ai-llm.md
View file

@ -261,14 +261,6 @@ let token_count = llm_provider.count_tokens(prompt)?;
6. **Cache Wisely**: Reduce redundant calls
7. **Stream When Possible**: Better user experience
## Future Enhancements
- Multi-modal support (images, audio)
- Fine-tuning capabilities
- Model routing based on task
- Automatic prompt optimization
- Advanced caching strategies
## Summary
The LLM integration is central to BotServer's intelligence, providing natural language understanding and generation capabilities. Through careful prompt engineering, context management, and provider abstraction, bots can deliver sophisticated conversational experiences while managing costs and performance.

10
docs/src/chapter-09/automation.md
View file

@ -224,16 +224,6 @@ Automation execution is logged:
- Rate limiting applies to automated tasks
- Monitor for runaway automations
## Future Enhancements
Potential improvements to automation:
- Event-driven triggers beyond scheduling
- Webhook integration
- Task dependencies and workflows
- Retry policies
- Distributed execution
- More trigger types (file changes, API events)
## Summary
BotServer's automation features enable bots to perform scheduled and event-driven tasks without user interaction. Through SET_SCHEDULE and system_automations, bots can maintain fresh content, process data regularly, and respond to events automatically, making them more proactive and useful.

8
docs/src/chapter-09/conversation.md
View file

@ -298,14 +298,6 @@ ANONYMOUS_RETENTION_HOURS=24
- Real-time processing overhead
- Concurrent conversation limits
## Future Enhancements
- Voice conversation support
- Multi-language conversations
- Conversation branching
- Advanced analytics
- Conversation templates
## Summary
Conversation management in BotServer provides robust session handling, message persistence, and context management, enabling sophisticated multi-turn interactions while maintaining performance and reliability.

12
docs/src/chapter-09/email.md
View file

@ -304,18 +304,6 @@ try {
- Account validity
- Folder synchronization
## Future Enhancements
Planned improvements:
- Full attachment support
- Email templates
- OAuth2 authentication
- Rich HTML editor
- Email scheduling
- Advanced filtering
- Spam detection
- Email analytics
## Summary
Email integration in BotServer enables powerful email-based automation and communication. Through IMAP/SMTP protocols and BASIC script integration, bots can manage email workflows, automate responses, and integrate email with other bot features.

16
docs/src/chapter-09/knowledge-base.md
View file

@ -303,9 +303,8 @@ TALK summary
### Environment Variables
```bash
# Qdrant Configuration
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=optional-api-key
# Vector Database Configuration
# Configure in your .env file
# Embedding Configuration
EMBEDDING_MODEL=text-embedding-ada-002
@ -316,17 +315,6 @@ SEARCH_TOP_K=5
SEARCH_THRESHOLD=0.7
```
## Future Enhancements
Planned improvements:
- Multi-modal search (images)
- Real-time indexing
- Advanced chunking strategies
- Cross-lingual support
- Document versioning
- Incremental updates
- Custom embedding models
## Summary
The knowledge base system is fundamental to BotServer's intelligence, enabling bots to access and retrieve relevant information from document collections. Through integration with Qdrant and semantic search, bots can provide accurate, context-aware responses based on organizational knowledge.

10
docs/src/chapter-09/storage.md
View file

@ -333,16 +333,6 @@ UPLOAD_SIZE_LIMIT=100MB
TEMP_DIR_SIZE=10GB
```
## Future Enhancements
Planned storage improvements:
- Distributed storage support
- Advanced caching strategies
- Data lake integration
- Time-series optimization
- GraphQL API for queries
- Real-time synchronization
## Summary
BotServer's multi-layered storage architecture provides flexibility, performance, and reliability. By using the right storage solution for each data type and implementing proper caching and optimization strategies, the system can handle large-scale deployments while maintaining responsiveness.

2
docs/src/chapter-10/README.md
View file

@ -37,7 +37,6 @@ Before contributing, ensure you have:
3. **Find Something to Work On**
- Check [good first issues](https://github.com/GeneralBots/BotServer/labels/good%20first%20issue)
- Review the roadmap
- Ask in discussions
## Types of Contributions
@ -228,7 +227,6 @@ All contributors are recognized:
Regular contributors may be invited to:
- Join core team
- Get merge permissions
- Influence roadmap
- Mentor others
## Resources

1
docs/src/chapter-10/pull-requests.md
View file

@ -12,7 +12,6 @@ Pull requests (PRs) are the primary method for contributing code to BotServer. T
- Search existing PRs to avoid duplication
- Check issues for related discussions
- Review the project roadmap
- Discuss major changes in an issue first
### 2. Prepare Your Branch

6
docs/src/chapter-11/security-features.md
View file

@ -230,9 +230,9 @@ MINIO_ACCESS_KEY="minioadmin"
MINIO_SECRET_KEY="minioadmin"
MINIO_USE_SSL=true
# Qdrant (Vector Database) configuration
QDRANT_URL="http://localhost:6333"
QDRANT_API_KEY="your-api-key"
# Vector Database configuration
# Configure in your .env file
# Cache configuration
CACHE_URL="redis://localhost:6379"

176
docs/src/chapter-11/user-auth.md
View file

@ -1,10 +1,10 @@
# User Authentication
BotServer uses Zitadel, an open-source identity management platform, for user authentication and authorization. No passwords are stored internally in BotServer.
BotServer uses a directory service component for user authentication and authorization. No passwords are stored internally in BotServer.
## Overview
Authentication in BotServer is handled entirely by Zitadel, which provides:
Authentication in BotServer is handled entirely by the directory service, which provides:
- User identity management
- OAuth 2.0 / OpenID Connect (OIDC) authentication
- Single Sign-On (SSO) capabilities
@ -14,35 +14,124 @@ Authentication in BotServer is handled entirely by Zitadel, which provides:
## Architecture
### Zitadel Integration
### Directory Service Integration
BotServer integrates with Zitadel through:
- **ZitadelClient**: Client for API communication
BotServer integrates with the directory service through:
- **DirectoryClient**: Client for API communication
- **AuthService**: Service layer for authentication operations
- **OIDC Flow**: Standard OAuth2/OIDC authentication flow
- **Service Account**: For administrative operations
### No Internal Password Storage
- **No password_hash columns**: Users table only stores Zitadel user IDs
- **No Argon2 hashing**: All password operations handled by Zitadel
- **No password reset logic**: Managed through Zitadel's built-in flows
- **No password_hash columns**: Users table only stores directory user IDs
- **No Argon2 hashing**: All password operations handled by directory service
- **No password reset logic**: Managed through directory service's built-in flows
- **Session tokens only**: BotServer only manages session state
## Authentication Flow
### Authentication Architecture
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Browser │◄────────│ BotServer │────────►│ Directory │
│ │ │ │ │ Service │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
│ 1. Login Request │ │
├───────────────────────►│ │
│ │ 2. Redirect to OIDC │
│ ├────────────────────────►│
│ │ │
│ 3. Show Login Page │◄────────────────────────│
│◄───────────────────────┤ │
│ │ │
│ 4. Enter Credentials │ │
├────────────────────────┼────────────────────────►│
│ │ │
│ │ 5. Return Tokens │
│ │◄────────────────────────│
│ 6. Set Session Cookie │ │
│◄───────────────────────│ │
│ │ │
│ 7. Authenticated! │ │
└────────────────────────┘ │
│
Database │
┌──────────────┐ │
│ PostgreSQL │◄───────────────┘
│ • Sessions │ User Sync
│ • User Refs │
└──────────────┘
```
### User Registration
1. User registration request sent to Zitadel
2. Zitadel creates user account
```
User → BotServer → Zitadel
│ │ │
│ Register │
├───────►│ │
│ │ Create │
│ ├─────────►│
│ │ ├─► Generate ID
│ │ ├─► Hash Password
│ │ ├─► Store User
│ │ User ID │
│ │◄─────────┤
│ ├─► Create Local Ref
│ ├─► Start Session
│ Token │
│◄───────┤
│ │
```
1. User registration request sent to directory service
2. Directory service creates user account
3. User ID returned to BotServer
4. BotServer creates local user reference
5. Session established with BotServer
### User Login
1. User redirected to Zitadel login page
2. Credentials validated by Zitadel
```
Browser BotServer Directory
│ │ │
│ GET /login │ │
├──────────────────────►│ │
│ │ │
│ 302 Redirect │ │
│◄──────────────────────┤ │
│ to Directory │ │
│ │ │
│ │
├────────────────────────────────────────────►│
│ Show Login Form │
│◄────────────────────────────────────────────┤
│ │
│ Submit Credentials │
├────────────────────────────────────────────►│
│ │
│ ├─► Validate
│ ├─► Generate Tokens
│ │
│ Redirect + Tokens │
│◄────────────────────────────────────────────┤
│ │ │
│ /auth/callback │ │
├──────────────────────►│ │
│ ├─► Validate Tokens │
│ ├─► Create Session │
│ ├─► Store in DB │
│ Set Cookie │ │
│◄──────────────────────┤ │
│ Redirect to App │ │
│ │ │
```
1. User redirected to directory service login page
2. Credentials validated by directory service
3. OIDC tokens returned via callback
4. BotServer validates tokens
5. Local session created
@ -50,37 +139,68 @@ BotServer integrates with Zitadel through:
### Token Validation
```
Request Flow Validation Pipeline
│ │
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ Request │ │ Extract Token │
│ + Cookie │ │ from Cookie/Header │
└──────┬───────┘ └──────────┬───────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ BotServer │ │ Check Session │
│ Validates │◄─────────────│ in Local Cache │
└──────┬───────┘ └──────────┬───────────┘
│ │
│ ├─► Valid? Continue
│ │
│ ├─► Expired?
▼ │
┌──────────────┐ ┌──────────────────────┐
│ Directory │◄─────────────│ Refresh with │
│ Refresh │ │ Directory API │
└──────┬───────┘ └──────────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ Process │ │ Load User Context │
│ Request │ │ Apply Permissions │
└──────────────┘ └──────────────────────┘
```
1. Client includes session token
2. BotServer validates local session
3. Optional: Refresh with Zitadel if expired
4. User context loaded from Zitadel
3. Optional: Refresh with directory service if expired
4. User context loaded from directory service
5. Request processed with user identity
## Zitadel Configuration
## Directory Service Configuration
### Environment Variables
```bash
# Zitadel connection
ZITADEL_ISSUER_URL=http://localhost:8080
ZITADEL_API_URL=http://localhost:8080/management/v1
ZITADEL_CLIENT_ID=<generated-client-id>
ZITADEL_CLIENT_SECRET=<generated-client-secret>
ZITADEL_PROJECT_ID=<project-id>
# Directory service connection
DIRECTORY_ISSUER_URL=http://localhost:8080
DIRECTORY_API_URL=http://localhost:8080/management/v1
DIRECTORY_CLIENT_ID=<generated-client-id>
DIRECTORY_CLIENT_SECRET=<generated-client-secret>
DIRECTORY_PROJECT_ID=<project-id>
# Service account for admin operations
ZITADEL_SERVICE_ACCOUNT_KEY=<service-account-key>
DIRECTORY_ADMIN_TOKEN=zitadel-admin-sa
DIRECTORY_SERVICE_ACCOUNT_KEY=<service-account-key>
DIRECTORY_ADMIN_TOKEN=directory-admin-sa
# OAuth redirect
ZITADEL_REDIRECT_URI=http://localhost:8080/auth/callback
DIRECTORY_REDIRECT_URI=http://localhost:8080/auth/callback
```
### Auto-Configuration
During bootstrap, BotServer automatically:
1. Installs Zitadel binary
2. Configures Zitadel with PostgreSQL
1. Installs directory service (Zitadel) via installer.rs
2. Configures directory service with PostgreSQL
3. Creates default organization
4. Sets up service account
5. Creates initial admin user
@ -93,11 +213,11 @@ During bootstrap, BotServer automatically:
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Internal BotServer ID |
| zitadel_id | TEXT | User ID in Zitadel |
| directory_id | TEXT | User ID in directory service |
| username | TEXT | Cached username |
| email | TEXT | Cached email |
| created_at | TIMESTAMPTZ | First login time |
| updated_at | TIMESTAMPTZ | Last sync with Zitadel |
| updated_at | TIMESTAMPTZ | Last sync with directory |
Note: No password_hash or any password-related fields exist.

87
docs/src/chapter-12/README.md
View file

@ -13,6 +13,54 @@ The BotServer REST API enables:
- System administration
- Analytics and monitoring
### API Architecture
```
Client Applications
│
▼
┌─────────────────────┐
│ HTTP/HTTPS │
│ Port 8080 │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ API Gateway │
│ /api/* │
└──────────┬──────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Auth │ │ Business │ │ Admin │
│ Endpoints │ │ Endpoints │ │ Endpoints │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ /auth/login │ │ /files/* │ │ /admin/* │
│ /auth/logout │ │ /users/* │ │ /monitoring │
│ /auth/token │ │ /groups/* │ │ /analytics │
└──────┬───────┘ │ /tasks/* │ └──────┬───────┘
│ │ /calendar/* │ │
│ └──────┬────────┘ │
│ │ │
└──────────────────┼───────────────────┘
│
┌─────────▼──────────┐
│ Service Layer │
│ • Session Manager │
│ • Auth Service │
│ • Bot Service │
└─────────┬──────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PostgreSQL │ │ Valkey │ │ Qdrant │
│ Database │ │ Cache │ │ Vectors │
└──────────────┘ └──────────────┘ └──────────────┘
```
## Base URL
All API endpoints are served from:
@ -42,6 +90,45 @@ Authenticate through Zitadel OAuth flow or use the login endpoint to obtain a se
## API Categories
### API Request Flow
```
HTTP Request
│
▼
┌─────────────┐
│ Rate Limit │ → Check request limits
└──────┬──────┘
│ Pass
▼
┌─────────────┐
│ Auth │ → Validate token/session
└──────┬──────┘
│ Valid
▼
┌─────────────┐
│ Route │ → Match endpoint pattern
└──────┬──────┘
│
▼
┌─────────────┐
│ Validate │ → Check request body
└──────┬──────┘
│ Valid
▼
┌─────────────┐
│ Process │ → Execute business logic
└──────┬──────┘
│
▼
┌─────────────┐
│ Format │ → JSON response
└──────┬──────┘
│
▼
HTTP Response
```
### Core APIs
- **[Files API](./files-api.md)** - File upload, download, and management

135
docs/src/glossary.md
View file

@ -1,70 +1,149 @@
# Glossary
Quick lookup for BotServer terms. If you're lost, start here.
## A
**Auto-Bootstrap** - The magical first run that installs everything automatically. PostgreSQL, cache, storage - all configured without you lifting a finger.
**Argon2** - Password hashing algorithm used for secure credential storage (winner of Password Hashing Competition)
**AST** - Abstract Syntax Tree, the compiled representation of BASIC scripts used for execution
**Authentication Flow** - Process of verifying user identity through credentials and establishing a session
**Argon2** - The Fort Knox of password hashing. Makes brute-force attacks computationally infeasible. We use it everywhere passwords are stored.
## B
**BASIC** - The scripting language used in .gbdialog files for creating conversational flows
**Bot Authentication** - Process of verifying a bot's credentials before allowing access
**BASIC** - Yes, that programming language from 1964. We brought it back because `TALK "Hello"` beats `await ctx.send()` any day. Powers all conversation scripts.
**BotSession** - A single conversation instance between a user and bot, maintaining context and history
**Bot Package** - A folder ending in `.gbai` containing everything to run a bot. Scripts, documents, config. That's it. Copy folder = deploy bot.
**BotSession** - The conversation between user and bot. Remembers everything - who you are, what you said, where you left off. Persists to database, cached for speed.
## C
**Collection** - A group of documents in a knowledge base that are indexed together for semantic search
**Context** - The current state and history of a conversation that influences bot responses
**Collection** - A folder of documents in `.gbkb/` that becomes searchable knowledge. Drop PDFs in `policies/`, bot answers policy questions. Zero configuration.
**Context** - What the LLM knows right now. Includes conversation history, active knowledge bases, loaded tools. Limited by token window (usually 4-8k tokens).
**config.csv** - The only config file you need. Simple key-value pairs in CSV format. Opens in Excel. Lives in `.gbot/` folder.
## D
**Dialog** - A conversation script written in BASIC that defines bot behavior and flow
**Dialog** - A `.bas` script defining conversation flow. Not complex state machines - just simple BASIC code like `TALK "Hi"` and `answer = HEAR`.
**Drive** - Built-in S3-compatible storage (SeaweedFS). Stores documents, templates, uploads. Auto-installed during bootstrap. No AWS account needed.
## E
**Embedding** - A vector representation of text used for semantic similarity comparisons
**Embedding** - Text converted to numbers for similarity search. "dog" and "puppy" have similar embeddings. BGE model by default, replaceable with any GGUF model.
**Event Handler** - BASIC code that runs when something happens. `ON "login"` runs at login. `ON "email"` when email arrives. `ON "0 8 * * *"` at 8 AM daily.
## G
**.gbai** - General Bot Application Interface, the root package containing bot architecture
**.gbdialog** - Package containing BASIC scripts for conversation flows
**.gbai** - "General Bot AI" folder. Contains entire bot. Example: `support.gbai/` becomes bot at `/support`. No manifest files, no build process.
**.gbkb** - General Bot Knowledge Base, package for document collections and semantic search
**.gbdialog** - Subfolder with BASIC scripts. Must contain `start.bas` as entry point. Tools go in `tools/` subdirectory.
**.gbot** - Package containing bot configuration and parameters
**.gbkb** - "Knowledge Base" subfolder. Each subdirectory becomes a searchable collection. PDFs, Word docs, text files - all automatically indexed.
**.gbtheme** - Package for UI theming and customization
**.gbot** - Configuration subfolder. Contains single `config.csv` file with bot settings. Missing values use defaults.
**.gbtheme** - Optional UI customization. CSS files, images, HTML templates. Most bots don't need this.
## H
**HEAR** - BASIC keyword to get user input. `name = HEAR` waits for user to type, stores response in variable.
**Hot Reload** - Change scripts while bot runs. Edit file, bot uses new version immediately. No restart needed (unless changing config).
## K
**Knowledge Base** - A collection of documents that provide contextual information to the bot
**Knowledge Base (KB)** - Documents the bot can search. Organized in folders under `.gbkb/`. Use with `USE KB "foldername"` in scripts.
**Keyword** - BASIC command like TALK, HEAR, LLM. About 40 total. All caps by convention, not requirement.
## L
**LLM** - Large Language Model, AI system used for generating responses
**LLM** - Large Language Model (ChatGPT, Claude, Llama). The AI brain that powers natural conversation understanding.
**Local Mode** - Run everything on your machine. LLM runs locally (llama.cpp), no internet required. Slower but private.
## M
**MCP** - Model Context Protocol, a standard for tool definitions
**Drive** - S3-compatible object storage component used for file management
**MCP** - Model Context Protocol. Standard format for defining tools that LLMs can call. Alternative to OpenAI function format.
**Memory** - Two types: Session (temporary, per conversation) and Bot (permanent, across all sessions). `SET` for session, `SET BOT MEMORY` for permanent.
## P
**Parameter** - Input definition for tools that specifies type, format, and description
**Package Manager** - Built-in system that installs/manages components. Handles PostgreSQL, cache, storage, vector DB, LLM server. All automatic.
**PARAM** - Defines tool parameters. `PARAM name, email, date` means tool needs these three inputs. LLM collects them automatically.
**PostgreSQL** - The database. Stores users, sessions, messages, bot config. Auto-installed, auto-configured, auto-migrated.
## Q
**Qdrant** - Vector database used for semantic search and embeddings
**Qdrant** - Vector database for semantic search. Stores document embeddings. Finds similar content even with different words. Optional but recommended.
## R
**Rhai** - The scripting engine powering BASIC interpreter. Rust-based, sandboxed, safe. You never see it directly.
## S
**Session** - See BotSession
**Session Token** - Unique identifier issued after authentication that validates subsequent requests
**Script** - A `.bas` file with BASIC code. `start.bas` runs first. Can call others with `RUN "other.bas"`.
**Semantic Search** - Search method that finds content based on meaning rather than just keywords
**Semantic Search** - Finding by meaning, not keywords. "vacation policy" finds "time off guidelines". Powered by embeddings and vector similarity.
**Session** - See BotSession. The container for a conversation.
**Session Token** - Random string identifying a session. Stored in browser localStorage for web, passed as header for API. Unguessable for security.
## T
**Tool** - A function that extends bot capabilities, defined with parameters and BASIC logic
**TALK** - BASIC keyword to send message. `TALK "Hello world"` displays that text to user.
**Template** - Example bot in `templates/` folder. Copy, modify, deploy. `default.gbai` is minimal starter, `announcements.gbai` shows advanced features.
**Tool** - A `.bas` file the LLM can call. Has PARAM definitions and DESCRIPTION. Put in `tools/` folder. AI figures out when to use it.
**Token** - Unit of text for LLMs. Roughly 4 characters. GPT-3.5 handles 4k tokens, GPT-4 handles 8k-128k. Includes prompt + response.
## U
**USE KB** - BASIC command to activate knowledge base. `USE KB "policies"` makes policies folder searchable for that session.
**USE TOOL** - BASIC command to enable a tool. `USE TOOL "send-email"` lets LLM send emails when appropriate.
## V
**Vector** - Numerical representation of data used in semantic search and AI systems
**Valkey** - Redis-compatible cache (fork after Redis license change). Stores session data for fast access. Auto-installed during bootstrap.
**Vector** - Mathematical representation of meaning. "Cat" might be [0.2, 0.8, -0.3, ...]. Similar meanings have similar vectors.
**Vector Collection** - See Collection. Folder of documents converted to vectors for semantic search.
## W
**WebSocket** - Real-time connection for chat. Enables instant messaging without polling. Path: `/ws` on same port as HTTP.
## Symbols
**.bas** - File extension for BASIC scripts. Plain text files with BASIC code.
**.csv** - Configuration format. Simple, editable in Excel, no JSON parsing needed.
**.env** - Environment variables file. Auto-generated during bootstrap with credentials and settings.
## Common Confusions
**"Do I need containers?"** - No. BotServer installs everything directly or in LXC containers.
**"What database?"** - PostgreSQL, auto-installed, auto-configured.
**"What about scaling?"** - Single server handles 1000+ concurrent users. Scale by running multiple instances.
**"Is BASIC really BASIC?"** - Inspired by BASIC, not strict implementation. Simpler, focused on conversations.
**"Can I use TypeScript/Python/etc?"** - No. BASIC only for conversation logic. Extend core in Rust if needed.
**"Is it production-ready?"** - Yes. Used in production since 2016 (earlier versions), current Rust version since 2023.

333
docs/src/introduction.md
View file

@ -1,252 +1,173 @@
# Introduction to BotServer
BotServer is an open-source conversational AI platform that enables users to create, deploy, and manage intelligent chatbots using a simple BASIC-like scripting language. Built in Rust with a focus on performance and security, it provides a complete ecosystem for building production-ready bot applications.
**Build conversational AI bots in minutes, not months.** BotServer lets you create intelligent chatbots by writing simple BASIC scripts and dropping in your documents. No complex frameworks, no cloud dependencies, no AI expertise required.
## What is BotServer?
## Quick Example
BotServer is a monolithic Rust application that combines multiple services into a unified platform for bot development:
- **BASIC Scripting**: Create conversation flows using simple, English-like `.bas` scripts
- **Template System**: Organize bots as `.gbai` packages with dialogs, knowledge bases, and configuration
- **Vector Search**: Semantic document retrieval using Qdrant vector database
- **LLM Integration**: Support for OpenAI, local models, and custom providers
- **Multi-Channel**: Web interface, WebSocket, voice, and extensible channel support
- **Auto-Bootstrap**: Automated installation and configuration of all dependencies
- **Enterprise Security**: Argon2 password hashing, AES-GCM encryption, secure session management
## Architecture
BotServer is implemented as a single Rust crate (version 6.0.8) with modular components:
### Core Modules
- **`auth`** - User authentication with Argon2 password hashing
- **`bot`** - Bot lifecycle and configuration management
- **`session`** - Persistent session state and conversation history
- **`basic`** - BASIC-like scripting language interpreter (powered by Rhai)
- **`llm`** - LLM provider integration (OpenAI, local models)
- **`context`** - Conversation context and memory management
### Infrastructure Modules
- **`bootstrap`** - Automated system initialization and component installation
- **`package_manager`** - Manages 20+ components (PostgreSQL, cache, drive, Qdrant, etc.)
- **`web_server`** - Axum-based HTTP API and WebSocket server
- **`drive`** - S3-compatible object storage and vector database integration
- **`config`** - Application configuration from `.env` and database
### Feature Modules
- **`automation`** - Cron scheduling and event-driven tasks
- **`email`** - IMAP/SMTP email integration (optional feature)
- **`meet`** - LiveKit video conferencing integration
- **`channels`** - Multi-channel abstraction layer
- **`file`** - Document processing (PDF extraction, parsing)
- **`drive_monitor`** - File system monitoring and automatic indexing
## Package System
Bots are organized as template-based packages in the `templates/` directory:
Want a student enrollment bot? Here's all you need:
1. **Drop your documents** in a folder:
```
templates/
├── default.gbai/ # Minimal starter bot
│ └── default.gbot/
│ └── config.csv
└── announcements.gbai/ # Full-featured example
├── announcements.gbdialog/
│ ├── start.bas
│ ├── auth.bas
│ └── *.bas
├── announcements.gbkb/
│ ├── auxiliom/
│ ├── news/
│ └── toolbix/
└── annoucements.gbot/
└── config.csv
edu.gbkb/
enrollment-policy.pdf
course-catalog.pdf
```
### Package Components
- **`.gbai`** - Root directory container for bot resources
- **`.gbdialog`** - BASIC scripts (`.bas` files) defining conversation logic
- **`.gbkb`** - Document collections for semantic search
- **`.gbot`** - Bot configuration in `config.csv` format
- **`.gbtheme`** - Optional UI customization (CSS/HTML)
- **`.gbdrive`** - Drive (S3-compatible) storage integration
## Key Features
### BASIC Scripting Language
Create conversations with simple, readable syntax:
2. **Write a simple tool** (optional):
```basic
let resume = GET_BOT_MEMORY("introduction");
SET_CONTEXT "general" AS resume;
TALK "Hello! I'm your assistant."
TALK "How can I help you today?"
let response = HEAR;
let answer = LLM("Answer the user's question: " + response);
TALK answer;
' enrollment.bas
PARAM name, email, course
SAVE "enrollments.csv", name, email, course
TALK "Welcome to " + course + "!"
```
Custom keywords include:
- `TALK` / `HEAR` - Conversation I/O
- `LLM` - Call language models
- `GET_BOT_MEMORY` / `SET_BOT_MEMORY` - Persistent storage
- `SET_CONTEXT` / `USE_KB` - Knowledge base management
- `USE_TOOL` / `LIST_TOOLS` - Tool integration
- `SET_SCHEDULE` / `ON` - Automation and events
- `GET` / `FIND` / `SET` - Data operations
- `FOR EACH` / `EXIT FOR` - Control flow
3. **Chat naturally**:
```
User: I want to enroll in computer science
Bot: I'll help you enroll! What's your name?
User: Sarah Chen
Bot: Welcome to Computer Science, Sarah!
```
### Knowledge Base & Semantic Search
### The Flow
- Store documents in `.gbkb/` collections
- Automatic indexing into Qdrant vector database
- Semantic search using embeddings
- Context retrieval for LLM augmentation
- Support for multiple document formats
![Conversation Flow](./assets/conversation-flow.svg)
### Auto-Bootstrap System
The AI handles everything else - understanding intent, collecting information, executing tools, answering from documents. Zero configuration.
BotServer automatically installs and configures:
## What Makes BotServer Different
1. **PostgreSQL** - User accounts, sessions, bot configuration
2. **Cache (Valkey)** - Session cache and temporary data
3. **Drive** - S3-compatible object storage
4. **Qdrant** - Vector database for semantic search
5. **Local LLM** - Optional local model server
6. **Email Server** - Optional SMTP/IMAP
7. **LiveKit** - Optional video conferencing
8. And more...
### Just Run It
```bash
./botserver
```
That's it. No Kubernetes, no cloud accounts. The bootstrap process installs everything locally in 2-5 minutes. PostgreSQL, vector database, object storage, cache - all configured automatically with secure credentials.
The bootstrap process:
- Generates secure credentials automatically
- Applies database migrations
- Creates bots from templates
- Uploads resources to storage
- Configures all components
### Real BASIC, Real Simple
Remember BASIC from the 80s? We brought it back for conversational AI:
```basic
' save-note.bas - A simple tool
PARAM topic, content
SAVE "notes.csv", topic, content, NOW()
TALK "Note saved!"
```
### Multi-Bot Hosting
Four lines. That's a working tool the AI can call automatically.
A single BotServer instance can host multiple bots:
### Documents = Knowledge
Drop PDFs, Word docs, or text files into `.gbkb/` folders. They're instantly searchable. No preprocessing, no configuration, no pipelines. The bot answers questions from your documents automatically.
- Each bot is isolated with separate configuration
- Bots share infrastructure (database, cache, storage)
- Independent update cycles per bot
- Optional multi-tenancy support
### Tools = Functions
Create `.bas` files that the AI discovers and calls automatically. Need to save data? Send emails? Call APIs? Just write a tool. The AI figures out when and how to use it.
### Security Features
## Architecture at a Glance
- **Password Hashing**: Argon2 with secure parameters
- **Encryption**: AES-GCM for sensitive data at rest
- **Session Management**: Cryptographically random tokens
- **API Authentication**: Token-based access control
- **Credential Generation**: Automatic secure password creation
- **Database Security**: Parameterized queries via Diesel ORM
BotServer is a single binary that includes everything:
### LLM Integration
![BotServer Architecture](./assets/architecture.svg)
Flexible AI provider support:
One process, one port, one command to run. Deploy anywhere - laptop, server, container.
- **OpenAI**: GPT-3.5, GPT-4, and newer models
- **Local Models**: Self-hosted LLM servers (llama.cpp compatible)
- **Streaming**: Token-by-token response streaming
- **Context Management**: Automatic context window handling
- **Model Selection**: Choose models based on task complexity
## Real-World Use Cases
### Storage Architecture
### Customer Support Bot
```
documents: FAQs, policies, procedures
tools: ticket creation, status lookup
result: 24/7 support that actually helps
```
- **PostgreSQL**: Structured data (users, bots, sessions, messages)
- **Cache**: Session cache and rate limiting
- **Drive (S3)**: Documents, templates, and assets
- **Qdrant**: Vector embeddings for semantic search
- **File System**: Optional local caching
### Employee Assistant
```
documents: HR policies, IT guides, company info
tools: leave requests, equipment orders
result: Instant answers, automated workflows
```
## How It Works
### Sales Catalog Bot
```
documents: product specs, pricing sheets
tools: quote generation, order placement
result: Interactive product discovery
```
1. **Bootstrap**: System scans `templates/` and creates bots from `.gbai` packages
2. **User Connection**: User connects via web interface or API
3. **Session Creation**: System creates authenticated session with unique token
4. **Dialog Execution**: Bot loads and executes `.gbdialog` scripts
5. **Knowledge Retrieval**: Queries vector database for relevant context
6. **LLM Integration**: Sends context + user message to language model
7. **Response**: Bot responds through appropriate channel
8. **State Persistence**: Session and conversation history saved to database
### Meeting Assistant
```
documents: agenda, previous minutes
tools: action item tracking, scheduling
result: AI-powered meeting facilitator
```
## Technology Stack
## The Package System
- **Language**: Rust (2021 edition)
- **Web Framework**: Axum + Tower
- **Async Runtime**: Tokio
- **Database**: Diesel ORM with PostgreSQL
- **Cache**: Valkey client (Redis-compatible, tokio-comp)
- **Storage**: AWS SDK S3 (drive compatible)
- **Vector DB**: Qdrant client (optional feature)
- **Scripting**: Rhai engine for BASIC interpreter
- **Security**: Argon2, AES-GCM, HMAC-SHA256
- **Desktop**: Tauri (optional feature)
- **Video**: LiveKit SDK
Bots are organized as packages - just folders with a naming convention:
## Installation Modes
```
my-bot.gbai/ # Package root
├── my-bot.gbdialog/ # BASIC scripts
│ └── start.bas # Entry point
├── my-bot.gbkb/ # Knowledge base
│ ├── policies/ # Document collection
│ └── procedures/ # Another collection
└── my-bot.gbot/ # Configuration
└── config.csv # Bot settings
```
BotServer supports multiple deployment modes:
### How It Works
- **Local**: Install components directly on the host system
- **Container**: Use LXC containers for isolation
![Package System Flow](./assets/package-system-flow.svg)
The `package_manager` handles component lifecycle in all modes.
That's it. No XML, no JSON schemas, no build process. Copy the folder to deploy.
## Use Cases
## Getting Started in 3 Steps
- **Customer Support**: Automated help desk with knowledge base
- **Internal Tools**: Employee assistance with company documentation
- **Product Catalogs**: Conversational product search and recommendations
- **Announcements**: Broadcast system with intelligent Q&A
- **Meeting Bots**: AI assistant for video conferences
- **Email Automation**: Intelligent email response and routing
- **Document Management**: Semantic search across document collections
### 1. Install (2 minutes)
```bash
wget https://github.com/GeneralBots/BotServer/releases/latest/botserver
chmod +x botserver
./botserver
```
## Getting Started
### 2. Open Browser
```
http://localhost:8080
```
1. **Install BotServer** following Chapter 01 instructions
2. **Run Bootstrap** to install dependencies automatically
3. **Explore Templates** in `templates/announcements.gbai/`
4. **Create Your Bot** by adding a new `.gbai` package
5. **Write Dialogs** using BASIC scripts in `.gbdialog/`
6. **Add Knowledge** by placing documents in `.gbkb/`
7. **Configure** via `config.csv` in `.gbot/`
8. **Restart** to activate your bot
### 3. Start Chatting
The default bot is ready. Ask it anything. Modify `templates/default.gbai/` to customize.
## Documentation Structure
## Core Philosophy
This book is organized into the following parts:
1. **Simplicity First** - If it needs documentation, it's too complex
2. **Everything Included** - No external dependencies to manage
3. **Production Ready** - Secure, scalable, enterprise-grade from day one
4. **Developer Friendly** - Clear errors, hot reload, great debugging
5. **AI Does the Work** - Don't write logic the LLM can handle
- **Part I**: Getting started and basic usage
- **Part II**: Package system (`.gbai`, `.gbdialog`, `.gbkb`, `.gbot`, `.gbtheme`, `.gbdrive`)
- **Part III**: Knowledge base and vector search
- **Part IV**: UI theming and customization
- **Part V**: BASIC scripting language reference
- **Part VI**: Rust architecture and extending BotServer
- **Part VII**: Bot configuration parameters
- **Part VIII**: Tool integration and external APIs
- **Part IX**: Complete feature matrix
- **Part X**: Contributing and development
- **Part XI**: Authentication and security
- **Appendices**: Database schema and reference material
## Technical Highlights
## Project Information
- **Language**: Written in Rust for performance and safety
- **Database**: PostgreSQL with Diesel ORM
- **Cache**: Valkey (Redis-compatible) for sessions
- **Storage**: S3-compatible object store
- **Vectors**: Qdrant for semantic search
- **Security**: Argon2 passwords, AES encryption
- **LLM**: OpenAI API or local models
- **Scripting**: Rhai-powered BASIC interpreter
## What's Next?
- **[Chapter 01](./chapter-01/README.md)** - Install and run your first bot
- **[Chapter 02](./chapter-02/README.md)** - Understanding packages
- **[Chapter 05](./chapter-05/README.md)** - Writing BASIC dialogs
- **[Templates](./chapter-02/templates.md)** - Explore example bots
## Community
BotServer is open source (AGPL-3.0) developed by Pragmatismo.com.br and contributors worldwide.
- **GitHub**: https://github.com/GeneralBots/BotServer
- **Version**: 6.0.8
- **License**: AGPL-3.0
- **Repository**: https://github.com/GeneralBots/BotServer
- **Language**: Rust (monolithic crate)
- **Community**: Open-source contributors from Pragmatismo.com.br and beyond
- **Status**: Production Ready
## Next Steps
Continue to [Chapter 01: Run and Talk](./chapter-01/README.md) to install BotServer and start your first conversation.
Ready to build your bot? Turn to [Chapter 01](./chapter-01/README.md) and let's go!