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:**

```basic
' 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:**

```rust
// 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
```basic
' 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:**

```basic
' 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:**

```basic
' 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:**

```basic
' 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:**

```basic
' 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)

```rust
// 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)

```sql
-- 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:**
```basic
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.**