diff --git a/IMPLEMENTATION-PLAN.md b/IMPLEMENTATION-PLAN.md new file mode 100644 index 000000000..06f99178e --- /dev/null +++ b/IMPLEMENTATION-PLAN.md @@ -0,0 +1,1768 @@ +# General Bots Implementation Plan + +## Implementation Status + +### ✅ COMPLETED (Phase 1) + +| Feature | File | Status | +|---------|------|--------| +| SET USER MEMORY / GET USER MEMORY | `src/basic/keywords/user_memory.rs` | ✅ Created | +| USE MODEL / Model Routing | `src/basic/keywords/model_routing.rs` | ✅ Created | +| A2A Protocol (SEND TO BOT, BROADCAST, etc.) | `src/basic/keywords/a2a_protocol.rs` | ✅ Created | +| SSE Streaming Responses | `src/web/stream_handlers.rs` | ✅ Created | +| API Tool Auto-Generation (OpenAPI) | `src/basic/keywords/api_tool_generator.rs` | ✅ Created | +| Database Migration | `migrations/6.1.1_multi_agent_memory/` | ✅ Created | + +### ✅ COMPLETED (Phase 2) + +| Feature | File | Status | +|---------|------|--------| +| Hybrid RAG Search (BM25 + Dense) | `src/vector-db/hybrid_search.rs` | ✅ Created | +| Code Sandbox (RUN PYTHON/JS/BASH) | `src/basic/keywords/code_sandbox.rs` | ✅ Created | +| Agent Reflection (REFLECT ON) | `src/basic/keywords/agent_reflection.rs` | ✅ Created | + +### New BASIC Keywords Implemented + +```basic +' User Memory (cross-session persistence) +SET USER MEMORY "preferred_language", "Spanish" +lang = GET USER MEMORY("preferred_language") +REMEMBER USER FACT "User prefers morning meetings" +facts = GET USER FACTS() +CLEAR USER MEMORY + +' Model Routing +USE MODEL "quality" +SET MODEL ROUTING "auto" +model = GET CURRENT MODEL() +models = LIST MODELS() + +' A2A Protocol (Agent-to-Agent Communication) +SEND TO BOT "finance-bot" MESSAGE "Calculate Q4 revenue" +BROADCAST MESSAGE "User needs billing help" +COLLABORATE WITH "sales-bot", "support-bot" ON "quarterly report" +response = WAIT FOR BOT "finance-bot" TIMEOUT 30 +DELEGATE CONVERSATION TO "expert-bot" +messages = GET A2A MESSAGES() + +' Code Sandbox (Sandboxed execution) +result = RUN PYTHON "print('Hello from Python')" +result = RUN JAVASCRIPT "console.log('Hello from JS')" +result = RUN BASH "echo 'Hello from Bash'" +result = RUN PYTHON WITH FILE "analysis.py" + +' Agent Reflection (Self-improvement) +SET BOT REFLECTION true +REFLECT ON "conversation_quality" +REFLECT ON "performance" +insights = GET REFLECTION INSIGHTS() +``` + +### New config.csv Properties + +```csv +name,value +# Model Routing +llm-models,default;fast;quality;code +llm-model-fast,small-model.gguf +llm-model-quality,large-model.gguf +llm-model-code,codellama.gguf + +# A2A Protocol +a2a-enabled,true +a2a-timeout,30 +a2a-max-hops,5 +a2a-protocol-version,1.0 + +# API Tool Generation (auto-generates tools from OpenAPI specs) +myweather-api-server,https://api.weather.com/openapi.json +payment-api-server,https://api.stripe.com/v3/spec + +# Hybrid RAG Search +rag-hybrid-enabled,true +rag-dense-weight,0.7 +rag-sparse-weight,0.3 +rag-reranker-enabled,true +rag-reranker-model,cross-encoder/ms-marco-MiniLM-L-6-v2 + +# Code Sandbox +sandbox-enabled,true +sandbox-timeout,30 +sandbox-memory-limit,256 +sandbox-cpu-limit,50 +sandbox-network-enabled,false +sandbox-runtime,process + +# Agent Reflection +bot-reflection-enabled,true +bot-reflection-interval,10 +bot-reflection-prompt,Analyze conversation quality and suggest improvements +bot-improvement-auto-apply,false +``` + +--- + +## Executive Summary + +This document outlines the implementation plan for enhancing General Bots with multi-agent orchestration, advanced memory management, tool ecosystem modernization, and enterprise-grade features. The plan follows KISS (Keep It Simple, Stupid) and Pragmatismo principles, maintaining BASIC as the primary interface. + +--- + +## 1. MULTI-AGENT ORCHESTRATION + +### 1.1 ADD BOT Keyword Enhancement (Existing Foundation) + +**Current State:** `add_bot.rs` already implements: +- `ADD BOT "name" WITH TRIGGER "keywords"` +- `ADD BOT "name" WITH TOOLS "tool1, tool2"` +- `ADD BOT "name" WITH SCHEDULE "cron"` +- `REMOVE BOT`, `LIST BOTS`, `SET BOT PRIORITY`, `DELEGATE TO` + +**Enhancements Needed:** + +#### 1.1.1 Agent-to-Agent Communication (A2A Protocol) + +Reference: https://a2a-protocol.org/latest/ + +```rust +// New file: botserver/src/basic/keywords/a2a_protocol.rs + +pub struct A2AMessage { + pub from_agent: String, + pub to_agent: String, + pub message_type: A2AMessageType, + pub payload: serde_json::Value, + pub correlation_id: Uuid, + pub timestamp: DateTime, +} + +pub enum A2AMessageType { + Request, // Agent requesting action from another + Response, // Agent responding to request + Broadcast, // Message to all agents in session + Delegate, // Hand off conversation to another agent + Collaborate, // Request collaboration on task +} +``` + +**New BASIC Keywords:** + +```basic +' Send message to another bot +SEND TO BOT "finance-bot" MESSAGE "Calculate Q4 revenue" + +' Broadcast to all bots in session +BROADCAST MESSAGE "User needs help with billing" + +' Request collaboration +COLLABORATE WITH "sales-bot", "finance-bot" ON "quarterly report" + +' Wait for response from bot +response = WAIT FOR BOT "finance-bot" TIMEOUT 30 +``` + +**config.csv Properties:** + +```csv +name,value +a2a-enabled,true +a2a-timeout,30 +a2a-max-hops,5 +a2a-protocol-version,1.0 +``` + +### 1.2 Agent Memory Management (SET BOT MEMORY Enhancement) + +**Current State:** `bot_memory.rs` implements `SET BOT MEMORY` and `GET BOT MEMORY` for bot-level key-value storage. + +**Enhancements:** + +#### 1.2.1 Short-Term Memory (Session-Scoped) + +```basic +' Short-term memory (cleared after session) +SET SHORT MEMORY "current_topic", "billing inquiry" +topic = GET SHORT MEMORY "current_topic" +``` + +#### 1.2.2 Long-Term Memory (Persistent) + +```basic +' Long-term memory (persists across sessions) +SET LONG MEMORY "user_preferences", preferences_json +prefs = GET LONG MEMORY "user_preferences" + +' Memory with TTL +SET BOT MEMORY "cache_data", data TTL 3600 +``` + +**Database Schema Addition:** + +```sql +CREATE TABLE bot_memory_extended ( + id UUID PRIMARY KEY, + bot_id UUID NOT NULL, + session_id UUID, -- NULL for long-term + memory_type VARCHAR(20) NOT NULL, -- 'short', 'long', 'episodic' + key VARCHAR(255) NOT NULL, + value TEXT NOT NULL, + ttl_seconds INTEGER, + created_at TIMESTAMP NOT NULL, + updated_at TIMESTAMP NOT NULL, + expires_at TIMESTAMP, + UNIQUE(bot_id, session_id, key) +); +``` + +### 1.3 Parallel Agent Execution (Group Conversations) + +**Implementation:** + +```basic +' In start.bas - configure parallel bots +ADD BOT "sales-bot" WITH TRIGGER "pricing, deals, discount" +ADD BOT "support-bot" WITH TRIGGER "help, issue, problem" +ADD BOT "expert-bot" AS TOOL ' Available to be called by other bots + +' Enable parallel mode - both bots receive input +SET SESSION PARALLEL true + +' Configure response sequencing +SET SESSION RESPONSE_ORDER "priority" ' or "round-robin", "first" +``` + +**New File:** `botserver/src/basic/keywords/parallel_agents.rs` + +```rust +pub struct ParallelAgentConfig { + pub enabled: bool, + pub response_order: ResponseOrder, + pub max_concurrent: usize, + pub aggregation_strategy: AggregationStrategy, +} + +pub enum ResponseOrder { + Priority, // Highest priority bot responds first + RoundRobin, // Alternate between bots + First, // First to respond wins + All, // All responses concatenated +} + +pub enum AggregationStrategy { + Concat, // Concatenate all responses + Summary, // LLM summarizes responses + Vote, // Majority decision + Delegate, // Best response wins +} +``` + +### 1.4 Agent Reflection/Self-Improvement Loops + +**Approach:** Use existing LLM infrastructure for reflection. + +```basic +' In bot's start.bas - enable reflection +SET BOT REFLECTION true +SET BOT REFLECTION_INTERVAL 10 ' Every 10 interactions + +' Manual reflection trigger +REFLECT ON "conversation_quality" +``` + +**Implementation:** + +```rust +// New file: botserver/src/basic/keywords/agent_reflection.rs + +pub async fn perform_reflection( + state: &AppState, + bot_id: Uuid, + session_id: Uuid, + reflection_type: &str, +) -> Result { + // 1. Gather recent conversation history + let history = get_recent_history(state, session_id, 20).await?; + + // 2. Build reflection prompt + let prompt = format!( + "Analyze this conversation and suggest improvements:\n{}\n\ + Focus on: {}\n\ + Output JSON with: {{\"insights\": [], \"improvements\": [], \"score\": 0-10}}", + history, reflection_type + ); + + // 3. Call LLM for reflection + let reflection = call_llm(state, &prompt).await?; + + // 4. Store insights in bot memory + store_reflection(state, bot_id, &reflection).await?; + + Ok(reflection) +} +``` + +**config.csv Properties:** + +```csv +name,value +bot-reflection-enabled,true +bot-reflection-interval,10 +bot-reflection-prompt,Analyze conversation quality and suggest improvements +bot-improvement-auto-apply,false +``` + +--- + +## 2. TOOL ECOSYSTEM MODERNIZATION + +### 2.1 MCP Server Configuration + +**Current State:** MCP tool generation exists in `compiler/mod.rs`. + +**Enhancement:** Add `mcp-server` flag to config.csv. + +```csv +name,value +mcp-server,true +mcp-server-port,3000 +mcp-server-name,my-custom-tools +``` + +**Implementation:** + +```rust +// New file: botserver/src/basic/mcp_server.rs + +pub struct MCPServerConfig { + pub enabled: bool, + pub port: u16, + pub name: String, + pub tools: Vec, +} + +pub async fn start_mcp_server(config: MCPServerConfig) -> Result<(), Error> { + // Expose compiled .bas tools as MCP server + let app = Router::new() + .route("/tools/list", get(list_tools)) + .route("/tools/call", post(call_tool)); + + axum::serve(listener, app).await +} +``` + +### 2.2 Tool Chaining and Composition + +**Current State:** Tools are called individually via `USE TOOL`. + +**Enhancement:** Chain tools with PIPE syntax. + +```basic +' Tool chaining +result = PIPE "extract-data" -> "transform" -> "save" + +' Tool composition +DEFINE TOOL CHAIN "etl-pipeline" + STEP 1: "extract-from-api" + STEP 2: "transform-data" + STEP 3: "load-to-db" +END CHAIN + +' Use the chain +RUN CHAIN "etl-pipeline" WITH input_data +``` + +**Implementation in BASIC Compiler:** + +```rust +// In compiler/mod.rs - add chain parsing + +fn parse_tool_chain(&self, source: &str) -> Option { + // Parse DEFINE TOOL CHAIN ... END CHAIN blocks + // Store chain definition in database + // Generate composite tool JSON +} +``` + +### 2.3 Automatic Tool Discovery from OpenAPI/Swagger + +**config.csv Format:** + +```csv +name,value +myweather-api-server,https://api.weather.com/openapi.json +payment-api-server,https://api.stripe.com/v3/spec +crm-api-server,./specs/crm-openapi.yaml +``` + +**Implementation:** + +```rust +// New file: botserver/src/basic/keywords/api_tool_generator.rs + +pub struct ApiToolGenerator { + state: Arc, + bot_id: Uuid, +} + +impl ApiToolGenerator { + pub async fn generate_from_openapi(&self, name: &str, spec_url: &str) -> Result<(), Error> { + // 1. Fetch OpenAPI spec + let spec = fetch_openapi_spec(spec_url).await?; + + // 2. Parse endpoints + let endpoints = parse_openapi_endpoints(&spec)?; + + // 3. Generate .bas files for each endpoint + for endpoint in endpoints { + let bas_content = self.generate_bas_for_endpoint(&name, &endpoint)?; + let file_path = format!(".gbdialog/{}/{}.bas", name, endpoint.operation_id); + self.write_and_compile(&file_path, &bas_content).await?; + } + + Ok(()) + } + + fn generate_bas_for_endpoint(&self, api_name: &str, endpoint: &Endpoint) -> String { + let mut bas = String::new(); + + // Generate PARAM declarations from OpenAPI parameters + for param in &endpoint.parameters { + bas.push_str(&format!( + "PARAM {} AS {} LIKE \"{}\" DESCRIPTION \"{}\"\n", + param.name, + map_openapi_type(¶m.schema_type), + param.example.as_deref().unwrap_or(""), + param.description + )); + } + + bas.push_str(&format!("\nDESCRIPTION \"{}\"\n\n", endpoint.description)); + + // Generate HTTP call + bas.push_str(&format!( + "result = {} HTTP \"{}\" WITH {}\n", + endpoint.method.to_uppercase(), + endpoint.path, + self.build_params_object(&endpoint.parameters) + )); + + bas.push_str("RETURN result\n"); + + bas + } +} +``` + +**Sync Behavior:** +- On bot startup, scan config.csv for `*-api-server` entries +- Fetch specs and generate tools in `.gbdialog//` +- Update if spec changes (compare hashes) +- Delete generated tools if config line removed +- Store in `generated_api_tools` table with source URL + +--- + +## 3. MEMORY & CONTEXT MANAGEMENT + +### 3.1 RAG 2.0 with Hybrid Search + +**Current State:** `vector-db/vectordb_indexer.rs` implements Qdrant-based vector search. + +**Enhancement:** Add hybrid search combining sparse (BM25) and dense (embedding) retrieval. + +```rust +// Modify: botserver/src/vector-db/vectordb_indexer.rs + +pub struct HybridSearchConfig { + pub dense_weight: f32, // 0.0 - 1.0 + pub sparse_weight: f32, // 0.0 - 1.0 + pub reranker_enabled: bool, + pub reranker_model: String, +} + +pub async fn hybrid_search( + &self, + query: &str, + config: &HybridSearchConfig, +) -> Vec { + // 1. Dense search (existing Qdrant) + let dense_results = self.vector_search(query).await?; + + // 2. Sparse search (BM25) + let sparse_results = self.bm25_search(query).await?; + + // 3. Combine with Reciprocal Rank Fusion + let combined = reciprocal_rank_fusion( + &dense_results, + &sparse_results, + config.dense_weight, + config.sparse_weight + ); + + // 4. Optional reranking + if config.reranker_enabled { + return self.rerank(query, combined).await?; + } + + combined +} +``` + +**config.csv Properties:** + +```csv +name,value +rag-hybrid-enabled,true +rag-dense-weight,0.7 +rag-sparse-weight,0.3 +rag-reranker-enabled,true +rag-reranker-model,cross-encoder/ms-marco-MiniLM-L-6-v2 +``` + +### 3.2 Graph-Based Memory (Knowledge Graphs) + +**Why Needed:** Track relationships between entities, enable complex queries like "Who works with John on Project X?" + +**config.csv Properties:** + +```csv +name,value +knowledge-graph-enabled,true +knowledge-graph-backend,postgresql +knowledge-graph-extract-entities,true +``` + +**Implementation:** + +```sql +-- New tables for knowledge graph +CREATE TABLE kg_entities ( + id UUID PRIMARY KEY, + bot_id UUID NOT NULL, + entity_type VARCHAR(100) NOT NULL, + entity_name VARCHAR(500) NOT NULL, + properties JSONB, + created_at TIMESTAMP NOT NULL +); + +CREATE TABLE kg_relationships ( + id UUID PRIMARY KEY, + bot_id UUID NOT NULL, + from_entity_id UUID REFERENCES kg_entities(id), + to_entity_id UUID REFERENCES kg_entities(id), + relationship_type VARCHAR(100) NOT NULL, + properties JSONB, + created_at TIMESTAMP NOT NULL +); +``` + +**BASIC Keywords:** + +```basic +' Extract and store entities from text +EXTRACT ENTITIES FROM text INTO KNOWLEDGE GRAPH + +' Query knowledge graph +related = QUERY GRAPH "people who work on Project Alpha" + +' Manual entity creation +ADD ENTITY "John Smith" TYPE "person" WITH {"department": "Sales"} +ADD RELATIONSHIP "John Smith" -> "works_on" -> "Project Alpha" +``` + +### 3.3 Episodic Memory (Conversation Summaries) + +**Why Needed:** Compress long conversations into summaries for efficient context. + +**config.csv Properties:** + +```csv +name,value +episodic-memory-enabled,true +episodic-summary-threshold,20 +episodic-summary-model,llm-default +``` + +**Implementation:** + +```rust +// New file: botserver/src/basic/keywords/episodic_memory.rs + +pub async fn create_episode_summary( + state: &AppState, + session_id: Uuid, + message_count_threshold: usize, +) -> Result { + let messages = get_session_messages(state, session_id).await?; + + if messages.len() < message_count_threshold { + return Ok(String::new()); + } + + let prompt = format!( + "Summarize this conversation into key points:\n{}\n\ + Output: {{\"summary\": \"...\", \"key_topics\": [], \"decisions\": [], \"action_items\": []}}", + format_messages(&messages) + ); + + let summary = call_llm(state, &prompt).await?; + + // Store episode + store_episode(state, session_id, &summary).await?; + + // Optionally compact original messages + if should_compact { + compact_messages(state, session_id).await?; + } + + Ok(summary) +} +``` + +### 3.4 Cross-Session Memory (SET USER MEMORY) + +**New BASIC Keywords:** + +```basic +' Store user preference across all sessions +SET USER MEMORY "preferred_language", "Spanish" +SET USER MEMORY "timezone", "America/New_York" + +' Retrieve user memory +lang = GET USER MEMORY "preferred_language" + +' Store learned fact about user +REMEMBER USER FACT "User is allergic to peanuts" + +' Get all learned facts +facts = GET USER FACTS +``` + +**Implementation:** + +```rust +// New file: botserver/src/basic/keywords/user_memory.rs + +pub fn set_user_memory_keyword(state: Arc, user: UserSession, engine: &mut Engine) { + engine.register_custom_syntax( + &["SET", "USER", "MEMORY", "$expr$", ",", "$expr$"], + false, + move |context, inputs| { + let key = context.eval_expression_tree(&inputs[0])?.to_string(); + let value = context.eval_expression_tree(&inputs[1])?.to_string(); + + // Store in user_memories table (not bot_memories) + tokio::spawn(async move { + diesel::insert_into(user_memories::table) + .values(( + user_memories::user_id.eq(user.user_id), + user_memories::key.eq(&key), + user_memories::value.eq(&value), + )) + .on_conflict((user_memories::user_id, user_memories::key)) + .do_update() + .set(user_memories::value.eq(&value)) + .execute(&mut conn); + }); + + Ok(Dynamic::UNIT) + }, + ); +} +``` + +--- + +## 4. ADVANCED LLM INTEGRATION + +### 4.1 Model Routing (USE MODEL Keyword) + +**config.csv - Multiple Models:** + +```csv +name,value +llm-model,default-model.gguf +llm-model-fast,small-model.gguf +llm-model-quality,large-model.gguf +llm-model-code,codellama.gguf +llm-models,default;fast;quality;code +``` + +**BASIC Keyword:** + +```basic +' Switch model for current conversation +USE MODEL "quality" + +' Use specific model for single call +answer = LLM "Complex reasoning task" WITH MODEL "quality" + +' Auto-routing based on query complexity +SET MODEL ROUTING "auto" +``` + +**Implementation:** + +```rust +// New file: botserver/src/basic/keywords/model_routing.rs + +pub struct ModelRouter { + models: HashMap, + default_model: String, + routing_strategy: RoutingStrategy, +} + +pub enum RoutingStrategy { + Manual, // User specifies model + Auto, // Route based on query analysis + LoadBalanced, // Distribute across models + Fallback, // Try models in order until success +} + +impl ModelRouter { + pub async fn route_query(&self, query: &str) -> &ModelConfig { + match self.routing_strategy { + RoutingStrategy::Auto => { + // Analyze query complexity + let complexity = analyze_query_complexity(query); + if complexity > 0.8 { + self.models.get("quality").unwrap_or(&self.default) + } else if query.contains("code") || query.contains("programming") { + self.models.get("code").unwrap_or(&self.default) + } else { + self.models.get("fast").unwrap_or(&self.default) + } + } + _ => &self.default + } + } +} +``` + +### 4.2 Streaming Responses with SSE + +**Implementation:** + +```rust +// Modify: botserver/src/web/chat_handlers.rs + +use axum::response::sse::{Event, Sse}; +use futures::stream::Stream; + +pub async fn stream_chat_response( + State(state): State, + Json(payload): Json, +) -> Sse>> { + let stream = async_stream::stream! { + let (tx, mut rx) = mpsc::channel(100); + + // Start LLM generation with streaming + tokio::spawn(async move { + let provider = OpenAIClient::new(api_key, Some(url)); + provider.generate_stream(&prompt, &messages, tx, &model, &key).await; + }); + + // Yield SSE events as tokens arrive + while let Some(token) = rx.recv().await { + yield Ok(Event::default().data(token)); + } + + yield Ok(Event::default().event("done").data("")); + }; + + Sse::new(stream) +} + +// Add route +.route("/api/chat/stream", post(stream_chat_response)) +``` + +**Frontend Integration:** + +```typescript +// gbclient/app/chat/page.tsx +const eventSource = new EventSource('/api/chat/stream'); +eventSource.onmessage = (event) => { + appendToken(event.data); +}; +eventSource.addEventListener('done', () => { + eventSource.close(); +}); +``` + +### 4.3 Mixture of Experts (MoE) Configuration + +**config.csv:** + +```csv +name,value +moe-enabled,true +moe-list,sales-bot;support-bot;technical-bot +moe-strategy,consensus +moe-min-agreement,2 +``` + +**Implementation:** + +```basic +' Auto-mode: system chooses best bot(s) +SET MOE MODE "auto" + +' Consensus mode: multiple bots must agree +SET MOE MODE "consensus" MIN_AGREEMENT 2 + +' Specialist mode: route to best expert +SET MOE MODE "specialist" +``` + +--- + +## 5. CODE INTERPRETER & EXECUTION + +### 5.1 Sandboxed Execution with LXC + +**New Keyword: RUN** + +```basic +' Run Python code in sandbox +result = RUN PYTHON " +import pandas as pd +df = pd.read_csv('data.csv') +print(df.describe()) +" + +' Run JavaScript +result = RUN JAVASCRIPT " +const sum = [1,2,3].reduce((a,b) => a+b, 0); +return sum; +" + +' Run with file context +result = RUN PYTHON WITH FILE "analysis.py" +``` + +**Implementation:** + +```rust +// New file: botserver/src/basic/keywords/code_sandbox.rs + +pub struct SandboxConfig { + pub runtime: SandboxRuntime, + pub timeout_seconds: u64, + pub memory_limit_mb: u64, + pub cpu_limit_percent: u32, + pub network_enabled: bool, +} + +pub enum SandboxRuntime { + LXC, + Docker, + Firecracker, + Process, // Direct process isolation (fallback) +} + +pub async fn execute_in_sandbox( + code: &str, + language: &str, + config: &SandboxConfig, +) -> Result { + // 1. Create LXC container with pre-installed packages + let container = create_lxc_container(language, config).await?; + + // 2. Write code to container + write_code_to_container(&container, code).await?; + + // 3. Execute with timeout + let result = tokio::time::timeout( + Duration::from_secs(config.timeout_seconds), + container.execute() + ).await??; + + // 4. Cleanup + container.destroy().await?; + + Ok(result) +} +``` + +**LXC Container Templates:** + +```bash +# Pre-built containers with common packages +lxc-python-data: + - pandas + - numpy + - matplotlib + - scikit-learn + +lxc-python-web: + - requests + - beautifulsoup4 + - selenium + +lxc-node: + - axios + - lodash + - cheerio +``` + +### 5.2 Code Generation (dev-mode Internal Tool) + +**config.csv:** + +```csv +name,value +dev-mode,true +dev-tool-enabled,true +``` + +**Internal Tool Behavior:** + +```basic +' User says: "Create a tool for customer enrollment with name, email, phone" +' System generates enrollment.bas: + +PARAM name AS string LIKE "John Doe" DESCRIPTION "Customer full name" +PARAM email AS string LIKE "john@example.com" DESCRIPTION "Customer email address" +PARAM phone AS string LIKE "+1-555-0100" DESCRIPTION "Customer phone number" + +DESCRIPTION "Enrolls a new customer in the system" + +' Validate inputs +IF ISEMPTY(name) THEN + TALK "Name is required" + RETURN +END IF + +' Save to database +SAVE "customers.csv", name, email, phone, NOW() + +TALK "Successfully enrolled " + name +``` + +**Implementation Flow:** + +1. User requests tool creation in chat +2. LLM analyzes request, generates .bas code +3. Compiler validates and compiles +4. Tool becomes immediately available +5. User notified of completion + +### 5.3 Language Server for Debugging + +**Architecture:** + +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ +│ VS Code │────▶│ Language Server │────▶│ BotServer │ +│ Extension │◀────│ (Rhai/BASIC) │◀────│ Debug Runtime │ +└─────────────────┘ └──────────────────┘ └─────────────────┘ +``` + +**Features:** +- Syntax highlighting for .bas files +- IntelliSense/autocomplete for keywords +- Breakpoint support +- Variable inspection +- Step through execution + +**Suite Code Editor:** + +```typescript +// gbclient/app/editor/code-editor.tsx +// Monaco editor with BASIC language support + +const monacoConfig = { + language: 'basic', + theme: 'gb-dark', + features: { + debugging: true, + breakpoints: true, + variableHover: true, + } +}; +``` + +### 5.4 Data Analysis Keywords + +```basic +' Create DataFrame from CSV +df = DATAFRAME FROM "sales.csv" + +' Filter and aggregate +filtered = FILTER df WHERE "region = 'North'" +summary = AGGREGATE filtered BY "product" SUM "revenue" + +' Generate chart +chart = CHART BAR summary X "product" Y "revenue" +SHOW chart + +' Statistical analysis +stats = DESCRIBE df +correlation = CORRELATE df "price", "quantity" +``` + +--- + +## 6. RETRIEVAL AUGMENTATION + +### 6.1 Web Search Integration + +**Already Implemented:** Check suite/chat for web search button. + +**Enhancement:** Add BASIC keyword. + +```basic +' Search the web +results = WEB SEARCH "latest AI news" + +' Search and summarize +summary = WEB SEARCH "climate change 2025" SUMMARIZE true + +' Fact check against web +verified = FACT CHECK statement +``` + +### 6.2 Document Parsing Enhancement + +**config.csv:** + +```csv +name,value +document-ocr-enabled,true +document-table-extraction,true +document-chart-extraction,true +document-parser,advanced +``` + +**Implementation:** + +```rust +// Enhanced document parsing with table/chart extraction +pub async fn parse_document( + path: &str, + config: &DocumentParserConfig, +) -> DocumentContent { + match config.parser { + ParserType::Advanced => { + // Use vision model for complex documents + let image = render_document_page(path)?; + let analysis = vision_service.describe_image(image).await?; + + DocumentContent { + text: analysis.text, + tables: extract_tables(&analysis), + charts: extract_charts(&analysis), + metadata: analysis.metadata, + } + } + ParserType::Basic => { + // Standard text extraction + extract_text_basic(path) + } + } +} +``` + +### 6.3 Query Decomposition + +**Implementation:** Pre-process complex queries before LLM. + +```rust +// In llm/mod.rs + +pub async fn decompose_query(query: &str) -> Vec { + let decomposition_prompt = format!( + "Break down this complex question into simpler sub-questions:\n\ + Question: {}\n\ + Output JSON: {{\"sub_questions\": [\"q1\", \"q2\", ...]}}", + query + ); + + let result = call_llm(&decomposition_prompt).await?; + parse_sub_questions(&result) +} + +// Usage in RAG pipeline +pub async fn answer_complex_query(query: &str) -> String { + let sub_queries = decompose_query(query).await?; + + let mut answers = Vec::new(); + for sub_query in sub_queries { + let context = retrieve_context(&sub_query).await?; + let answer = generate_answer(&sub_query, &context).await?; + answers.push(answer); + } + + // Synthesize final answer + synthesize_answers(query, &answers).await +} +``` + +**config.csv:** + +```csv +name,value +query-decomposition-enabled,true +query-decomposition-threshold,50 +``` + +--- + +## 7. WORKFLOW & ORCHESTRATION + +### 7.1 BASIC-First Workflow Engine + +**Current State:** BASIC already supports `IF`, `FOR`, `WHILE`, `SUB`, `FUNCTION`. + +**Enhancement:** Add workflow-specific constructs. + +```basic +' Define workflow +WORKFLOW "order-processing" + STEP "validate" CALL validate_order + STEP "payment" CALL process_payment DEPENDS ON "validate" + STEP "fulfill" CALL fulfill_order DEPENDS ON "payment" + STEP "notify" CALL notify_customer DEPENDS ON "fulfill" + + ON ERROR GOTO error_handler +END WORKFLOW + +' Run workflow +RUN WORKFLOW "order-processing" WITH order_data + +' Conditional branching (existing IF enhanced) +STEP "review" IF order_total > 1000 THEN + CALL manual_review +ELSE + CALL auto_approve +END IF +``` + +### 7.2 Human-in-the-Loop Approvals + +**New Keyword: HEAR ON** + +```basic +' Wait for approval via mobile/email/teams +HEAR approval ON mobile_number "+1-555-0100" +HEAR approval ON email "manager@company.com" +HEAR approval ON teams "manager-channel" + +' With timeout and fallback +HEAR approval ON email "manager@company.com" TIMEOUT 3600 DEFAULT "auto-approve" +``` + +**Implementation:** + +```rust +// New file: botserver/src/basic/keywords/human_approval.rs + +pub async fn wait_for_approval( + channel: ApprovalChannel, + timeout_seconds: u64, + default_action: Option, +) -> Result { + // 1. Send approval request + send_approval_request(&channel).await?; + + // 2. Wait for response with timeout + let response = tokio::time::timeout( + Duration::from_secs(timeout_seconds), + listen_for_response(&channel) + ).await; + + match response { + Ok(Ok(answer)) => Ok(answer), + _ => Ok(default_action.unwrap_or_default()) + } +} +``` + +### 7.3 Workflow Templates + +Store in `.gbai/templates/workflows/`: + +``` +workflows/ + ├── approval-flow.bas + ├── etl-pipeline.bas + ├── customer-onboarding.bas + ├── support-escalation.bas + └── order-processing.bas +``` + +--- + +## 8. COLLABORATION FEATURES + +### 8.1 Multi-User Conversations (Groups) + +**Current State:** Group selector exists in chat window. + +**Enhancement:** Full implementation. + +```typescript +// gbclient/app/chat/page.tsx - Enhanced group support + +interface ChatGroup { + id: string; + name: string; + members: User[]; + activeBot: string; + sharedContext: boolean; +} + +// Group message handling +const handleGroupMessage = async (message: Message, group: ChatGroup) => { + // Broadcast to all group members + group.members.forEach(member => { + sendToMember(member.id, message); + }); + + // Process with shared context if enabled + if (group.sharedContext) { + await processBotResponse(message, group); + } +}; +``` + +### 8.2 Activity Feeds (Delve-like App) + +**New App:** `gbclient/app/delve/` + +```typescript +// gbclient/app/delve/page.tsx + +interface Activity { + id: string; + userId: string; + userName: string; + action: 'message' | 'file_upload' | 'tool_use' | 'bot_interaction'; + timestamp: Date; + details: any; +} + +const DelvePage = () => { + const [activities, setActivities] = useState([]); + + return ( +
+

