refactor: remove deprecated documentation, configuration, and utility scripts

This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2026-04-29 07:18:36 -03:00
parent c445aa6de7
commit 47cdb2bf78
8 changed files with 0 additions and 628 deletions

View file

@ -1,5 +0,0 @@
[build]
jobs = 8
[target.x86_64-unknown-linux-gnu]
linker = "clang"

View file

@ -1,57 +0,0 @@
# Multi-Agent Workflows Guide
## Creating Workflows
### Basic Workflow Structure
```basic
ORCHESTRATE WORKFLOW "workflow-name"
STEP 1: BOT "analyzer" "process input"
STEP 2: BOT "validator" "check results"
END WORKFLOW
```
### Human Approval Integration
```basic
STEP 3: HUMAN APPROVAL FROM "manager@company.com"
TIMEOUT 1800 ' 30 minutes
ON TIMEOUT: ESCALATE TO "director@company.com"
```
### Parallel Processing
```basic
STEP 4: PARALLEL
BRANCH A: BOT "processor-1" "handle batch-a"
BRANCH B: BOT "processor-2" "handle batch-b"
END PARALLEL
```
### Event-Driven Coordination
```basic
ON EVENT "data-ready" DO
CONTINUE WORKFLOW AT STEP 5
END ON
PUBLISH EVENT "processing-complete"
```
### Cross-Bot Memory Sharing
```basic
BOT SHARE MEMORY "successful-patterns" WITH "learning-bot"
BOT SYNC MEMORY FROM "master-knowledge-bot"
```
## Best Practices
1. **Keep workflows focused** - Max 10 steps per workflow
2. **Use meaningful names** - Clear bot and step names
3. **Add timeouts** - Always set timeouts for human approvals
4. **Share knowledge** - Use memory sharing for bot learning
5. **Handle events** - Use event system for loose coupling
## Workflow Persistence
Workflows automatically survive server restarts. State is stored in PostgreSQL and recovered on startup.
## Visual Designer
Use the drag-and-drop designer at `/designer/workflow` to create workflows visually. The designer generates BASIC code automatically.

View file

