diff --git a/PROMPT.md b/PROMPT.md index 7e50d7f7..4dfec605 100644 --- a/PROMPT.md +++ b/PROMPT.md @@ -1,49 +1,11 @@ -# botbook Development Prompt Guide +# botbook Development Guide -**Version:** 6.1.0 -**Purpose:** LLM context for botbook documentation development +**Version:** 6.2.0 +**Purpose:** Documentation for General Bots (mdBook) --- -## Weekly Maintenance - EVERY MONDAY - -### Package Review Checklist - -**Every Monday, review the following:** - -1. **Dependency Updates** - ```bash - cargo outdated - cargo audit - ``` - -2. **Package Consolidation Opportunities** - - Check if new crates can replace custom code - - Look for crates that combine multiple dependencies - - Review `Cargo.toml` for redundant dependencies - -3. **Documentation Sync** - - Verify docs match current implementation - - Check for deprecated keywords/features - - Update examples with latest syntax - -4. **Asset Updates** - - Sync icons with `botui/ui/suite/assets/icons/` - - Verify all screenshots are current - - Check external links are valid - -### Packages to Watch - -| Area | Potential Packages | Purpose | -|------|-------------------|---------| -| Markdown | `pulldown-cmark` | Better MD processing | -| Search | `tantivy` | Full-text search in docs | -| Diagrams | `mermaid` | Replace ASCII diagrams | -| i18n | `fluent` | Translation management | - ---- - -## CRITICAL: Keyword Naming Rules +## πŸ“š CRITICAL: Keyword Naming Rules **Keywords NEVER use underscores. Always use spaces.** @@ -53,25 +15,19 @@ SEND MAIL to, subject, body, attachments GENERATE PDF template, data, output MERGE PDF files, output DELETE "url" -DELETE "table", "filter" ON ERROR RESUME NEXT -CLEAR ERROR SET BOT MEMORY key, value -GET BOT MEMORY key KB STATISTICS -KB DOCUMENTS COUNT ``` ### ❌ WRONG - Never Use Underscores ```basic SEND_MAIL ' WRONG! GENERATE_PDF ' WRONG! -MERGE_PDF ' WRONG! DELETE_HTTP ' WRONG! -SET_HEADER ' WRONG! ``` -### Keyword Mappings (Documentation to Implementation) +### Keyword Mappings | Write This | NOT This | |------------|----------| | `SEND MAIL` | `SEND_MAIL` | @@ -79,58 +35,13 @@ SET_HEADER ' WRONG! | `MERGE PDF` | `MERGE_PDF` | | `DELETE` | `DELETE_HTTP` | | `SET HEADER` | `SET_HEADER` | -| `CLEAR HEADERS` | `CLEAR_HEADERS` | -| `GROUP BY` | `GROUP_BY` | | `FOR EACH` | `FOR_EACH` | -| `EXIT FOR` | `EXIT_FOR` | -| `ON ERROR RESUME NEXT` | (no underscore version) | - -### Special Keywords -- `GENERATE FROM TEMPLATE` = Use `FILL` keyword -- `GENERATE WITH PROMPT` = Use `LLM` keyword -- `DELETE` is unified - auto-detects HTTP URLs vs database tables vs files --- -## Official Icons - MANDATORY +## 🎨 OFFICIAL ICONS - MANDATORY -**NEVER generate icons with LLM. ALWAYS use official SVG icons from `src/assets/icons/`.** - -### Available Icons - -| Icon | File | Usage | -|------|------|-------| -| Logo | `gb-logo.svg` | Main GB branding | -| Bot | `gb-bot.svg` | Bot/assistant representation | -| Analytics | `gb-analytics.svg` | Charts, metrics, dashboards | -| Calendar | `gb-calendar.svg` | Scheduling, events | -| Chat | `gb-chat.svg` | Conversations, messaging | -| Compliance | `gb-compliance.svg` | Security, auditing | -| Designer | `gb-designer.svg` | Workflow automation | -| Drive | `gb-drive.svg` | File storage, documents | -| Mail | `gb-mail.svg` | Email functionality | -| Meet | `gb-meet.svg` | Video conferencing | -| Paper | `gb-paper.svg` | Document editing | -| Research | `gb-research.svg` | Search, investigation | -| Sources | `gb-sources.svg` | Knowledge bases | -| Tasks | `gb-tasks.svg` | Task management | -| Chart | `gb-chart.svg` | Data visualization | -| Check | `gb-check.svg` | Success, completion | -| Database | `gb-database.svg` | Data storage | -| Folder | `gb-folder.svg` | File organization | -| Gear | `gb-gear.svg` | Settings | -| Globe | `gb-globe.svg` | Web, internet | -| Lightbulb | `gb-lightbulb.svg` | Ideas, tips | -| Lock | `gb-lock.svg` | Security | -| Note | `gb-note.svg` | Notes, comments | -| Package | `gb-package.svg` | Packages, modules | -| Palette | `gb-palette.svg` | Themes, styling | -| Rocket | `gb-rocket.svg` | Launch, deploy | -| Search | `gb-search.svg` | Search functionality | -| Signal | `gb-signal.svg` | Connectivity | -| Target | `gb-target.svg` | Goals, objectives | -| Tree | `gb-tree.svg` | Hierarchy, structure | -| Warning | `gb-warning.svg` | Alerts, cautions | +**NEVER generate icons with LLM. Use official SVG icons from `botui/ui/suite/assets/icons/`** ### Usage in Documentation @@ -138,53 +49,13 @@ SET_HEADER ' WRONG! ![Chat](../assets/icons/gb-chat.svg) - + Analytics ``` -### Icon Guidelines - -- All icons use `stroke="currentColor"` for CSS theming -- ViewBox: `0 0 24 24` -- Stroke width: `1.5` -- Rounded line caps and joins -- Consistent with GB brand identity - -**DO NOT:** -- Generate new icons with AI/LLM -- Use emoji or unicode symbols as icons -- Use external icon libraries (FontAwesome, etc.) -- Create inline SVG diagrams when an official icon exists - --- -## Project Overview - -botbook is the **mdBook-based documentation** for the General Bots platform. It provides comprehensive guides, tutorials, and API references for users and developers. - -### Workspace Position - -``` -botbook/ # THIS PROJECT - Documentation -botserver/ # Main server (source of truth) -botlib/ # Shared library -botui/ # Web/Desktop UI -botapp/ # Desktop app -botmodels/ # Data models visualization -botplugin/ # Browser extension -``` - -### What botbook Provides - -- **User Guides**: Getting started, installation, quick start -- **BASIC Reference**: Keywords, syntax, examples -- **API Documentation**: REST endpoints, WebSocket -- **Configuration**: Settings, environment variables -- **Architecture**: System design, components - ---- - -## Structure +## πŸ“ STRUCTURE ``` botbook/ @@ -192,155 +63,94 @@ botbook/ β”œβ”€β”€ src/ β”‚ β”œβ”€β”€ SUMMARY.md # Table of contents β”‚ β”œβ”€β”€ README.md # Introduction -β”‚ β”œβ”€β”€ 01-introduction/ # Run and Talk (Quick Start) +β”‚ β”œβ”€β”€ 01-introduction/ # Quick Start β”‚ β”œβ”€β”€ 02-templates/ # Package System β”‚ β”œβ”€β”€ 03-knowledge-base/ # Knowledge Base -β”‚ β”œβ”€β”€ 04-gbui/ # UI System -β”‚ β”œβ”€β”€ 05-gbtheme/ # Theming β”‚ β”œβ”€β”€ 06-gbdialog/ # BASIC Dialogs -β”‚ β”œβ”€β”€ 07-gbapp/ # Applications β”‚ β”œβ”€β”€ 08-config/ # Configuration -β”‚ β”œβ”€β”€ 09-tools/ # Tools β”‚ β”œβ”€β”€ 10-rest/ # REST API -β”‚ β”œβ”€β”€ 11-features/ # Feature Modules -β”‚ β”œβ”€β”€ 12-auth/ # Authentication -β”‚ β”œβ”€β”€ 13-community/ # Contributing -β”‚ β”œβ”€β”€ 14-migration/ # Migration Guide -β”‚ β”œβ”€β”€ 15-appendix/ # Reference materials -β”‚ β”œβ”€β”€ 16-appendix-docs-style/ -β”‚ β”œβ”€β”€ 17-testing/ # Testing guide -β”‚ β”œβ”€β”€ 18-appendix-external-services/ -β”‚ β”œβ”€β”€ 19-maintenance/ # Maintenance β”‚ └── assets/ # Images, diagrams β”œβ”€β”€ i18n/ # Translations -β”‚ β”œβ”€β”€ cn/ # Chinese -β”‚ β”œβ”€β”€ en/ # English -β”‚ β”œβ”€β”€ ja/ # Japanese -β”‚ └── pt/ # Portuguese └── book/ # Generated output ``` --- -## Documentation Rules - -### CRITICAL REQUIREMENTS +## πŸ“– DOCUMENTATION RULES ``` - All documentation MUST match actual source code - Extract real keywords from botserver/src/basic/keywords/ -- Reference real models from botserver/src/shared/models.rs - Use actual examples from botserver/templates/ -- Version numbers must be 6.1.0 +- Version numbers must be 6.2.0 - No placeholder content - only verified features ``` -### Writing Style +--- +## 🚫 NO ASCII DIAGRAMS β€” MANDATORY + +**NEVER use ASCII art diagrams. ALL diagrams must be SVG.** + +### ❌ Prohibited ASCII Patterns ``` -- Beginner-friendly, instructional tone -- Practical examples that work -- Step-by-step instructions -- Clear headings and structure -- Use mdBook admonitions for tips/warnings +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” ╔═══════╗ +-------+ +β”‚ Box β”‚ β•‘ Box β•‘ | Box | +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β•šβ•β•β•β•β•β•β•β• +-------+ ``` -### Code Examples +### βœ… What to Use Instead -```markdown - -```bas -TALK "Hello, world!" -name = HEAR -TALK "Welcome, " + name +| Instead of... | Use... | +|---------------|--------| +| ASCII box diagrams | SVG diagrams in `assets/` | +| ASCII flow charts | SVG with arrows and boxes | +| ASCII directory trees | Markdown tables | -' Error handling -ON ERROR RESUME NEXT -result = SOME_OPERATION() -IF ERROR THEN - TALK "Error: " + ERROR MESSAGE -END IF -ON ERROR GOTO 0 +--- -' Email - note: spaces not underscores -SEND MAIL "user@example.com", "Subject", "Body", [] +## 🎨 SVG DIAGRAM GUIDELINES -' PDF generation - note: spaces not underscores -GENERATE PDF "template.html", data, "output.pdf" +All SVGs must support light/dark modes: -' Unified DELETE - auto-detects context -DELETE "https://api.example.com/resource/123" ' HTTP DELETE -DELETE "customers", "status = 'inactive'" ' Database DELETE -DELETE "temp/file.txt" ' File DELETE -``` - - -```csv -name,value -server_port,8080 -llm-url,http://localhost:8081 -``` - - -```rust -use botlib::prelude::*; -``` +```xml + ``` --- -## Building Documentation +## πŸ’¬ CONVERSATION EXAMPLES -```bash -# Install mdBook -cargo install mdbook +Use WhatsApp-style HTML format for bot interactions: -# Build documentation -cd botbook -mdbook build - -# Serve locally with hot reload -mdbook serve --open - -# Build specific language -mdbook build --dest-dir book-pt src-pt +```html +
+
+ +
+
+ +
+
``` --- -## Chapter Content Guidelines - -### Chapter 1: Run and Talk -- Quick start (5 minutes to running bot) -- Bootstrap process explanation -- First conversation walkthrough -- Session management basics - -### Chapter 2: Package System -- .gbai folder structure -- .gbot configuration -- .gbdialog scripts -- .gbkb knowledge bases -- .gbtheme customization - -### Chapter 6: BASIC Dialogs -- Keyword reference (from source) -- TALK, HEAR, SET, GET -- Control flow (IF, FOR, WHILE) -- Tool creation -- LLM integration - -### Chapter 8: Configuration -- config.csv format -- Environment variables -- Database configuration -- Service settings - ---- - -## Source Code References - -When documenting features, verify against actual source: +## πŸ“‹ SOURCE CODE REFERENCES | Topic | Source Location | |-------|-----------------| @@ -348,379 +158,30 @@ When documenting features, verify against actual source: | Database Models | `botserver/src/shared/models.rs` | | API Routes | `botserver/src/core/urls.rs` | | Configuration | `botserver/src/core/config/` | -| Bootstrap | `botserver/src/core/bootstrap/` | | Templates | `botserver/templates/` | -| Error Handling | `botserver/src/basic/keywords/errors/` | - -### Key Implementation Files -| Keyword Category | File | -|-----------------|------| -| `SEND MAIL`, `SEND TEMPLATE` | `send_mail.rs` | -| `GENERATE PDF`, `MERGE PDF` | `file_operations.rs` | -| `DELETE`, `INSERT`, `UPDATE` | `data_operations.rs` | -| `POST`, `PUT`, `GRAPHQL`, `SOAP` | `http_operations.rs` | -| `ON ERROR RESUME NEXT` | `errors/on_error.rs` | -| `KB STATISTICS`, `KB DOCUMENTS COUNT` | `kb_statistics.rs` | -| `LLM` | `llm_keyword.rs` | -| `FILL` (template filling) | `data_operations.rs` | --- -## NO ASCII DIAGRAMS β€” MANDATORY +## πŸ”§ BUILDING DOCUMENTATION -**NEVER use ASCII art diagrams in documentation. ALL diagrams must be SVG.** +```bash +# Install mdBook +cargo install mdbook -### Prohibited ASCII Patterns +# Build documentation +cd botbook && mdbook build -``` -❌ NEVER USE: -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” ╔═══════╗ +-------+ -β”‚ Box β”‚ β•‘ Box β•‘ | Box | -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β•šβ•β•β•β•β•β•β•β• +-------+ - -β”œβ”€β”€ folder/ β”‚ β†’ β–Ά ──► -β”‚ └── file β–Ό ← β—€ ◄── -``` - -### What to Use Instead - -| Instead of... | Use... | -|---------------|--------| -| ASCII box diagrams | SVG diagrams in `assets/` | -| ASCII flow charts | SVG with arrows and boxes | -| ASCII directory trees | Markdown tables or SVG | -| ASCII tables with borders | Markdown tables | -| ASCII progress indicators | SVG or text description | - -### Directory Trees β†’ Tables - -```markdown -❌ WRONG: -mybot.gbai/ -β”œβ”€β”€ mybot.gbdialog/ -β”‚ └── start.bas -└── mybot.gbot/ - └── config.csv - -βœ… CORRECT: -| Path | Description | -|------|-------------| -| `mybot.gbai/` | Root package | -| `mybot.gbdialog/` | BASIC scripts | -| `mybot.gbdialog/start.bas` | Entry point | -| `mybot.gbot/` | Configuration | -| `mybot.gbot/config.csv` | Bot settings | -``` - -### Rationale - -- ASCII breaks in different fonts/editors -- Not accessible for screen readers -- Cannot adapt to dark/light themes -- Looks unprofessional in modern docs -- SVGs scale perfectly at any size - ---- - -## SVG Diagram Guidelines β€” Theme Transparency - -All SVG diagrams MUST be theme-agnostic and work with light/dark modes. - -### Required Structure - -Every SVG must include: - -1. **CSS classes for text** (not hardcoded colors) -2. **Dark mode media query** in ` -``` - -### Standard Gradients (use these IDs) - -| Gradient ID | Colors | Purpose | -|-------------|--------|---------| -| `primaryGrad` | `#6366F1` β†’ `#8B5CF6` | Primary/purple elements | -| `cyanGrad` | `#06B6D4` β†’ `#0EA5E9` | Cyan/info elements | -| `greenGrad` | `#10B981` β†’ `#34D399` | Success/green elements | -| `orangeGrad` | `#F59E0B` β†’ `#FBBF24` | Warning/orange elements | - -### Background Rules - -- Use `fill="#FAFBFC"` for main background (not pure white) -- Add dot pattern overlay: `fill="url(#dots)"` with `opacity="0.08"` -- Cards use `fill="#FFFFFF"` with `stroke="#E2E8F0"` for definition -- Use `filter="url(#cardShadow)"` for card depth - -### DO NOT - -- ❌ Hardcode text colors without CSS class -- ❌ Use pure black (`#000000`) for text -- ❌ Forget the `@media (prefers-color-scheme: dark)` block -- ❌ Create new gradient IDs when standard ones exist -- ❌ Use ASCII art diagrams when SVG is appropriate - -### DO - -- βœ… Use CSS classes for ALL text elements -- βœ… Include dark mode media query in every SVG -- βœ… Use standard gradient IDs consistently -- βœ… Test SVGs in both light and dark browser modes -- βœ… Convert ASCII diagrams to proper SVGs -- βœ… Place SVGs in `src/assets/chapter-XX/` directories - -### Dimensions - -- Width: 600-1200px (responsive) -- Use `style="max-width: 100%; height: auto;"` when embedding - -### Reference - -See `src/16-appendix-docs-style/svg.md` for complete guidelines. - ---- - -## Translation Workflow - -1. English is source of truth (`src/`) -2. Translations in `src-{lang}/` -3. Keep structure identical -4. Update `book.toml` for each language -5. Build separately per language - ---- - -## Quality Checklist - -Before committing documentation: - -- [ ] All code examples tested and working -- [ ] Version numbers are 6.1.0 -- [ ] Links are valid (relative paths) -- [ ] Images have alt text -- [ ] SUMMARY.md is updated -- [ ] mdbook build succeeds without errors -- [ ] Content matches actual source code -- [ ] **NO underscores in keyword names** (use spaces) -- [ ] Model names are generic or current (no gpt-4o, claude-3, etc.) -- [ ] Error handling uses `ON ERROR RESUME NEXT` pattern correctly - ---- - -## Rules - -- **Accuracy**: Must match botserver source code -- **Completeness**: No placeholder sections -- **Clarity**: Accessible to BASIC enthusiasts -- **Version**: Always reference 6.1.0 -- **Examples**: Only working, tested code -- **Structure**: Follow mdBook conventions -- **Keywords**: NEVER use underscores - always spaces -- **Models**: Use generic references or current model names -- **Errors**: Document `ON ERROR RESUME NEXT` for error handling -- **Session Continuation**: When running out of context or time, NEVER use excuses like "due to time constraints". Instead, create a detailed summary of: (1) what was done, (2) what remains to be done, (3) specific files and line numbers to fix, (4) exact next steps. This allows the next session to continue seamlessly. - ---- - -## Quick Reference: Implemented Keywords - -### Error Handling -```basic -ON ERROR RESUME NEXT ' Enable error trapping -ON ERROR GOTO 0 ' Disable error trapping -CLEAR ERROR ' Clear error state -IF ERROR THEN ' Check if error occurred -ERROR MESSAGE ' Get last error message -ERR ' Get error number -THROW "message" ' Raise an error -``` - -### HTTP Operations -```basic -POST "url", data -PUT "url", data -PATCH "url", data -DELETE "url" ' Unified - works for HTTP, DB, files -SET HEADER "name", "value" -CLEAR HEADERS -GRAPHQL "url", query, variables -SOAP "wsdl", "operation", params -``` - -### File & PDF Operations -```basic -READ "path" -WRITE "path", content -COPY "source", "dest" -MOVE "source", "dest" -LIST "path" -COMPRESS files, "archive.zip" -EXTRACT "archive.zip", "dest" -UPLOAD file -DOWNLOAD "url" -GENERATE PDF template, data, "output.pdf" -MERGE PDF files, "output.pdf" -``` - -### Data Operations -```basic -FIND "table", "filter" -SAVE "table", data -INSERT "table", data -UPDATE "table", data, "filter" -DELETE "table", "filter" -MERGE "table", data, "key" -FILL data, template ' Template filling (was GENERATE FROM TEMPLATE) -MAP data, "mapping" -FILTER data, "condition" -AGGREGATE data, "operation" -``` - -### Knowledge Base & Accounts -```basic -USE KB "collection" -USE ACCOUNT "email@example.com" ' LLM search + file ops -CLEAR KB -KB STATISTICS -KB COLLECTION STATS "name" -KB DOCUMENTS COUNT -KB DOCUMENTS ADDED SINCE days -KB LIST COLLECTIONS -KB STORAGE SIZE -``` - -### LLM Operations -```basic -result = LLM "prompt" ' Generate with LLM (was GENERATE WITH PROMPT) -USE MODEL "model-name" -``` - -### Communication -```basic -TALK "message" -HEAR variable -SEND MAIL to, subject, body -SEND MAIL to, subject, body USING "account@example.com" -SEND TEMPLATE recipients, template, variables -``` - -### File Operations with Accounts -```basic -' account:// path notation (requires USE ACCOUNT first) -COPY "account://user@gmail.com/file.pdf" TO "local.pdf" -COPY "local.xlsx" TO "account://user@outlook.com/data.xlsx" +# Serve locally with hot reload +mdbook serve --open ``` --- -## Conversation Examples (WhatsApp Style) +## πŸ”‘ REMEMBER -All conversation examples throughout the book use the WhatsApp-style HTML format. This provides a familiar, visually consistent representation of bot interactions. - -### Standard Format - -```html -
-
- -
-
- -
-
-``` - -### Message Classes - -| Class | Usage | -|-------|-------| -| `wa-chat` | Container for the conversation | -| `wa-message` | Individual message wrapper | -| `wa-message user` | User message (right-aligned, colored) | -| `wa-message bot` | Bot message (left-aligned) | -| `wa-bubble` | Message bubble with styling | -| `wa-time` | Timestamp display | - -### Formatting Guidelines - -1. **User messages** β€” Use `wa-message user` class -2. **Bot messages** β€” Use `wa-message bot` class -3. **Timestamps** β€” Include `wa-time` div with realistic times -4. **Multi-line responses** β€” Use separate `