Activity Feed

+ {activities.map(activity => ( + + ))} +
+ ); +}; +``` + +--- + +## 9. OBSERVABILITY & DEBUGGING + +### 9.1 LLM Observability Dashboard + +**Location:** Suite Monitor app enhancement. + +**Metrics to Track:** +- Token usage per conversation +- Response latency +- Cache hit rate +- Model selection distribution +- Error rates +- Cost estimation + +```rust +// New file: botserver/src/llm/observability.rs + +pub struct LLMMetrics { + pub request_count: Counter, + pub token_count: Counter, + pub latency_histogram: Histogram, + pub cache_hits: Counter, + pub cache_misses: Counter, + pub errors: Counter, +} + +impl LLMMetrics { + pub fn record_request(&self, tokens: u64, latency_ms: u64, cached: bool) { + self.request_count.inc(); + self.token_count.inc_by(tokens); + self.latency_histogram.observe(latency_ms as f64); + if cached { + self.cache_hits.inc(); + } else { + self.cache_misses.inc(); + } + } +} +``` + +### 9.2 Trace Visualization + +**Live Trace Panel in Monitor:** + +```typescript +// gbclient/app/monitor/trace-panel.tsx + +interface TraceEvent { + timestamp: Date; + component: string; + action: string; + duration_ms: number; + metadata: any; +} + +const TracePanelLive = () => { + // WebSocket connection for live traces + const [traces, setTraces] = useState([]); + + useEffect(() => { + const ws = new WebSocket('/api/traces/live'); + ws.onmessage = (event) => { + setTraces(prev => [...prev, JSON.parse(event.data)].slice(-100)); + }; + return () => ws.close(); + }, []); + + return ( +
+ {traces.map((trace, i) => ( + + ))} +
+ ); +}; +``` + +### 9.3 Cost Tracking + +**Already in Monitor.** Enhancement: + +```sql +-- Cost tracking table +CREATE TABLE conversation_costs ( + id UUID PRIMARY KEY, + session_id UUID NOT NULL, + user_id UUID NOT NULL, + bot_id UUID NOT NULL, + model_used VARCHAR(100), + input_tokens INTEGER, + output_tokens INTEGER, + cost_usd DECIMAL(10, 6), + timestamp TIMESTAMP NOT NULL +); +``` + +### 9.4 Prompt Playground + +**Location:** Paper app enhancement. + +```typescript +// gbclient/app/paper/playground.tsx + +const PromptPlayground = () => { + const [systemPrompt, setSystemPrompt] = useState(''); + const [userPrompt, setUserPrompt] = useState(''); + const [model, setModel] = useState('default'); + const [response, setResponse] = useState(''); + + const testPrompt = async () => { + const result = await fetch('/api/playground/test', { + method: 'POST', + body: JSON.stringify({ systemPrompt, userPrompt, model }) + }); + setResponse(await result.text()); + }; + + return ( +
+