gb/IMPROVE.md

General Bots AI Orchestrator Operating System - Architectural Improvements

Analysis Date: January 24, 2026
Analyzed Version: 6.1.0
Target Version: 7.0.0

---

Executive Summary

General Bots is a folder-based AI orchestrator where .gbai packages contain everything (BASIC scripts, documents, config). The system ALREADY has:

• LXC container isolation via botserver install --container
• Visual designer for BASIC scripts
• Package manager built-in (drop .gbai folder = deployed)
• Multi-agent via ADD BOT keyword in BASIC
• Single binary deployment model

This analysis focuses on ENHANCING what exists, not replacing it.

Current Architecture Analysis

What Already Exists (Don't Rebuild)

1. Package System (.gbai): Folder-based deployment - copy folder = deployed bot
2. LXC Container Isolation: botserver install vault --container creates isolated services
3. Visual Designer: Already exists for BASIC script creation
4. Multi-Agent: ADD BOT keyword enables bot-to-bot delegation
5. Single Binary: One botserver binary manages everything
6. Auto-Bootstrap: Scans templates/ for .gbai folders, auto-deploys
7. BASIC Scripting: Rhai-based interpreter with 80+ keywords
8. Built-in Package Manager: botserver install <component> handles dependencies

Real Strengths

1. Zero-Config Deployment: Drop .gbai folder in templates/, restart = live
2. BASIC Accessibility: Non-programmers can create AI workflows
3. Comprehensive Suite: 50+ integrated apps (CRM, docs, video, etc.)
4. Security-First: No unwrap(), proper error handling, SafeCommand wrapper
5. LXC Isolation: Each service (PostgreSQL, Vault, VectorDB) in own container
6. Feature Flags: Granular control from minimal to full deployment

Current Limitations (What to Actually Improve)

1. Multi-Agent Coordination: ADD BOT exists but lacks sophisticated orchestration patterns
2. Workflow Visualization: Designer exists but limited to linear BASIC scripts
3. Agent Memory: Basic episodic memory, lacks long-term agent learning
4. Cross-Bot Communication: Bots can delegate but no pub/sub or event bus
5. LLM Routing: Basic model selection, lacks intelligent routing based on task
6. Plugin Ecosystem: MCP support exists but no marketplace or discovery

---

Proposed Architectural Improvements

1. Enhanced Multi-Agent Orchestration (Priority: Critical)

Current State

• ADD BOT keyword enables bot delegation
• Basic priority and trigger matching
• No sophisticated coordination patterns

Proposed Enhancement: Agent Collaboration Patterns

Extend existing BASIC keywords, don't replace:

' Current (works)
ADD BOT "specialist" WITH TRIGGER "technical questions"

' Enhanced (new patterns)
ADD BOT "analyst" WITH ROLE "data-processor"
ADD BOT "reviewer" WITH ROLE "quality-check"

' New coordination keyword
ORCHESTRATE WORKFLOW
  STEP 1: BOT "researcher" GATHERS data
  STEP 2: BOT "analyst" PROCESSES data  
  STEP 3: BOT "writer" CREATES report
  STEP 4: HUMAN APPROVAL required
  STEP 5: BOT "publisher" DISTRIBUTES report
END WORKFLOW

Implementation:

• Add ORCHESTRATE WORKFLOW keyword to basic/keywords/
• Store workflow state in existing PostgreSQL
• Use existing ADD BOT infrastructure
• Leverage existing session management

Benefits:

• Builds on existing ADD BOT system
• BASIC-accessible workflow definition
• No new infrastructure needed

2. Visual Workflow Designer Enhancement (Priority: High)

Current State

• Designer exists for BASIC scripts
• Linear script editing
• No visual workflow representation

Proposed Enhancement: Drag-and-Drop Workflow Canvas

Extend existing designer, don't rebuild:

// Add to existing botserver/src/designer/
pub struct WorkflowNode {
    node_type: NodeType,
    basic_code: String,  // Generates BASIC
    position: (f32, f32),
}

pub enum NodeType {
    BotAgent { bot_name: String },
    HumanApproval { approvers: Vec<String> },
    Condition { expression: String },
    Loop { iterations: String },
    Parallel { branches: Vec<Branch> },
}

Output: Generates BASIC code using existing keywords

' Generated from visual designer
ORCHESTRATE WORKFLOW
  STEP 1: BOT "support" HANDLES initial_request
  IF priority = "high" THEN
    STEP 2: HUMAN APPROVAL FROM "manager"
  END IF
  STEP 3: BOT "resolver" COMPLETES task
END WORKFLOW

Benefits:

• Visual design → BASIC code generation
• Uses existing BASIC interpreter
• No new runtime needed

3. Agent Memory & Learning (Priority: Medium)

Current State

• Episodic memory via REMEMBER keyword
• Session-based context
• No long-term agent learning

Proposed Enhancement: Agent Knowledge Evolution

New BASIC keywords:

' Agent learns from interactions
AGENT LEARN FROM conversation_id
  PATTERN "customer prefers email"
  CONFIDENCE 0.8
END LEARN

' Agent recalls learned patterns
preferences = AGENT RECALL "customer communication"

' Agent shares knowledge with other bots
AGENT SHARE KNOWLEDGE WITH "support-bot-2"

Implementation:

• Store in existing VectorDB (Qdrant)
• Use existing knowledge base infrastructure
• Extend REMEMBER keyword functionality

4. Event-Driven Bot Communication (Priority: Medium)

Current State

• Bots delegate via ADD BOT
• Direct invocation only
• No pub/sub pattern

Proposed Enhancement: Event Bus in BASIC

New keywords:

' Subscribe to events
ON EVENT "new_ticket" DO
  priority = GET "priority" FROM EVENT
  IF priority = "urgent" THEN
    DELEGATE TO "escalation-bot"
  END IF
END ON

' Publish events
PUBLISH EVENT "ticket_resolved"
  WITH ticket_id = ticket_id
  WITH resolution = "Fixed"
END PUBLISH

' Cross-bot coordination
WAIT FOR EVENT "approval_received" TIMEOUT 3600

Implementation:

• Use existing Redis for pub/sub
• Extend existing session management
• Add event handlers to BASIC interpreter

5. Intelligent LLM Routing (Priority: Medium)

Current State

• Basic model selection via config
• MODEL ROUTING keyword exists
• No automatic optimization

Proposed Enhancement: Smart Model Selection

Enhanced BASIC keyword:

' Current
result = LLM "Analyze this data" WITH MODEL "gpt-4"

' Enhanced with auto-routing
result = LLM "Analyze this data" 
  WITH OPTIMIZE FOR "speed"      ' or "cost" or "quality"
  WITH MAX_COST 0.01
  WITH MAX_LATENCY 2000

' Learns from usage
AGENT LEARN MODEL PERFORMANCE
  TASK "data analysis"
  BEST_MODEL "claude-3"
  REASON "faster and cheaper"
END LEARN

Implementation:

• Extend existing llm/observability.rs
• Use existing model routing infrastructure
• Add cost/latency tracking

6. Plugin Marketplace (Priority: Low)

Current State

• MCP server support exists
• Manual configuration via mcp.csv
• No discovery mechanism

Proposed Enhancement: Plugin Discovery

New BASIC keywords:

' Discover available plugins
plugins = SEARCH PLUGINS FOR "calendar integration"

' Install plugin
INSTALL PLUGIN "google-calendar-mcp"
  WITH PERMISSIONS "read,write"
  WITH SCOPE "current-bot"

' Use plugin tools
USE TOOL "create-calendar-event" FROM PLUGIN "google-calendar-mcp"

Implementation:

• Extend existing MCP infrastructure
• Add plugin registry (PostgreSQL table)
• Security scanning before installation

---

Implementation Roadmap

Phase 1: Enhanced Orchestration (Months 1-2)

Goal: Improve multi-agent coordination using existing infrastructure

1. ORCHESTRATE WORKFLOW keyword

   • Add to basic/keywords/orchestration.rs
   • Use existing session management
   • Store workflow state in PostgreSQL

2. Event Bus in BASIC

   • Leverage existing Redis pub/sub
   • Add ON EVENT, PUBLISH EVENT keywords
   • Extend existing message handling

3. Agent Memory Enhancement

   • Extend REMEMBER keyword
   • Use existing VectorDB (Qdrant)
   • Add AGENT LEARN, AGENT RECALL keywords

Deliverables:

• 3 new BASIC keywords
• No new infrastructure
• Backward compatible

Phase 2: Visual Workflow Designer (Months 3-4)

Goal: Enhance existing designer with workflow canvas

1. Drag-and-Drop Canvas

   • Extend botserver/src/designer/
   • Generate BASIC code from visual design
   • Use existing HTMX architecture

2. Workflow Templates

   • Pre-built workflow patterns
   • Stored as .gbai packages
   • Shareable via existing package system

Deliverables:

• Visual workflow editor
• Generates BASIC code
• Uses existing designer infrastructure

Phase 3: Intelligence & Learning (Months 5-6)

Goal: Add agent learning and smart routing

1. LLM Router Enhancement

   • Extend llm/observability.rs
   • Add cost/latency tracking
   • Automatic model selection

2. Agent Knowledge Evolution

   • Pattern recognition from conversations
   • Cross-bot knowledge sharing
   • Stored in existing VectorDB

Deliverables:

• Smart LLM routing
• Agent learning system
• Uses existing infrastructure

Phase 4: Plugin Ecosystem (Months 7-8)

Goal: Enable plugin discovery and marketplace

1. Plugin Registry

   • PostgreSQL table for plugins
   • Security scanning
   • Version management

2. Discovery Keywords

   • SEARCH PLUGINS, INSTALL PLUGIN
   • Extend existing MCP support
   • No new runtime needed

Deliverables:

• Plugin marketplace
• Discovery system
• Extends existing MCP infrastructure

---

Technical Specifications

New BASIC Keywords (Extend Existing Interpreter)

// Add to botserver/src/basic/keywords/

// orchestration.rs
pub fn register_orchestrate_workflow(engine: &mut Engine) { }
pub fn register_on_event(engine: &mut Engine) { }
pub fn register_publish_event(engine: &mut Engine) { }

// agent_learning.rs  
pub fn register_agent_learn(engine: &mut Engine) { }
pub fn register_agent_recall(engine: &mut Engine) { }
pub fn register_agent_share(engine: &mut Engine) { }

// plugin_discovery.rs
pub fn register_search_plugins(engine: &mut Engine) { }
pub fn register_install_plugin(engine: &mut Engine) { }

Database Schema Extensions (PostgreSQL)

-- Workflow state (uses existing session management)
CREATE TABLE workflow_executions (
  id UUID PRIMARY KEY,
  bot_id UUID REFERENCES bots(id),
  workflow_definition TEXT,
  current_step INTEGER,
  state JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Agent learning (uses existing VectorDB for embeddings)
CREATE TABLE agent_knowledge (
  id UUID PRIMARY KEY,
  bot_id UUID REFERENCES bots(id),
  pattern TEXT,
  confidence FLOAT,
  learned_from UUID REFERENCES conversations(id),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Plugin registry (extends existing MCP support)
CREATE TABLE plugins (
  id UUID PRIMARY KEY,
  name TEXT UNIQUE,
  mcp_server_url TEXT,
  permissions TEXT[],
  security_scan_result JSONB,
  downloads INTEGER DEFAULT 0,
  rating FLOAT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Performance Targets (Realistic)

Metric	Current	Target	How
Multi-agent coordination	Manual	Automated	ORCHESTRATE keyword
Workflow complexity	Linear	Branching/parallel	Visual designer
Agent learning	None	Pattern recognition	VectorDB + LEARN keyword
Plugin discovery	Manual CSV	Searchable	Plugin registry
LLM routing	Static	Dynamic	Cost/latency tracking

Resource Requirements (No Change)

Development:

• Same as current (16+ cores, 32GB RAM)
• No new infrastructure

Production:

• Same LXC container model
• Existing PostgreSQL, Redis, Qdrant
• No additional services needed

---

Why NOT Microservices?

You already have LXC containers for isolation. The current architecture:

Host System
├── botserver (single binary)
├── LXC: default-tables (PostgreSQL)
├── LXC: default-drive (S3 storage)
├── LXC: default-cache (Redis)
├── LXC: default-vault (Secrets)
└── LXC: default-vectordb (Qdrant)

This gives you:

• ✅ Process isolation (LXC containers)
• ✅ Resource limits per service
• ✅ Independent service restarts
• ✅ Security boundaries
• ✅ Easy backup/restore (LXC snapshots)

Microservices would add:

• ❌ Network latency between services
• ❌ Complex service discovery
• ❌ Distributed tracing overhead
• ❌ More failure points
• ❌ Deployment complexity

Keep the single binary + LXC model. It's simpler and faster.

---

Why NOT Separate Workflow Engine?

You already have:

• BASIC interpreter (Rhai)
• Visual designer
• Session management
• State persistence

Just add keywords:

ORCHESTRATE WORKFLOW
  STEP 1: BOT "researcher" GATHERS data
  STEP 2: BOT "analyst" PROCESSES data
END WORKFLOW

This generates workflow state in PostgreSQL, executes via existing BASIC interpreter.

No separate workflow engine needed. BASIC IS the workflow engine.

---

Why NOT Plugin Marketplace Infrastructure?

You already have:

• MCP server support
• mcp.csv configuration
• Tool registration system

Just add:

• PostgreSQL table for plugin registry
• SEARCH PLUGINS keyword
• INSTALL PLUGIN keyword (writes to mcp.csv)

No separate marketplace service needed. It's just a searchable table + BASIC keywords.

---

Migration Strategy

There Is No Migration

Everything is additive:

1. Add new BASIC keywords to basic/keywords/
2. Add new database tables (migrations)
3. Extend existing designer UI
4. No breaking changes

Existing .gbai packages continue working.

Backward Compatibility

• Old BASIC scripts: ✅ Work unchanged
• Old .gbai packages: ✅ Deploy unchanged
• Old API endpoints: ✅ Function unchanged
• Old LXC containers: ✅ No changes needed

Version 7.0 = Version 6.1 + new keywords

---

Business Impact

Immediate Benefits (Phase 1-2, Months 1-4)

Enhanced Multi-Agent Coordination:

• Users can create complex workflows in BASIC
• No coding required for orchestration patterns
• Builds on familiar ADD BOT keyword

Visual Workflow Designer:

• Drag-and-drop workflow creation
• Generates BASIC code automatically
• Non-programmers can build AI workflows

ROI:

• 50% faster workflow creation
• 80% reduction in training time
• No new infrastructure costs

Long-term Benefits (Phase 3-4, Months 5-8)

Agent Learning:

• Bots improve from interactions
• Knowledge sharing between bots
• Reduced manual configuration

Plugin Ecosystem:

• Community-contributed integrations
• Faster feature delivery
• Revenue from marketplace (optional)

ROI:

• 10x more integrations via community
• 30% reduction in support costs
• Potential marketplace revenue

Cost Analysis

Development Cost: $200-300K over 8 months

• 2 senior Rust developers
• No new infrastructure
• Extends existing codebase

Infrastructure Cost: $0 additional

• Uses existing PostgreSQL, Redis, Qdrant
• Same LXC container model
• No new services

Revenue Impact: $1-2M additional ARR

• Faster enterprise adoption
• Plugin marketplace potential
• Reduced implementation time

Total ROI: 5-10x return in first year

---

Conclusion

The proposed improvements extend the existing architecture, not replace it:

1. Keep .gbai package system - It's brilliant
2. Keep LXC containers - Better than microservices
3. Keep BASIC scripting - Core differentiator
4. Keep single binary - Simpler deployment
5. Keep visual designer - Just enhance it

Add:

• New BASIC keywords for orchestration
• Agent learning capabilities
• Plugin discovery system
• Enhanced workflow visualization

Result: More powerful AI orchestration while maintaining simplicity.

Key Success Factors

1. BASIC-first design - Everything accessible via BASIC keywords
2. No breaking changes - Existing .gbai packages work unchanged
3. Extend, don't replace - Build on existing infrastructure
4. Keep it simple - Folder-based deployment stays
5. Community-driven - Plugin ecosystem enables innovation

This approach maintains General Bots' unique position: The only AI platform where non-programmers can create sophisticated multi-agent workflows by dropping folders and writing BASIC.