@ -1,308 +0,0 @@
# Tools vs Bots: When to Use Each
**Chapter 4: Understanding the Difference Between Function Calls and AI Agents**
---
## Overview
General Bots provides two ways to extend your bot's capabilities:
- **TOOLs** - Simple functions with input/output
- **BOTs** - Intelligent AI agents that can reason and remember
Understanding when to use each is crucial for building efficient, cost-effective automation.
## Quick Comparison
| Feature | TOOL | BOT |
|---------|------|-----|
| **Purpose** | Data operations | Decision making |
| **Intelligence** | None (function) | Full LLM reasoning |
| **Speed** | Fast (10-100ms) | Slower (1-5 seconds) |
| **Cost** | Free | LLM tokens ($0.001-0.01) |
| **Input** | Structured data | Natural language |
| **Output** | Structured data | Conversational response |
| **Memory** | Stateless | Remembers context |
## Tools: The Function Approach
### What Are Tools?
Tools are **stateless functions** that perform specific operations:
```basic
' Tool usage - direct function call
USE TOOL "check-order"
result = CALL TOOL "check-order" WITH order_id="12345"
' Returns: {"status": "delivered", "amount": 899}
```
### When to Use Tools
✅ **Perfect for:**
- Database queries
- API calls
- Calculations
- Data transformations
- Real-time operations
```basic
' Examples of good tool usage
USE TOOL "get-weather"
weather = CALL TOOL "get-weather" WITH city="São Paulo"
USE TOOL "calculate-tax"
tax = CALL TOOL "calculate-tax" WITH amount=100, region="BR"
USE TOOL "send-email"
CALL TOOL "send-email" WITH to="user@example.com", subject="Order Confirmed"
```
### Tool Limitations
❌ **Cannot:**
- Make decisions
- Understand context
- Remember previous calls
- Handle ambiguous input
- Provide explanations
## Bots: The AI Agent Approach
### What Are Bots?
Bots are **intelligent agents** that can reason, remember, and make decisions:
```basic
' Bot usage - conversational interaction
ADD BOT "order-specialist"
response = ASK BOT "order-specialist" ABOUT "Customer says order 12345 arrived damaged. What should we do?"
' Returns: Detailed analysis with reasoning and recommendation
```
### When to Use Bots
✅ **Perfect for:**
- Complex decision making
- Natural language understanding
- Multi-step reasoning
- Context-aware responses
- Customer service scenarios
```basic
' Examples of good bot usage
ADD BOT "financial-advisor"
advice = ASK BOT "financial-advisor" ABOUT "Customer wants refund after 60 days but threatens legal action"
ADD BOT "technical-support"
solution = ASK BOT "technical-support" ABOUT "User can't login, tried password reset twice"
ADD BOT "content-moderator"
decision = ASK BOT "content-moderator" ABOUT "Review this user comment for policy violations"
```
### Bot Capabilities
✅ **Can:**
- Analyze complex situations
- Remember conversation history
- Use multiple tools internally
- Provide detailed explanations
- Handle edge cases
## Real-World Example: Order Processing
### Scenario
Customer contacts support: *"My laptop order #12345 arrived broken. I need this fixed immediately as I have a presentation tomorrow."*
### Tool-Only Approach (Limited)
```basic
' Simple but inflexible
USE TOOL "check-order"
order = CALL TOOL "check-order" WITH order_id="12345"
USE TOOL "check-warranty"
warranty = CALL TOOL "check-warranty" WITH order_id="12345"
IF order.status = "delivered" AND warranty.valid = true THEN
TALK "You're eligible for replacement"
ELSE
TALK "Please contact manager"
END IF
```
**Problems:**
- No understanding of urgency ("presentation tomorrow")
- No consideration of customer history
- Rigid, rule-based responses
- Cannot handle edge cases
### Bot Approach (Intelligent)
```basic
' Intelligent and flexible
ADD BOT "support-specialist"
response = ASK BOT "support-specialist" ABOUT "Customer says laptop order #12345 arrived broken. They have presentation tomorrow and need immediate help."
```
**Bot's internal reasoning:**
1. Uses `check-order` tool → Order delivered 2 days ago, $1,299 laptop
2. Uses `check-warranty` tool → Premium warranty valid
3. Uses `customer-history` tool → VIP customer, 8 previous orders
4. **Analyzes urgency** → Presentation tomorrow = time-sensitive
5. **Considers options** → Replacement (2-day shipping) vs immediate refund for local purchase
6. **Makes recommendation** → "Given urgency and VIP status, authorize immediate refund so customer can buy locally, plus expedited replacement as backup"
## Hybrid Approach: Best of Both Worlds
**Recommended pattern: Bots use Tools internally**
```basic
' support-specialist.bas - Bot implementation
USE TOOL "check-order"
USE TOOL "check-warranty"
USE TOOL "customer-history"
USE TOOL "inventory-check"
USE KB "support-policies"
WHEN ASKED ABOUT order_issue DO
' Gather data using tools (fast, cheap)
order = CALL TOOL "check-order" WITH order_id
warranty = CALL TOOL "check-warranty" WITH order_id
customer = CALL TOOL "customer-history" WITH customer_id
' Apply AI reasoning (intelligent, contextual)
urgency = ANALYZE urgency FROM user_message
customer_value = CALCULATE value FROM customer.total_orders
IF urgency = "high" AND customer_value = "vip" THEN
recommendation = "Expedited resolution with manager approval"
ELSE IF warranty.type = "premium" THEN
recommendation = "Standard replacement process"
ELSE
recommendation = "Store credit or repair option"
END IF
RETURN detailed_response WITH reasoning AND next_steps
END WHEN
```
## Performance Guidelines
### Tool Performance
- **Latency:** 10-100ms
- **Cost:** $0 (no LLM calls)
- **Throughput:** 1000+ operations/second
- **Use for:** High-frequency, simple operations
### Bot Performance
- **Latency:** 1-5 seconds
- **Cost:** $0.001-0.01 per interaction
- **Throughput:** 10-100 interactions/second
- **Use for:** Complex, high-value decisions
## Decision Framework
### Use TOOL when:
1. **Operation is deterministic** - Same input always produces same output
2. **Speed is critical** - Real-time responses needed
3. **Cost matters** - High-frequency operations
4. **Data is structured** - Clear input/output format
### Use BOT when:
1. **Context matters** - Previous conversation affects response
2. **Reasoning required** - Multiple factors to consider
3. **Natural language input** - Ambiguous or conversational requests
4. **Edge cases exist** - Situations requiring judgment
### Use HYBRID when:
1. **Complex workflows** - Multiple steps with decision points
2. **Data + Intelligence** - Need both fast data access and smart reasoning
3. **Scalability important** - Balance cost and capability
## Common Patterns
### Pattern 1: Data Retrieval
```basic
' TOOL: Simple lookup
price = CALL TOOL "get-price" WITH product_id="laptop-123"
' BOT: Contextual pricing
ADD BOT "pricing-advisor"
quote = ASK BOT "pricing-advisor" ABOUT "Customer wants bulk discount for 50 laptops, they're a returning enterprise client"
```
### Pattern 2: Validation
```basic
' TOOL: Rule-based validation
valid = CALL TOOL "validate-email" WITH email="user@domain.com"
' BOT: Contextual validation
ADD BOT "content-reviewer"
assessment = ASK BOT "content-reviewer" ABOUT "Is this product review appropriate for our family-friendly site?"
```
### Pattern 3: Workflow Orchestration
```basic
' Hybrid: Bot coordinates, tools execute
ORCHESTRATE WORKFLOW "order-processing"
STEP 1: CALL TOOL "validate-payment" WITH payment_info
STEP 2: BOT "fraud-detector" ANALYZES transaction_pattern
STEP 3: CALL TOOL "reserve-inventory" WITH product_id
STEP 4: BOT "shipping-optimizer" SELECTS best_carrier
STEP 5: CALL TOOL "send-confirmation" WITH order_details
END WORKFLOW
```
## Best Practices
### 1. Start Simple, Add Intelligence
```basic
' Phase 1: Tool-based (fast to implement)
result = CALL TOOL "process-refund" WITH order_id, amount
' Phase 2: Add bot intelligence (when complexity grows)
ADD BOT "refund-specialist"
decision = ASK BOT "refund-specialist" ABOUT "Customer wants refund but policy expired, they're threatening bad review"
```
### 2. Cache Bot Responses
```basic
' Expensive bot call
ADD BOT "product-recommender"
recommendations = ASK BOT "product-recommender" ABOUT "Best laptop for gaming under $1000"
' Cache result for similar queries
REMEMBER "gaming-laptop-under-1000" AS recommendations
```
### 3. Fallback Patterns
```basic
' Try bot first, fallback to tool
TRY
response = ASK BOT "smart-assistant" ABOUT user_query
CATCH bot_error
' Fallback to simple tool
response = CALL TOOL "keyword-search" WITH query=user_query
END TRY
```
## Summary
**Tools** are your **workhorses** - fast, reliable, cost-effective for data operations.
**Bots** are your **brain trust** - intelligent, contextual, perfect for complex decisions.
**Hybrid approach** gives you the best of both: use tools for speed and bots for intelligence.
Choose based on your specific needs:
- Need speed? → Tool
- Need intelligence? → Bot
- Need both? → Bot that uses tools
The key is understanding that **tools and bots complement each other** - they're not competing solutions, but different tools for different jobs in your AI automation toolkit.
---
**Next:** [Chapter 5: Building Multi-Agent Workflows](workflows.md)