` tags for each line -5. **Status indicators** β€” Use text indicators (Success, Error, etc.) not emojis -6. **Bold text** β€” Use `` for emphasis -7. **Attachments** β€” Indicate with text like "[Attachment: filename.pdf]" - -### Complete Example - -```html -

- - - - - -
-``` - -### When to Use Each Format - -| Content Type | Format | -|--------------|--------| -| Interface screenshots | SVG wireframe | -| System architecture | SVG diagram | -| Data flow diagrams | SVG diagram | -| Bot conversations | WhatsApp HTML | -| API examples | Code blocks | -| Configuration | Code blocks | - -The WhatsApp chat styling is defined in `src/whatsapp-chat.css` and automatically included in the book build. +- **Accuracy** - Must match botserver source code +- **Completeness** - No placeholder sections +- **Clarity** - Accessible to BASIC enthusiasts +- **Keywords** - NEVER use underscores - always spaces +- **NO ASCII art** - Use SVG diagrams only +- **Version 6.2.0** - Always reference 6.2.0 diff --git a/src/11-features/feature-map.md b/src/11-features/feature-map.md new file mode 100644 index 00000000..165e4027 --- /dev/null +++ b/src/11-features/feature-map.md @@ -0,0 +1,343 @@ +# Cargo Feature Map + +This document provides a comprehensive reference for all Cargo.toml feature flags in General Bots, their dependencies, and how to use them for optimized builds. + +## Overview + +General Bots uses Rust's feature flag system to enable modular compilation. This allows you to: + +- **Reduce binary size** by excluding unused features +- **Minimize dependencies** for faster compilation +- **Customize deployments** for specific use cases +- **Control resource usage** in constrained environments + +## Feature Categories + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ BUNDLE FEATURES β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚communicationsβ”‚ β”‚productivity β”‚ β”‚ documents β”‚ β”‚ full β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ APPLICATION FEATURES β”‚ +β”‚ chat, mail, meet, calendar, tasks, drive, docs, paper... β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CORE TECHNOLOGIES β”‚ +β”‚ cache, automation, llm, vectordb, monitoring... β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Default Features + +The default feature set provides a minimal but functional installation: + +```toml +default = ["chat", "drive", "tasks", "automation", "cache", "directory"] +``` + +| Feature | Purpose | +|---------|---------| +| `chat` | AI chat interface | +| `drive` | File storage and management | +| `tasks` | Task scheduling and management | +| `automation` | BASIC script engine (Rhai) | +| `cache` | Redis session caching | +| `directory` | User directory services | + +## Communication Features + +Features for messaging, email, and real-time communication. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `chat` | - | Core chat functionality | +| `people` | - | Contact management | +| `mail` | lettre, mailparse, imap, native-tls | Full email client (IMAP/SMTP) | +| `meet` | livekit | Video conferencing | +| `social` | - | Social network integrations | +| `whatsapp` | - | WhatsApp Business API | +| `telegram` | - | Telegram Bot API | +| `instagram` | - | Instagram messaging | +| `msteams` | - | Microsoft Teams integration | + +### Bundle: `communications` + +Enables all communication features: + +```toml +communications = ["chat", "people", "mail", "meet", "social", + "whatsapp", "telegram", "instagram", "msteams", "cache"] +``` + +## Productivity Features + +Features for task management, scheduling, and project planning. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `calendar` | - | Event scheduling | +| `tasks` | cron, automation | Task management with scheduling | +| `project` | quick-xml | Project (MS Project style) | +| `goals` | - | Goal tracking and OKRs | +| `workspace` | - | Workspace management | +| `tickets` | - | Support ticket system | +| `billing` | - | Invoicing and payments | + +### Bundle: `productivity` + +```toml +productivity = ["calendar", "tasks", "project", "goals", "workspaces", "cache"] +``` + +## Document Features + +Features for document processing and file management. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `drive` | aws-config, aws-sdk-s3, aws-smithy-async, pdf-extract | Cloud storage (S3-compatible) | +| `docs` | docx-rs, ooxmlsdk | Word document processing | +| `paper` | docs, pdf-extract | AI-assisted writing | +| `sheet` | calamine, spreadsheet-ods | Spreadsheet processing | +| `slides` | ooxmlsdk | Presentation processing | + +### Bundle: `documents` + +```toml +documents = ["paper", "docs", "sheet", "slides", "drive"] +``` + +## Media Features + +Features for video, audio, and visual content. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `video` | - | Video processing | +| `player` | - | Media playback | +| `canvas` | - | Visual editor/whiteboard | + +### Bundle: `media` + +```toml +media = ["video", "player", "canvas"] +``` + +## Learning & Research Features + +Features for AI-powered research and learning. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `learn` | - | Learning management | +| `research` | llm, vectordb | AI research assistant | +| `sources` | - | Knowledge source management | + +### Bundle: `learning` + +```toml +learning = ["learn", "research", "sources"] +``` + +## Analytics Features + +Features for monitoring and business intelligence. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `analytics` | - | Usage analytics | +| `dashboards` | - | Custom BI dashboards | +| `monitoring` | sysinfo | System monitoring | + +### Bundle: `analytics_suite` + +```toml +analytics_suite = ["analytics", "dashboards", "monitoring"] +``` + +## Development Features + +Features for bot development and automation. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `designer` | - | Visual bot builder | +| `editor` | - | Code editor | +| `automation` | rhai, cron | BASIC script engine | + +### Bundle: `development` + +```toml +development = ["designer", "editor", "automation"] +``` + +## Admin Features + +Features for system administration. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `attendant` | - | Human handoff queue | +| `security` | - | Security settings | +| `settings` | - | Configuration UI | + +### Bundle: `admin` + +```toml +admin = ["attendant", "security", "settings"] +``` + +## Core Technologies + +Low-level features that other features depend on. + +| Feature | Dependencies | Description | +|---------|--------------|-------------| +| `llm` | - | LLM integration framework | +| `vectordb` | qdrant-client | Vector database for RAG | +| `nvidia` | - | NVIDIA GPU acceleration | +| `cache` | redis | Session caching | +| `compliance` | csv | Compliance/audit tools | +| `timeseries` | - | Time-series database | +| `weba` | - | Web accessibility features | +| `directory` | - | User directory services | +| `progress-bars` | indicatif | CLI progress indicators | +| `grpc` | tonic | gRPC server | +| `jemalloc` | tikv-jemallocator, tikv-jemalloc-ctl | Memory allocator | +| `console` | crossterm, ratatui, monitoring | Terminal UI mode | + +## Build Profiles + +### Minimal Build + +Smallest possible binary with core functionality: + +```bash +cargo build --release --no-default-features --features "chat,cache" +``` + +**Size**: ~15MB +**Use case**: Embedded devices, edge computing + +### Lightweight Build + +Core office features without heavy dependencies: + +```bash +cargo build --release --no-default-features \ + --features "chat,drive,tasks,cache,directory" +``` + +**Size**: ~25MB +**Use case**: Small deployments, resource-constrained servers + +### Standard Build (Default) + +Balanced feature set for most deployments: + +```bash +cargo build --release +``` + +**Size**: ~40MB +**Use case**: General purpose, development + +### Full Build + +All features enabled: + +```bash +cargo build --release --all-features +``` + +**Size**: ~80MB+ +**Use case**: Enterprise deployments, feature testing + +## Dependency Matrix + +``` +Feature | External Crates | Size Impact +-----------------+--------------------------------------+------------- +mail | lettre, mailparse, imap, native-tls | ~2MB +meet | livekit | ~5MB +vectordb | qdrant-client | ~3MB +drive | aws-sdk-s3, aws-config | ~4MB +docs | docx-rs, ooxmlsdk | ~2MB +sheet | calamine, spreadsheet-ods | ~1MB +automation | rhai, cron | ~2MB +cache | redis | ~1MB +console | crossterm, ratatui | ~1MB +monitoring | sysinfo | ~500KB +``` + +## Runtime Configuration + +Features can be further controlled at runtime via the `.product` file: + +```ini +# .product file +name=My Custom Bot +apps=chat,drive,tasks +theme=dark +``` + +The effective app list is the **intersection** of: +1. Features compiled in Cargo.toml +2. Apps enabled in `.product` file + +This means you can compile with many features but only expose a subset to users. + +## API Endpoint + +The `/api/product` endpoint returns the current feature matrix: + +```json +{ + "name": "General Bots", + "apps": ["chat", "drive", "tasks"], + "compiled_features": ["chat", "drive", "tasks", "automation", "cache", "directory"], + "theme": "sentient" +} +``` + +## Checking Compiled Features + +In Rust code, use conditional compilation: + +```rust +#[cfg(feature = "mail")] +fn handle_email() { + // Only compiled when mail feature is enabled +} +``` + +At runtime, check the `COMPILED_FEATURES` constant: + +```rust +use crate::core::features::COMPILED_FEATURES; + +if COMPILED_FEATURES.contains(&"mail") { + // Feature is available +} +``` + +## Best Practices + +1. **Start minimal**: Begin with the default features and add as needed +2. **Use bundles**: Prefer bundle features over individual ones for consistency +3. **Test builds**: Verify functionality after changing features +4. **Document requirements**: List required features in deployment docs +5. **Monitor size**: Track binary size as features are added + +## See Also + +- [Building from Source](../07-gbapp/building.md) +- [Cargo Tools Reference](../07-gbapp/cargo-tools.md) +- [White Label Configuration](../22-white-label/README.md) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 8ccc5304..171a82e0 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -304,6 +304,7 @@ - [Chapter 11: Feature Reference](./11-features/README.md) - [Feature Editions](./11-features/editions.md) - [Core Features](./11-features/core-features.md) + - [Cargo Feature Map](./11-features/feature-map.md) - [Conversation Management](./11-features/conversation.md) - [AI and LLM](./11-features/ai-llm.md) - [Knowledge Base](./11-features/knowledge-base.md)