View file

@ -1,74 +0,0 @@
# BASIC Language Reference - Version 6.2.0
## New Workflow Orchestration Keywords
### ORCHESTRATE WORKFLOW
Creates multi-step workflows with bot coordination.
**Syntax:**
```basic
ORCHESTRATE WORKFLOW "workflow-name"
STEP 1: BOT "bot-name" "action"
STEP 2: HUMAN APPROVAL FROM "email@domain.com" TIMEOUT 1800
STEP 3: PARALLEL
BRANCH A: BOT "bot-a" "process"
BRANCH B: BOT "bot-b" "process"
END PARALLEL
END WORKFLOW
```
**Features:**
- Workflow state persists through server restarts
- Variables automatically passed between steps
- Human approval integration with timeouts
- Parallel processing support
### Event System
**ON EVENT**
```basic
ON EVENT "event-name" DO
TALK "Event received"
END ON
```
**PUBLISH EVENT**
```basic
PUBLISH EVENT "event-name"
```
**WAIT FOR EVENT**
```basic
WAIT FOR EVENT "approval-received" TIMEOUT 3600
```
### Enhanced Memory
**BOT SHARE MEMORY**
```basic
BOT SHARE MEMORY "key" WITH "target-bot"
```
**BOT SYNC MEMORY**
```basic
BOT SYNC MEMORY FROM "source-bot"
```
### Enhanced LLM (Feature-gated)
**Optimized LLM Calls**
```basic
result = LLM "Analyze data" WITH OPTIMIZE FOR "speed"
result = LLM "Complex task" WITH MAX_COST 0.05 MAX_LATENCY 2000
```
## File Type Detection
The designer automatically detects:
- **Tools**: Simple input/output functions
- **Workflows**: Multi-step orchestration
- **Regular Bots**: Conversational interfaces
## Backward Compatibility
All existing BASIC keywords continue to work unchanged. New keywords extend functionality without breaking existing `.gbai` packages.

View file

@ -1,181 +0,0 @@
#!/bin/bash
#
# Migrate LXD containers from ZFS to Incus directory storage
# Usage: ./migrate_zfs_to_incus_dir.sh [options]
#
# Options:
# --dry-run Show what would be done without executing
# --source-pool NAME LXD storage pool name (default: default)
# --dest-pool NAME Incus storage pool name (default: default)
# --containers LIST Comma-separated list of containers (default: all)
# --incus-host HOST Remote Incus host (optional)
# --help Show this help
set -e
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
# Defaults
DRY_RUN=false
SOURCE_POOL="default"
DEST_POOL="default"
CONTAINERS=""
INCUS_HOST=""
BACKUP_DIR="/tmp/lxd-backups"
# Print banner
print_banner() {
echo -e "${BLUE}"
echo "╔════════════════════════════════════════════════════════════╗"
echo "║ LXD to Incus Migration Tool (ZFS -> Directory Storage) ║"
echo "╚════════════════════════════════════════════════════════════╝"
echo -e "${NC}"
}
# Show help
show_help() {
echo "Usage: $0 [options]"
echo ""
echo "Migrate LXD containers from ZFS storage to Incus directory storage."
echo ""
echo "Options:"
echo " --dry-run Show what would be done without executing"
echo " --source-pool NAME LXD storage pool name (default: default)"
echo " --dest-pool NAME Incus storage pool name (default: default)"
echo " --containers LIST Comma-separated list of containers (default: all)"
echo " --incus-host HOST Remote Incus host (ssh)"
echo " --help Show this help"
echo ""
echo "Examples:"
echo " $0 --dry-run"
echo " $0 --source-pool zfs-storage --dest-pool dir-storage"
echo " $0 --containers container1,container2 --incus-host user@remote-host"
}
# Check dependencies
check_dependencies() {
local missing=()
if ! command -v lxc &> /dev/null; then
missing+=("lxc")
fi
if ! command -v incus &> /dev/null; then
missing+=("incus")
fi
if [ ${#missing[@]} -gt 0 ]; then
echo -e "${RED}Missing dependencies: ${missing[*]}${NC}"
echo "Please install them and try again."
exit 1
fi
}
# Parse arguments
while [[ $# -gt 0 ]]; do
case $1 in
--dry-run)
DRY_RUN=true
shift
;;
--source-pool)
SOURCE_POOL="$2"
shift 2
;;
--dest-pool)
DEST_POOL="$2"
shift 2
;;
--containers)
CONTAINERS="$2"
shift 2
;;
--incus-host)
INCUS_HOST="$2"
shift 2
;;
-h|--help)
show_help
exit 0
;;
*)
echo -e "${RED}Unknown option: $1${NC}"
show_help
exit 1
;;
esac
done
# Execute command (dry-run aware)
exec_cmd() {
local cmd="$1"
if [ "$DRY_RUN" = true ]; then
echo -e "${YELLOW}[DRY-RUN] $cmd${NC}"
else
echo -e "${GREEN}[EXEC] $cmd${NC}"
eval "$cmd"
fi
}
# Main migration logic
migrate_container() {
local container="$1"
local backup_file="$BACKUP_DIR/${container}-$(date +%Y%m%d%H%M%S).tar.gz"
echo -e "${BLUE}Migrating container: $container${NC}"
# Create backup directory
exec_cmd "mkdir -p $BACKUP_DIR"
# Create snapshot
local snapshot_name="migrate-$(date +%Y%m%d%H%M%S)"
exec_cmd "lxc snapshot $container $snapshot_name --stateful"
# Export container
exec_cmd "lxc export $container $backup_file --snapshot $snapshot_name"
# Transfer to remote Incus host if specified
if [ -n "$INCUS_HOST" ]; then
exec_cmd "scp $backup_file $INCUS_HOST:$BACKUP_DIR/"
exec_cmd "rm $backup_file"
backup_file="$BACKUP_DIR/$(basename $backup_file)"
fi
# Import into Incus
local import_cmd="incus import $backup_file $container"
if [ -n "$INCUS_HOST" ]; then
import_cmd="ssh $INCUS_HOST '$import_cmd'"
fi
exec_cmd "$import_cmd"
# Cleanup snapshot
exec_cmd "lxc delete $container/$snapshot_name"
# Cleanup local backup file if not remote
if [ -z "$INCUS_HOST" ] && [ "$DRY_RUN" = false ]; then
rm "$backup_file"
fi
echo -e "${GREEN}Completed migration for: $container${NC}"
}
# Main
print_banner
check_dependencies
# Get list of containers
if [ -z "$CONTAINERS" ]; then
CONTAINERS=$(lxc list --format csv | cut -d',' -f1)
fi
# Convert comma-separated list to array
IFS=',' read -ra CONTAINER_ARRAY <<< "$CONTAINERS"
# Migrate each container
for container in "${CONTAINER_ARRAY[@]}"; do
migrate_container "$container"
done
echo -e "${GREEN}Migration complete!${NC}"

View file

@ -1 +0,0 @@
find . -maxdepth 1 -type f -exec echo -e "\n=== {} ===\n" \; -exec cat {} \; | xclip -selection clipboard

View file

@ -434,5 +434,3 @@ rustls=off,rustls_pemfile=off,tokio_rustls=off,\
Ok(())
}
// force rebuild Fri Apr 3 21:42:33 -03 2026
// Force new CI run - Tue Apr 28 05:22:39 PM -03 2026