GeneralBots/botbook
2
2
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update

Browse source
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-12-17 17:44:07 -03:00
parent 3629e948ef
commit 2c930a3316
10 changed files with 2492 additions and 764 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

401
src/04-gbui/apps/tasks.md
View file

@ -1,33 +1,69 @@
# Tasks
> **The machine does the work**
> **Describe What You Want, Get a Working App**
---
<img src="../../assets/chapter-04/autotask-interface.svg" alt="Tasks Interface" style="max-width: 100%; height: auto;">
## What is Tasks?
Tasks is where the machine does the work for you. Instead of manually tracking to-do items, you describe what you want to accomplish in natural language, and the system compiles your intent into an executable plan with automatic step-by-step execution.
Tasks is where you describe what you want and the system builds it. No coding - just tell it what you need.
| Old Way | Tasks Way |
|---------|-----------|
| Create a task | Describe your goal |
| Do it yourself | Machine plans it |
| Mark complete | Machine executes it |
| Repeat | You approve critical steps |
| You Say | You Get |
|---------|---------|
| "CRM for my cellphone store" | Working app with customers, sales, inventory |
| "Track repair status" | Kanban board with status workflow |
| "Sales dashboard" | Charts and metrics auto-updating |
---
## How It Works
| Step | What Happens |
|------|--------------|
| **1. Describe** | Write what you want in plain English |
| **2. Compile** | LLM analyzes intent, generates execution plan |
| **3. Review** | See steps, estimates, risks before execution |
| **4. Execute** | System runs the plan, pausing for approvals |
| **5. Monitor** | Watch progress, make decisions when needed |
```
DESCRIBE → PLAN → EXECUTE → DONE
```
### 1. Describe
Write what you want in plain language:
```
"Create a CRM for my cellphone store with:
- Customer list (name, phone, email)
- Product inventory with stock levels
- Sales tracking
- Repair status board"
```
### 2. Plan
System shows the execution plan:
```
Step 1: Create tables (customers, products, sales, repairs)
Step 2: Generate application UI
Step 3: Add search and filters
Step 4: Configure repair workflow
Confidence: 92% | ETA: 3 minutes
```
### 3. Execute
Watch progress in real-time:
```
[████████████████░░░░] 75%
Step 3 of 4: Adding search...
```
### 4. Done
Your app is ready:
```
✅ Application: /apps/cellphone-crm
✅ Tables: customers, products, sales, repairs
```
---
@ -35,296 +71,159 @@ Tasks is where the machine does the work for you. Instead of manually tracking t
### Write Your Intent
In the intent box, describe what you want to accomplish:
Be specific about what you want:
| Good Examples |
|---------------|
| "Make a financial CRM for Deloitte with client management and reporting" |
| "Create a website that collects leads and sends them to Salesforce" |
| "Build an automated email campaign for our product launch" |
| "Analyze Q4 sales data and generate a PDF report with charts" |
| ✅ Good | ❌ Too Vague |
|---------|--------------|
| "CRM for cellphone store with customer tracking and repair status" | "Make an app" |
| "Inventory with low stock alerts when below 10 units" | "Track stuff" |
| "Sales dashboard with daily revenue chart" | "Dashboard" |
**Tips for better results:**
### Choose Mode
- Be specific about the outcome you want
- Mention the client or project name
- Include key features or requirements
- Specify integrations if needed
| Mode | Best For |
|------|----------|
| **Automatic** | Trusted, simple tasks |
| **Supervised** | Learning, want to review each step |
| **Dry Run** | Testing - see what would happen |
### Choose Execution Mode
### Click Execute
| Mode | Best For | How It Works |
|------|----------|--------------|
| **Semi-Automatic** | Most tasks | Runs automatically, pauses for high-risk steps |
| **Supervised** | Learning/sensitive | Pauses before each step for your approval |
| **Fully Automatic** | Trusted workflows | Runs everything without stopping |
| **Dry Run** | Testing | Simulates execution without making changes |
### Set Priority
| Priority | Meaning |
|----------|---------|
| **Critical** | Urgent, run immediately |
| **High** | Important, prioritize |
| **Medium** | Normal priority (default) |
| **Low** | Run when resources available |
| **Background** | Run during idle time |
### Click Compile & Plan
The LLM will:
1. Extract entities (action, target, domain, client)
2. Generate an execution plan with ordered steps
3. Assess risks and estimate resources
4. Generate the underlying BASIC program
The system runs each step and shows progress.
---
## Understanding the Execution Plan
## Task Progress
After compilation, you see a detailed plan:
### Status Icons
### Plan Header
| Icon | Meaning |
|------|---------|
| ✓ | Completed |
| ◐ | Running |
| ○ | Pending |
| ⚠ | Needs attention |
| ✕ | Failed |
| Field | Description |
|-------|-------------|
| **Plan Name** | Auto-generated title for your task |
| **Description** | Summary of what will be accomplished |
| **Confidence** | How confident the LLM is in the plan (aim for 80%+) |
| **Risk Level** | Overall risk assessment (None/Low/Medium/High/Critical) |
| **Estimated Duration** | How long execution should take |
| **Estimated Cost** | API and compute costs |
### Steps Are Saved
### Execution Steps
Every step is stored so you can:
Each step shows:
| Field | Description |
|-------|-------------|
| **Step Number** | Order of execution |
| **Priority** | CRITICAL, HIGH, MEDIUM, LOW |
| **Step Name** | What this step does |
| **Keywords** | BASIC keywords that will be used |
| **Risk Level** | Risk for this specific step |
### Plan Actions
| Button | Action |
|--------|--------|
| **Discard** | Delete the plan, start over |
| **Edit Plan** | Modify steps before execution |
| **Simulate** | Preview impact without executing |
| **Execute** | Start running the plan |
- **Resume** if interrupted
- **Track** exactly where you are
- **Debug** if something fails
---
## Monitoring Tasks
## Your Generated App
### Task States
Apps are created at `.gbdrive/apps/{name}/`:
| Status | Meaning |
|--------|---------|
| **Draft** | Created, not yet compiled |
| **Compiling** | LLM is generating the plan |
| **Ready** | Plan generated, waiting to start |
| **Running** | Currently executing |
| **Paused** | Execution paused by user |
| **Pending Approval** | Waiting for you to approve a step |
| **Waiting Decision** | Needs your input to continue |
| **Completed** | Successfully finished |
| **Failed** | Encountered an error |
| **Cancelled** | Stopped by user |
```
.gbdrive/apps/cellphone-crm/
├── index.html # Your application
├── _assets/
│ ├── htmx.min.js
│ └── styles.css
└── schema.json # Table definitions
```
### Filter Tabs
### Direct API Access
| Tab | Shows |
|-----|-------|
| **All** | Every task regardless of status |
| **Running** | Currently executing tasks |
| **Need Approval** | Tasks waiting for your approval |
| **Decisions** | Tasks needing your input |
Your app talks directly to botserver:
### Progress Tracking
```html
<!-- List customers -->
<div hx-get="/api/db/customers" hx-trigger="load">
Each task shows:
<!-- Add customer -->
<form hx-post="/api/db/customers">
- Current step number and name
- Progress bar with percentage
- Time elapsed and estimated remaining
<!-- Search -->
<input hx-get="/api/db/customers"
hx-trigger="keyup changed delay:300ms">
```
No middleware - HTMX calls the API directly.
---
## Approvals & Decisions
## Data Storage
### When Approvals Are Required
All data uses the `user_data` virtual table:
High-impact actions require your approval:
```
Your app: cellphone-crm
Table: customers
↓
API: /api/db/customers
↓
Storage: user_data (namespaced)
```
- Sending emails to many recipients
- Modifying production databases
- Making external API calls with side effects
- Deploying to live environments
- Actions exceeding cost thresholds
### Benefits
### Approval Dialog
When approval is needed, you see:
| Field | Description |
|-------|-------------|
| **Action description** | What will happen |
| **Impact summary** | What could be affected |
| **Risk level** | How risky this step is |
| **Simulation result** | Preview of the outcome |
**Options:**
| Action | Result |
|--------|--------|
| **Approve** | Continue execution |
| **Defer** | Decide later |
| **Reject** | Skip this step or stop execution |
### Making Decisions
Sometimes the system needs your input:
- Choosing between alternative approaches
- Selecting from multiple options
- Providing missing information
Each option shows pros, cons, and impact estimates.
- Tables created on demand
- Each app isolated
- Add fields anytime
- No migrations needed
---
## Task Actions
| Action | When Available | What It Does |
|--------|----------------|--------------|
| **Details** | Always | View full task information |
| **Simulate** | Before execution | Preview impact |
| **Pause** | While running | Temporarily stop execution |
| **Resume** | When paused | Continue execution |
| **Cancel** | Anytime | Stop and discard task |
| Action | When | What It Does |
|--------|------|--------------|
| **Pause** | Running | Stop temporarily |
| **Resume** | Paused | Continue from where stopped |
| **Cancel** | Anytime | Stop and discard |
| **Retry** | Failed | Try failed step again |
---
## Creating Tasks from Chat
## From Chat
You can also create tasks by talking to your bot:
Create tasks by talking to your bot:
**You:** "I need to build a customer portal for Acme Corp"
**You:** "I need a CRM for my cellphone store"
**Bot:** "I'll create a task for that. Here's the plan:
- 5 steps, estimated 3 hours
- Includes: database setup, authentication, dashboard, API integration
- Risk: Low
**Bot:** "I'll create that. Here's the plan:
- 4 steps, ~3 minutes
- Tables: customers, products, sales, repairs
Should I execute this plan?"
Execute?"
**You:** "Yes, go ahead"
**You:** "Yes"
**Bot:** "Task started. I'll notify you when approvals are needed."
**Bot:** "Started. I'll notify you when done."
---
## Generated BASIC Code
## Examples
Every task generates a BASIC program behind the scenes. You can view and copy this code:
### Cellphone Store CRM
```bas
' AUTO-GENERATED BASIC PROGRAM
' Plan: Financial CRM for Deloitte
PLAN_START "Financial CRM", "Client management system"
STEP 1, "Create database schema", CRITICAL
STEP 2, "Setup authentication", HIGH
STEP 3, "Build client module", HIGH
PLAN_END
NEW_TABLE "clients"
COLUMN "name", STRING
COLUMN "email", STRING
COLUMN "revenue", DECIMAL
SAVE_TABLE
```
"CRM with customers, products, sales, and repair tracking
with status: received, diagnosing, repairing, ready, delivered"
```
This code can be:
### Restaurant Reservations
- Copied for manual execution
- Modified and saved as a template
- Reused for similar projects
```
"Reservation system with tables, bookings, and waitlist"
```
---
### Inventory Tracker
## Best Practices
### Writing Good Intents
| Do | Don't |
|----|-------|
| "Create a sales dashboard for Q4 data with charts showing revenue by region" | "Make something" |
| "Build an email drip campaign: welcome email, 3-day follow-up, 7-day offer" | "Do the thing we discussed" |
| "Analyze customer feedback CSV and generate sentiment report" | "Fix it" |
### Choosing Execution Mode
| Situation | Recommended Mode |
|-----------|------------------|
| New to Tasks | Supervised |
| Routine tasks | Semi-Automatic |
| Trusted, tested workflows | Fully Automatic |
| Experimenting | Dry Run |
### Managing Risk
- Review the risk assessment before executing
- Use Simulate for high-risk tasks
- Set up approval thresholds in settings
- Monitor running tasks actively
---
## Troubleshooting
### Compilation Failed
- Check that your intent is clear and specific
- Avoid ambiguous language
- Include necessary context (client name, data sources)
### Task Stuck on Running
- Check if an approval is pending
- Look for decision requests
- Review the execution log for errors
### Unexpected Results
- Review the generated plan before executing
- Use Dry Run to test first
- Check the BASIC code for issues
---
## Settings
Configure Tasks behavior in Settings:
| Setting | Description |
|---------|-------------|
| **Default execution mode** | Your preferred mode |
| **Approval thresholds** | When to require approval |
| **Cost limits** | Maximum spend per task |
| **Notification preferences** | How to alert you |
| **Auto-cleanup** | Remove completed tasks after X days |
```
"Inventory with products, suppliers, and low stock alerts"
```
---
## See Also
- [Autonomous Task AI](../../07-gbapp/autonomous-tasks.md) - Architecture details
- [CREATE SITE](../../06-gbdialog/keyword-create-site.md) - App generation
- [Calendar](./calendar.md) - Scheduled tasks
- [Chat](./chat.md) - Create tasks through conversation
- [Autonomous Tasks](../../21-autonomous-tasks/README.md) - Complete guide
- [Dev Chat Widget](../dev-chat.md) - Test while developing
- [HTMX Architecture](../htmx-architecture.md) - How the UI works

243
src/04-gbui/dev-chat.md Normal file
View file

@ -0,0 +1,243 @@
# Dev Chat Widget
> **Test Your App Without Leaving the Page**
---
## Overview
The Dev Chat Widget is a floating chat interface that lets you interact with your bot while developing. Talk to modify files, query data, or test features - all without leaving your app.
---
## Activating Dev Mode
The widget appears automatically when:
- URL contains `?dev=1`
- Cookie `dev_mode=1` is set
- Running on `localhost` or `127.0.0.1`
---
## Usage
### Opening the Chat
- **Click** the floating purple button (bottom-right)
- **Keyboard:** `Ctrl+Shift+D`
### Closing
- Click the X button
- Press `Escape`
- Click the floating button again
---
## Quick Actions
| Button | Command | What It Does |
|--------|---------|--------------|
| 📋 Tables | `show tables` | List all tables in your app |
| 📁 Files | `list files` | Show app files |
| 🔄 Reload | `reload app` | Refresh the page |
| ⚠️ Errors | `show errors` | Display any errors |
| 🗑️ Clear | - | Clear chat history |
---
## Example Commands
### Query Data
```
Show all customers
```
```
Find sales from last week
```
```
Count products with stock < 10
```
### Modify App
```
Add a notes field to the customer form
```
```
Change the status options to: new, in-progress, done
```
```
Make the table sortable by date
```
### File Operations
```
Show me index.html
```
```
Add a search box to the header
```
```
Update the page title to "My CRM"
```
---
## Adding to Your App
### Automatic (Dev Mode)
Apps generated with autonomous tasks include the dev chat automatically in dev mode.
### Manual
Add the script to any page:
```html
<script src="/_assets/dev-chat.js"></script>
```
---
## Data Storage
Chat history is stored in the `user_data` virtual table:
```
Namespace: dev_chat
Key: {app_name}_history
```
This means:
- History persists across sessions
- Each app has separate history
- No additional tables needed
---
## WebSocket Connection
The widget connects via WebSocket for real-time updates:
```
ws://localhost:8080/ws/dev
```
When connected:
- Instant responses
- File change notifications
- Auto-reload on updates
Fallback to HTTP if WebSocket unavailable.
---
## File Change Indicators
When botserver modifies files, you'll see:
| Icon | Type | Meaning |
|------|------|---------|
| ➕ | created | New file added |
| ✏️ | modified | File updated |
| ➖ | deleted | File removed |
After file changes, the app auto-reloads.
---
## JavaScript API
Access the widget programmatically:
```javascript
// Open the chat
gbDevChat.open();
// Close the chat
gbDevChat.close();
// Send a message
gbDevChat.send("show tables");
// Add a custom message
gbDevChat.addMessage("Custom notification", "system");
// Show a file change
gbDevChat.showFileChange("index.html", "modified");
```
---
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+D` | Toggle chat |
| `Escape` | Close chat |
| `Enter` | Send message |
| `Shift+Enter` | New line in message |
---
## Styling
The widget uses CSS custom properties you can override:
```css
#gb-dev-chat-btn {
--dev-primary: #667eea;
--dev-secondary: #764ba2;
}
```
---
## Security
The dev chat widget:
- Only loads in dev mode (localhost or explicit flag)
- Requires same authentication as your app
- All operations go through botserver's permission system
- Never exposed in production builds
---
## Troubleshooting
### Widget Not Appearing
1. Check you're in dev mode (`?dev=1` or localhost)
2. Verify the script is loaded
3. Check browser console for errors
### Connection Failed
1. Ensure botserver is running
2. Check WebSocket endpoint is accessible
3. Falls back to HTTP automatically
### Commands Not Working
1. Check you have permissions
2. Verify the app context is correct
3. Try more specific commands
---
## See Also
- [Autonomous Tasks](../21-autonomous-tasks/README.md) - How apps are generated
- [HTMX Architecture](./htmx-architecture.md) - Frontend patterns
- [REST API](../10-rest/README.md) - API reference

730
src/07-gbapp/autonomous-tasks.md
View file

@ -4,608 +4,312 @@
---
<img src="../assets/chapter-07/autonomous-task-flow.svg" alt="Autonomous Task AI Flow" style="max-width: 100%; height: auto;">
---
## Overview
General Bots transforms how work gets done. Instead of humans executing tasks step-by-step, you describe what you want and the AI autonomously builds, deploys, and manages everything.
Autonomous Tasks let you describe what you want and the system builds it. No coding required - just describe your application in plain language.
**Traditional approach:**
```
Human thinks → Human plans → Human codes → Human deploys → Human maintains
```
**You say:**
> "Create a CRM for my cellphone store"
**General Bots approach:**
```
Human describes intent → AI plans → AI generates → AI deploys → AI monitors
```
This is not just task automation - it's **autonomous task execution** where the LLM acts as the brain that understands, plans, and accomplishes complex work.
**You get:**
- Working HTMX application at `/apps/cellphone-crm`
- Database tables: `customers`, `products`, `sales`, `repairs`
- Forms, lists, search, filters - all functional
- Direct connection to botserver API
---
## Core Architecture
### The Foundation: .gbai + .gbdrive
Every autonomous task operates within the General Bots package structure:
## Architecture
```
project.gbai/ # The AI workspace
├── project.gbdialog/ # BASIC scripts (auto-generated)
│ ├── start.bas # Entry point
│ └── tools/ # Generated tools
├── project.gbkb/ # Knowledge base
│ └── docs/ # Reference documents
├── project.gbot/ # Configuration
│ └── config.csv # Bot settings
├── project.gbdrive/ # Online storage (MinIO bucket)
│ ├── assets/ # Generated assets
│ ├── data/ # Task data files
│ └── output/ # Produced artifacts
└── project.gbtheme/ # UI customization
┌─────────────────────────────────────────────────────────────────┐
│ Your App │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Forms │ │ Lists │ │ Actions │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └───────────────┼───────────────┘ │
│ │ HTMX │
└────────────────────────┼────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ botserver API │
│ │
│ /api/db/* /api/drive/* /api/llm/* │
│ CRUD operations File storage AI features │
│ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PostgreSQL + MinIO + LLM │
│ (user_data virtual table) │
└─────────────────────────────────────────────────────────────────┘
```
**Key insight:** The `.gbdrive` folder is a live link to cloud storage (MinIO/S3). Everything the AI creates, processes, or outputs lives here - accessible via API, web UI, or direct bucket access.
**Key insight:** Apps talk directly to botserver. No middleware, no generated backend code - just HTMX calling the API.
---
## How Autonomous Tasks Work
## The user_data Virtual Table
### 1. Intent Compilation
When you describe what you want, the LLM performs **intent compilation**:
All app data lives in one flexible table system:
```
User: "Create a CRM for tracking real estate leads with email automation"
LLM Analysis:
├── Action: CREATE
├── Target: CRM application
├── Domain: Real estate
├── Features:
│ ├── Lead tracking
│ ├── Email automation
│ └── Contact management
├── Integrations: Email service
└── Output: HTMX web application
App: cellphone-crm
Table: customers
│
▼
Namespace: cellphone-crm.customers
│
▼
Storage: user_data table with proper indexing
```
### 2. Plan Generation
Your app calls `/api/db/customers` and botserver handles the rest.
The AI generates an execution plan with ordered steps:
### Benefits
| Step | Priority | Description | Keywords |
|------|----------|-------------|----------|
| 1 | CRITICAL | Create database schema | NEW_TABLE, COLUMN |
| 2 | HIGH | Setup authentication | OAUTH, JWT |
| 3 | HIGH | Build lead management UI | CREATE SITE, FORM |
| 4 | MEDIUM | Create email templates | CREATE DRAFT |
| 5 | MEDIUM | Setup automation rules | SET SCHEDULE, ON |
| 6 | LOW | Deploy and configure | DEPLOY |
### 3. Autonomous Execution
The system executes each step, pausing only for:
- High-risk operations requiring approval
- Decisions that need human input
- External integrations requiring credentials
- **No migrations** - Tables created on demand
- **Isolation** - Each app's data is separate
- **Flexibility** - Add fields anytime
- **Security** - Per-app access control
---
## CREATE SITE: The App Generator
## How It Works
`CREATE SITE` is the cornerstone keyword for autonomous app creation. It generates complete HTMX-based web applications bound to the botserver API.
### 1. Describe
### How It Works
```basic
CREATE SITE "crm", "bottemplates/apps/crud", "Build a real estate CRM with lead tracking"
```
**Execution flow:**
1. **Template Loading**
- Reads HTML templates from `bottemplates/apps/crud/`
- Combines all `.html` files as reference
- Extracts HTMX patterns and component structures
2. **LLM Generation**
- Sends combined templates + prompt to LLM
- Generates new `index.html` with:
- HTMX attributes for dynamic behavior
- API bindings to botserver endpoints
- CSS using local `_assets` only (no external CDNs)
3. **Deployment**
- Creates folder at `<site_path>/crm/`
- Writes generated `index.html`
- Copies required assets
- Site immediately available at `/crm`
### Generated App Structure
Tell the system what you want:
```
sites/crm/
├── index.html # LLM-generated HTMX app
"Create a CRM for my cellphone store with:
- Customer tracking (name, phone, email)
- Product inventory with stock levels
- Sales linked to customers
- Repair status board"
```
### 2. Plan
System creates execution steps:
```
Step 1: Create tables (customers, products, sales, repairs)
Step 2: Generate HTMX application
Step 3: Add search and filters
Step 4: Configure repair workflow
```
### 3. Execute
Each step runs and shows progress:
```
[████████████████░░░░] 75%
Step 3 of 4: Adding search...
```
### 4. Deliver
Your app is ready:
```
✅ Application: /apps/cellphone-crm
✅ Tables: customers, products, sales, repairs
✅ Features: CRUD, search, status board
```
---
## Generated App Structure
```
.gbdrive/apps/cellphone-crm/
├── index.html # HTMX application
├── _assets/
│ ├── htmx.min.js # HTMX library
│ ├── app.js # Custom interactions
│ └── styles.css # Themed styles
└── api/ # Handled by botserver
│ ├── htmx.min.js # HTMX library
│ ├── app.js # Helpers
│ └── styles.css # Styling
└── schema.json # Table definitions
```
### HTMX + GB API Pattern
---
Generated apps use HTMX to communicate with botserver:
## HTMX Patterns
### List with Auto-Refresh
```html
<!-- Lead list with live updates -->
<div id="leads"
hx-get="/api/crm/leads"
<div id="customers"
hx-get="/api/db/customers"
hx-trigger="load, every 30s"
hx-swap="innerHTML">
Loading leads...
</div>
<!-- Add new lead form -->
<form hx-post="/api/crm/leads"
hx-target="#leads"
hx-swap="afterbegin"
hx-indicator="#saving">
<input name="name" placeholder="Lead name" required>
<input name="email" type="email" placeholder="Email">
<input name="phone" placeholder="Phone">
<button type="submit">
<span class="btn-text">Add Lead</span>
<span id="saving" class="htmx-indicator">Saving...</span>
</button>
</form>
<!-- Lead detail with inline editing -->
<div class="lead-card"
hx-get="/api/crm/leads/${id}"
hx-trigger="click"
hx-target="#detail-panel">
<h3>${name}</h3>
<p>${email}</p>
Loading...
</div>
```
### API Binding
### Create Form
The generated HTMX calls map to botserver endpoints automatically:
```html
<form hx-post="/api/db/customers"
hx-target="#customers"
hx-swap="afterbegin">
<input name="name" required>
<input name="phone">
<button type="submit">Add</button>
</form>
```
| HTMX Call | Botserver Handler | BASIC Equivalent |
|-----------|-------------------|------------------|
| `GET /api/crm/leads` | Query handler | `FIND "leads"` |
| `POST /api/crm/leads` | Insert handler | `UPSERT "leads"` |
| `PUT /api/crm/leads/:id` | Update handler | `SET "leads"` |
| `DELETE /api/crm/leads/:id` | Delete handler | `DELETE "leads"` |
### Search
```html
<input type="search"
hx-get="/api/db/customers"
hx-trigger="keyup changed delay:300ms"
hx-target="#customers"
placeholder="Search...">
```
### Delete
```html
<button hx-delete="/api/db/customers/${id}"
hx-target="closest tr"
hx-confirm="Delete?">
🗑️
</button>
```
---
## The .gbdrive Workspace
## API Mapping
Every autonomous task uses `.gbdrive` as its workspace - a cloud-synced folder structure:
| HTMX | Endpoint | Action |
|------|----------|--------|
| `hx-get` | `/api/db/customers` | List |
| `hx-get` | `/api/db/customers/123` | Get one |
| `hx-post` | `/api/db/customers` | Create |
| `hx-put` | `/api/db/customers/123` | Update |
| `hx-delete` | `/api/db/customers/123` | Delete |
### Storage Architecture
### Query Parameters
```
.gbdrive/ (MinIO bucket)
├── tasks/
│ ├── task-001/
│ │ ├── plan.json # Execution plan
│ │ ├── progress.json # Current state
│ │ ├── logs/ # Execution logs
│ │ └── output/ # Generated files
│ └── task-002/
│ └── ...
├── apps/
│ ├── crm/
│ │ ├── index.html
│ │ └── _assets/
│ └── dashboard/
│ └── ...
├── data/
│ ├── leads.json
│ ├── contacts.json
│ └── reports/
└── assets/
├── templates/
├── images/
└── documents/
?q=john # Search
?status=active # Filter
?sort=created_at # Sort
?order=desc # Direction
?limit=20&offset=40 # Pagination
```
### Accessing .gbdrive
---
**Via API:**
```javascript
// List files
fetch('/api/drive/list?path=tasks/task-001')
## Task Steps Storage
// Download file
fetch('/api/drive/download?path=apps/crm/index.html')
Every task stores its steps for:
// Upload file
fetch('/api/drive/upload', {
method: 'POST',
body: formData
})
```
- **Continuation** - Resume if interrupted
- **Progress** - Know exactly where you are
- **Debugging** - See what happened
**Via BASIC:**
```basic
' List drive contents
files = DIR ".gbdrive/tasks"
' Copy to drive
COPY "report.pdf" TO ".gbdrive/output/"
' Read from drive
data = LOAD ".gbdrive/data/leads.json"
```
**Via rclone:**
```bash
# Sync local to drive
rclone sync ./mybot.gbai drive:mybot --watch
# Download from drive
rclone copy drive:mybot/output ./local-output
```json
{
"task_id": "abc123",
"steps": [
{"order": 1, "name": "Create tables", "status": "completed"},
{"order": 2, "name": "Generate UI", "status": "running", "progress": 60},
{"order": 3, "name": "Add search", "status": "pending"}
]
}
```
---
## Execution Modes
### Semi-Automatic (Recommended)
The AI executes autonomously but pauses for critical decisions:
```
[Step 1] Creating database... ✓
[Step 2] Setting up auth... ✓
[Step 3] Building UI... ✓
[Step 4] ⚠️ APPROVAL REQUIRED
Action: Send 500 welcome emails
Impact: Email quota usage
[Approve] [Modify] [Skip]
```
### Supervised
Every step requires explicit approval:
```
[Step 1] Create database schema
Tables: leads, contacts, activities
[Approve] [Modify] [Skip]
```
### Fully Automatic
Complete autonomous execution without stops:
```
Task: "Build CRM for real estate"
Status: RUNNING
Progress: ████████████░░░░ 75%
Current: Generating email templates
ETA: 12 minutes
```
### Dry Run
Simulates execution without making changes:
```
[SIMULATION] Step 1: Would create 3 tables
[SIMULATION] Step 2: Would generate 5 HTML files
[SIMULATION] Step 3: Would create 2 email templates
[SIMULATION] Estimated cost: $0.45
[SIMULATION] Estimated time: 25 minutes
Proceed with actual execution? [Yes] [No]
```
| Mode | Behavior |
|------|----------|
| **Automatic** | Runs without stopping |
| **Supervised** | Pauses before each step |
| **Dry Run** | Shows what would happen |
---
## Generated BASIC Programs
## Dev Chat Widget
Behind every autonomous task is a BASIC program. The LLM generates executable code:
Test your app without leaving the page:
```basic
' =============================================================================
' AUTO-GENERATED: Real Estate CRM
' Created: 2024-01-15
' =============================================================================
1. Add `?dev=1` to URL or run on localhost
2. Click the floating chat icon (or Ctrl+Shift+D)
3. Talk to modify your app in real-time
PLAN_START "Real Estate CRM", "Lead tracking with email automation"
STEP 1, "Create database", CRITICAL
STEP 2, "Build UI", HIGH
STEP 3, "Setup automation", MEDIUM
PLAN_END
' -----------------------------------------------------------------------------
' STEP 1: Database Schema
' -----------------------------------------------------------------------------
NEW_TABLE "leads"
COLUMN "id", UUID, PRIMARY KEY
COLUMN "name", STRING, REQUIRED
COLUMN "email", STRING
COLUMN "phone", STRING
COLUMN "status", STRING, DEFAULT "new"
COLUMN "source", STRING
COLUMN "created_at", TIMESTAMP
SAVE_TABLE
NEW_TABLE "activities"
COLUMN "id", UUID, PRIMARY KEY
COLUMN "lead_id", UUID, FOREIGN KEY "leads.id"
COLUMN "type", STRING
COLUMN "notes", TEXT
COLUMN "created_at", TIMESTAMP
SAVE_TABLE
' -----------------------------------------------------------------------------
' STEP 2: Generate Application
' -----------------------------------------------------------------------------
CREATE SITE "crm", "bottemplates/apps/crud", "Real estate CRM with:
- Lead list with filtering and search
- Lead detail view with activity timeline
- Quick add form
- Status pipeline view (Kanban)
- Email integration buttons"
' -----------------------------------------------------------------------------
' STEP 3: Automation Rules
' -----------------------------------------------------------------------------
ON "leads" INSERT DO
' Send welcome email to new leads
IF NEW.email != "" THEN
CREATE DRAFT NEW.email, "Welcome to Our Service", "
Hi " + NEW.name + ",
Thank you for your interest...
"
END IF
' Log activity
UPSERT "activities"
SET lead_id = NEW.id
SET type = "created"
SET notes = "Lead created from " + NEW.source
END ON
' Schedule daily digest
SET SCHEDULE "0 9 * * *" DO
leads = FIND "leads", "status=new AND created_at > yesterday"
IF COUNT(leads) > 0 THEN
report = LLM "Create summary of " + COUNT(leads) + " new leads"
SEND MAIL "sales@company.com", "Daily Lead Digest", report
END IF
END SCHEDULE
```html
<script src="/_assets/dev-chat.js"></script>
```
The dev chat uses the same `user_data` system for history storage.
---
## Task Lifecycle
## Example: Cellphone Store CRM
### States
**Request:**
> "CRM for cellphone store with customers, products, sales, and repair tracking"
| State | Description |
|-------|-------------|
| `draft` | Task created, intent captured |
| `compiling` | LLM generating execution plan |
| `ready` | Plan generated, awaiting execution |
| `running` | Currently executing steps |
| `paused` | Execution paused by user |
| `pending_approval` | Waiting for approval on high-risk step |
| `waiting_decision` | Needs user input to continue |
| `completed` | Successfully finished all steps |
| `failed` | Encountered unrecoverable error |
| `cancelled` | Stopped by user |
**Result:**
### Monitoring
| Table | Fields |
|-------|--------|
| `customers` | id, name, phone, email, notes |
| `products` | id, name, brand, model, price, stock |
| `sales` | id, customer_id, product_id, quantity, total |
| `repairs` | id, customer_id, device, status, price |
Real-time task monitoring via WebSocket:
**Features:**
- Customer list with search
- Product inventory with stock alerts
- Sales entry form
- Repair status board (Kanban)
```javascript
// Connect to task updates
const ws = new WebSocket('wss://host/ws/autotask');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
switch (data.type) {
case 'step_progress':
updateProgressBar(data.progress);
break;
case 'approval_required':
showApprovalDialog(data.approval);
break;
case 'task_completed':
showSuccessNotification(data.task);
break;
}
};
```
---
## Building Your Own Autonomous Workflows
### Example: Automated Report Generator
```basic
' Intent: "Generate weekly sales report every Monday"
SET SCHEDULE "0 8 * * 1" DO
' Gather data
sales = FIND "orders", "created_at > last_week"
customers = FIND "customers", "orders > 0"
' Generate analysis
analysis = LLM "Analyze sales data: " + JSON(sales)
' Create report site
CREATE SITE "report-" + TODAY(), "bottemplates/apps/dashboard", analysis
' Notify stakeholders
SEND MAIL "team@company.com", "Weekly Sales Report", "
Report ready: /report-" + TODAY()
"
END SCHEDULE
```
### Example: Customer Onboarding Automation
```basic
' Triggered when new customer signs up
ON "customers" INSERT DO
' Create personalized welcome site
welcome_content = LLM "Create welcome page for " + NEW.name + " in " + NEW.industry
CREATE SITE "welcome-" + NEW.id, "bottemplates/apps/crud", welcome_content
' Schedule follow-up sequence
CREATE TASK "Follow up with " + NEW.name, "Call in 3 days"
' Send welcome email with site link
CREATE DRAFT NEW.email, "Welcome!", "
Hi " + NEW.name + ",
Your personalized portal is ready: /welcome-" + NEW.id
"
END ON
```
### Example: Dynamic Dashboard Builder
```basic
' User asks: "Create a dashboard showing our KPIs"
' Step 1: Analyze available data
tables = SHOW TABLES
schema = LLM "Analyze schema for KPI opportunities: " + JSON(tables)
' Step 2: Generate dashboard
CREATE SITE "dashboard", "bottemplates/apps/dashboard", "
Create executive dashboard with:
" + schema + "
Include:
- Real-time metrics cards
- Trend charts (last 30 days)
- Comparison to previous period
- Export to PDF button
"
' Step 3: Set auto-refresh
TALK "Dashboard created at /dashboard with live updates"
```
---
## Integration with GB Infrastructure
### How Apps Use botserver
Generated HTMX apps don't need their own backend - they use botserver's API:
```
┌─────────────────────────────────────────────────────────────┐
│ Generated HTMX App │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Forms │ │ Lists │ │ Charts │ │ Actions │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴────────────┴────────────┘ │
│ │ HTMX │
└─────────────────────────┼───────────────────────────────────┘
│
┌─────────────────────────┼───────────────────────────────────┐
│ botserver API │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ CRUD │ │ LLM │ │ Drive │ │ Mail │ │
│ │ /api/db │ │ /api/llm │ │/api/drive│ │/api/mail │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ ┌────┴─────────────┴─────────────┴─────────────┴────┐ │
│ │ PostgreSQL + MinIO + LLM │ │
│ └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Available API Endpoints
| Endpoint | Purpose | HTMX Usage |
|----------|---------|------------|
| `/api/db/{table}` | CRUD operations | `hx-get`, `hx-post`, `hx-put`, `hx-delete` |
| `/api/llm/complete` | LLM generation | `hx-post` with prompt |
| `/api/drive/*` | File operations | `hx-get` for download, `hx-post` for upload |
| `/api/mail/send` | Email sending | `hx-post` with recipients |
| `/api/chat` | Conversational AI | WebSocket |
**Access:** `/apps/cellphone-crm`
---
## Best Practices
### Writing Effective Intents
### Be Specific
**Good:**
```
"Create a project management app for our marketing team with:
- Kanban board for campaign tasks
- Team member assignment
- Deadline tracking with reminders
- File attachments per task
- Weekly progress reports"
```
✅ Good:
> "CRM for cellphone store with customer tracking, sales, and repair status workflow"
**Bad:**
```
"Make an app"
```
❌ Vague:
> "Make an app"
### Template Organization
### Include Workflows
Keep templates organized for reuse:
✅ Good:
> "Repair status: received → diagnosing → repairing → ready → delivered"
```
templates/
├── app/ # Full application templates
│ ├── dashboard.html
│ ├── crud-list.html
│ └── form-wizard.html
├── components/ # Reusable components
│ ├── data-table.html
│ ├── chart-card.html
│ └── form-field.html
├── emails/ # Email templates
│ ├── welcome.html
│ └── notification.html
└── reports/ # Report templates
├── summary.html
└── detailed.html
```
❌ Missing:
> "Track repairs"
### Security Considerations
### Mention Relationships
- All generated apps inherit botserver authentication
- API calls require valid session tokens
- File uploads go through virus scanning
- Database operations respect row-level security
- LLM outputs are sanitized before rendering
✅ Good:
> "Sales linked to customers and products"
❌ Unclear:
> "Sales tracking"
---
## See Also
- [CREATE SITE Keyword](../06-gbdialog/keyword-create-site.md) - Detailed syntax
- [.gbai Architecture](../02-templates/gbai.md) - Package structure
- [.gbdrive Storage](../02-templates/gbdrive.md) - File management
- [HTMX Architecture](../04-gbui/htmx-architecture.md) - UI patterns
- [API Reference](../10-rest/README.md) - botserver endpoints
- [Autonomous Tasks Chapter](../21-autonomous-tasks/README.md) - Complete guide
- [CREATE SITE](../06-gbdialog/keyword-create-site.md) - The keyword behind it
- [REST API](../10-rest/README.md) - API reference
- [HTMX Architecture](../04-gbui/htmx-architecture.md) - Frontend patterns

221
src/21-autonomous-tasks/README.md Normal file
View file

@ -0,0 +1,221 @@
# Autonomous Tasks
> **From Intent to Application**
---
## What Are Autonomous Tasks?
Autonomous Tasks transform how applications are built. Instead of writing code manually, you describe what you want, and the system generates a complete working application.
**Example:**
> "I want to create a CRM for my cellphone store"
**Result:**
- A fully functional HTMX web application at `/apps/cellphone-crm`
- Database tables for `customers`, `products`, `sales`, `repairs`
- Forms, lists, filters, and reports - all working
- Connected to your bot for AI-assisted operations
---
## How It Works
```
┌─────────────────────────────────────────────────────────────────┐
│ 1. DESCRIBE │
│ "Create a CRM for my cellphone store with customer │
│ tracking, sales, and repair status" │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. PLAN │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Step 1 │ │ Step 2 │ │ Step 3 │ │
│ │ Create │→│ Generate │→│ Setup │ │
│ │ Tables │ │ UI │ │ Workflows │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. EXECUTE │
│ [████████████████░░░░░░░░░░] 60% - Generating UI... │
│ Step 2 of 3 • ETA: 2 minutes │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. DONE │
│ ✅ Application ready at /apps/cellphone-crm │
│ ✅ Tables created: customers, products, sales, repairs │
│ ✅ AI assistant connected │
└─────────────────────────────────────────────────────────────────┘
```
---
## The Stack
| Layer | Technology | What It Does |
|-------|------------|--------------|
| **Frontend** | HTMX | Dynamic UI without writing JavaScript |
| **Backend** | botserver | API, authentication, business logic |
| **Database** | PostgreSQL | Stores your application data |
| **Storage** | MinIO/S3 | Files, documents, uploads |
| **AI** | LLM | Generates the app, powers the assistant |
### No Middleware Needed
Generated apps talk directly to botserver:
```
┌─────────────────────┐ ┌─────────────────────┐
│ HTMX Frontend │──────│ botserver │
│ │ HTTP │ │
│ - Forms │◄────►│ - /api/db/table │
│ - Lists │ │ - /api/drive/... │
│ - Actions │ │ - /api/llm/... │
└─────────────────────┘ └─────────────────────┘
```
---
## Where Apps Live
Generated applications are stored in `.gbdrive/apps`:
```
mybot.gbai/
└── mybot.gbdrive/
└── apps/
└── cellphone-crm/
├── index.html # Main application
├── _assets/
│ ├── htmx.min.js
│ ├── app.js
│ └── styles.css
└── data/
└── schema.json # Table definitions
```
Access your app at: `https://your-bot.com/apps/cellphone-crm`
---
## Data Storage
### The `user_data` Virtual Table
Every app has access to a flexible data store through the `user_data` virtual table system. When your app needs a table like `customers`, botserver maps it to the underlying storage:
```
App request: POST /api/db/customers
│
▼
botserver routes to: user_data table with namespace "cellphone-crm.customers"
│
▼
PostgreSQL storage with proper indexing and relationships
```
### Your Tables Are Real
When you create an app that needs `customers`, `products`, and `sales` tables, they're created as proper database entities:
| Table | Fields | Purpose |
|-------|--------|---------|
| `customers` | id, name, phone, email, notes | Customer records |
| `products` | id, name, brand, model, price, stock | Inventory |
| `sales` | id, customer_id, product_id, date, amount | Transactions |
| `repairs` | id, customer_id, device, status, notes | Service tracking |
---
## Task Steps
Every task is broken into steps that are stored for:
1. **Continuation** - Resume later if interrupted
2. **Progress tracking** - See exactly where you are
3. **Debugging** - Understand what happened
4. **Learning** - Improve future generations
### Step Structure
```json
{
"task_id": "abc123",
"steps": [
{
"order": 1,
"name": "Create database tables",
"status": "completed",
"started_at": "2024-01-15T10:00:00Z",
"completed_at": "2024-01-15T10:00:15Z"
},
{
"order": 2,
"name": "Generate application UI",
"status": "running",
"started_at": "2024-01-15T10:00:16Z",
"progress": 60
},
{
"order": 3,
"name": "Configure workflows",
"status": "pending"
}
]
}
```
---
## Chapter Contents
- [Task Workflow](./workflow.md) - From intent to completion
- [App Generation](./app-generation.md) - How apps are created
- [Data Model](./data-model.md) - Tables and storage
- [Progress Tracking](./progress.md) - Monitoring and continuation
- [Examples](./examples.md) - Real-world autonomous tasks
---
## Quick Example
**You say:**
> "Create a CRM for my cellphone store with customers, sales tracking, and repair status"
**The system:**
1. **Analyzes your intent:**
- Type: CRM application
- Domain: Cellphone retail
- Entities: customers, products, sales, repairs
2. **Creates the plan:**
- Step 1: Create `customers`, `products`, `sales`, `repairs` tables
- Step 2: Generate HTMX application with forms and lists
- Step 3: Add search, filters, and status workflows
3. **Executes and reports:**
```
✅ Step 1: Tables created
⏳ Step 2: Generating UI... (60%)
⏸ Step 3: Waiting
```
4. **Delivers the app:**
- URL: `/apps/cellphone-crm`
- Features: Customer list, add customer form, sales tracking, repair status board
---
## See Also
- [CREATE SITE](../06-gbdialog/keyword-create-site.md) - The keyword behind app generation
- [.gbdrive Storage](../02-templates/gbdrive.md) - Where apps live
- [REST API](../10-rest/README.md) - The API your apps use
- [HTMX Architecture](../04-gbui/htmx-architecture.md) - Frontend patterns

373
src/21-autonomous-tasks/app-generation.md Normal file
View file

@ -0,0 +1,373 @@
# App Generation
> **HTMX Applications Connected to botserver**
---
## Overview
When you request an application, the system generates a complete HTMX frontend that communicates directly with botserver's API. No middleware, no separate backend - just HTML that talks to the API.
---
## The Generated Stack
```
┌─────────────────────────────────────────────────────────────────┐
│ Generated Application │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ index.html │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Lists │ │ Forms │ │ Actions │ │ Filters │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ │ └───────────┬┴───────────┴┬───────────┘ │ │
│ │ │ HTMX │ │ │
│ └───────────────────┼─────────────┼──────────────────────┘ │
└──────────────────────┼─────────────┼──────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ botserver API │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ /api/db/* │ │/api/drive/*│ │ /api/llm/* │ │
│ │ CRUD │ │ Files │ │ AI │ │
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
│ └───────────────┼───────────────┘ │
│ ▼ │
│ PostgreSQL + MinIO │
└─────────────────────────────────────────────────────────────────┘
```
---
## Generated File Structure
When you create an app called "cellphone-crm", this is created:
```
.gbdrive/apps/cellphone-crm/
├── index.html # Main application
├── _assets/
│ ├── htmx.min.js # HTMX library
│ ├── app.js # App-specific JavaScript
│ └── styles.css # Styling
└── schema.json # Table definitions
```
---
## HTMX Patterns Used
### List View with Auto-Refresh
```html
<div id="customers"
hx-get="/api/db/customers"
hx-trigger="load, every 30s"
hx-swap="innerHTML">
Loading customers...
</div>
```
### Create Form
```html
<form hx-post="/api/db/customers"
hx-target="#customers"
hx-swap="afterbegin"
hx-indicator=".loading">
<input name="name" placeholder="Customer name" required>
<input name="phone" type="tel" placeholder="Phone">
<input name="email" type="email" placeholder="Email">
<button type="submit">
Add Customer
<span class="loading htmx-indicator">...</span>
</button>
</form>
```
### Edit in Place
```html
<tr hx-get="/api/db/customers/${id}/edit"
hx-trigger="dblclick"
hx-swap="outerHTML">
<td>${name}</td>
<td>${phone}</td>
<td>${email}</td>
</tr>
```
### Delete with Confirmation
```html
<button hx-delete="/api/db/customers/${id}"
hx-target="closest tr"
hx-swap="outerHTML swap:0.5s"
hx-confirm="Delete this customer?">
🗑️
</button>
```
### Search
```html
<input type="search"
name="q"
placeholder="Search customers..."
hx-get="/api/db/customers"
hx-trigger="keyup changed delay:300ms"
hx-target="#customers">
```
### Filter Dropdown
```html
<select name="status"
hx-get="/api/db/repairs"
hx-trigger="change"
hx-target="#repairs">
<option value="">All Status</option>
<option value="received">Received</option>
<option value="repairing">Repairing</option>
<option value="ready">Ready</option>
</select>
```
---
## API Endpoints Your App Uses
### App Context is Automatic
Your app runs inside botui (Suite). The botui proxy automatically:
1. Detects your app from the URL (`/apps/cellphone-crm/`)
2. Injects `X-App-Context: cellphone-crm` header
3. Forwards to botserver
**You don't need to do anything special** - just use normal HTMX:
```html
<!-- botui handles the app context automatically -->
<form hx-post="/api/db/customers">
<input name="name">
<button>Add</button>
</form>
```
### Endpoints
| HTMX Call | Endpoint | What It Does |
|-----------|----------|--------------|
| `hx-get="/api/db/customers"` | GET | List all customers |
| `hx-get="/api/db/customers?q=john"` | GET | Search customers |
| `hx-post="/api/db/customers"` | POST | Create customer |
| `hx-put="/api/db/customers/123"` | PUT | Update customer |
| `hx-delete="/api/db/customers/123"` | DELETE | Delete customer |
### Query Parameters
| Parameter | Example | Purpose |
|-----------|---------|---------|
| `q` | `?q=john` | Full-text search |
| `sort` | `?sort=created_at` | Sort field |
| `order` | `?order=desc` | Sort direction |
| `limit` | `?limit=20` | Results per page |
| `offset` | `?offset=40` | Pagination |
| `{field}` | `?status=active` | Filter by field |
---
## Example: Cellphone CRM
For a cellphone store CRM, the generated app includes:
### Customer List
```html
<section id="customers-section">
<header>
<h2>Customers</h2>
<input type="search"
hx-get="/api/db/customers"
hx-trigger="keyup changed delay:300ms"
hx-target="#customer-list"
placeholder="Search by name or phone...">
<button onclick="openModal('add-customer')">+ Add Customer</button>
</header>
<table>
<thead>
<tr>
<th>Name</th>
<th>Phone</th>
<th>Email</th>
<th>Actions</th>
</tr>
</thead>
<tbody id="customer-list"
hx-get="/api/db/customers"
hx-trigger="load">
</tbody>
</table>
</section>
```
### Sales Form
```html
<form id="new-sale"
hx-post="/api/db/sales"
hx-target="#recent-sales"
hx-swap="afterbegin">
<select name="customer_id" required
hx-get="/api/db/customers"
hx-trigger="load"
hx-target="this"
hx-swap="innerHTML">
<option>Loading customers...</option>
</select>
<select name="product_id" required
hx-get="/api/db/products?stock_gt=0"
hx-trigger="load"
hx-target="this"
hx-swap="innerHTML">
<option>Loading products...</option>
</select>
<input name="quantity" type="number" min="1" value="1">
<button type="submit">Complete Sale</button>
</form>
```
### Repair Status Board
```html
<div class="kanban-board">
<div class="column" data-status="received">
<h3>Received</h3>
<div hx-get="/api/db/repairs?status=received"
hx-trigger="load, every 60s">
</div>
</div>
<div class="column" data-status="diagnosing">
<h3>Diagnosing</h3>
<div hx-get="/api/db/repairs?status=diagnosing"
hx-trigger="load, every 60s">
</div>
</div>
<div class="column" data-status="repairing">
<h3>Repairing</h3>
<div hx-get="/api/db/repairs?status=repairing"
hx-trigger="load, every 60s">
</div>
</div>
<div class="column" data-status="ready">
<h3>Ready for Pickup</h3>
<div hx-get="/api/db/repairs?status=ready"
hx-trigger="load, every 60s">
</div>
</div>
</div>
```
---
## Styling
Generated apps use CSS custom properties for easy theming:
```css
:root {
--primary: #0ea5e9;
--success: #22c55e;
--warning: #f59e0b;
--danger: #ef4444;
--bg: #ffffff;
--text: #1e293b;
--border: #e2e8f0;
--radius: 8px;
}
/* Dark mode automatic */
@media (prefers-color-scheme: dark) {
:root {
--bg: #0f172a;
--text: #f1f5f9;
--border: #334155;
}
}
```
---
## JavaScript Helpers
`app.js` includes utilities for common operations:
```javascript
// Toast notifications
function toast(message, type = 'info') {
// Shows a temporary notification
}
// Modal management
function openModal(id) { ... }
function closeModal(id) { ... }
// HTMX event handling
document.body.addEventListener('htmx:afterSwap', (e) => {
// Update UI after data changes
});
document.body.addEventListener('htmx:responseError', (e) => {
toast('Error: ' + e.detail.error, 'error');
});
```
---
## Bot Integration
Your generated app can talk to the bot for AI features:
```html
<!-- AI-assisted customer lookup -->
<form hx-post="/api/llm/complete"
hx-target="#ai-result">
<input name="prompt"
placeholder="Find customers who bought iPhones last month">
<button type="submit">🤖 Ask AI</button>
</form>
<!-- AI generates the query, executes it, returns results -->
<div id="ai-result"></div>
```
---
## Customization After Generation
Generated apps can be modified:
1. **Edit directly** - Modify `index.html` in `.gbdrive/apps/`
2. **Use Designer** - Visual editor in Suite
3. **Regenerate** - Ask for changes, system updates the app
---
## See Also
- [Data Model](./data-model.md) - How tables are created
- [Progress Tracking](./progress.md) - Monitor generation
- [HTMX Architecture](../04-gbui/htmx-architecture.md) - Frontend patterns
- [REST API](../10-rest/README.md) - API reference

398
src/21-autonomous-tasks/data-model.md Normal file
View file

@ -0,0 +1,398 @@
# Data Model
> **Tables Created for Your Application**
---
## Overview
When you create an autonomous task that generates an application, the system automatically creates the database tables needed to store your data. These tables are real PostgreSQL tables with proper types, indexes, and relationships.
---
## The user_data System
Under the hood, all application data is managed through the `user_data` virtual table system. This provides:
- **Namespacing** - Each app's tables are isolated
- **Multi-tenancy** - Your data is separate from other users
- **Flexibility** - Tables can be created dynamically
- **Security** - Access control per table
### How It Works
Apps run inside botui (Suite), which proxies all API calls to botserver. The app context flows automatically:
```
┌─────────────────────────────────────────────────────────────┐
│ botui (Suite) │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Your App: /apps/cellphone-crm/ │ │
│ │ │ │
│ │ <form hx-post="/api/db/customers"> │ │
│ │ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ botui proxy │ │
│ │ - Adds X-App-Context: cellphone-crm │ │
│ │ - Forwards to botserver │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ botserver │
│ │
│ POST /api/db/customers │
│ X-App-Context: cellphone-crm │
│ │ │
│ ▼ │
│ Routes to: user_data WHERE app='cellphone-crm' │
│ AND table='customers' │
└─────────────────────────────────────────────────────────────┘
```
### App Context Detection
botui proxy determines the app from the request URL and injects the `X-App-Context` header:
| Request From | App Context |
|--------------|-------------|
| `/apps/cellphone-crm/*` | `cellphone-crm` |
| `/apps/inventory/*` | `inventory` |
| Suite main (no app) | `default` |
### Generated HTMX (No Special Headers Needed)
```html
<!-- Your app just uses normal HTMX -->
<form hx-post="/api/db/customers">
<input name="name">
<button>Add</button>
</form>
<!-- botui proxy automatically adds X-App-Context -->
```
### For External API Clients
```bash
# Must include X-App-Context header
curl -X POST https://bot.example.com/api/db/customers \
-H "X-App-Context: cellphone-crm" \
-H "Authorization: Bearer $TOKEN" \
-d '{"name": "John"}'
```
---
## Table Creation
When you describe your app, the system infers the tables needed:
**Your description:**
> "CRM for cellphone store with customer tracking, sales, and repairs"
**Tables created:**
| Table | Purpose |
|-------|---------|
| `customers` | Customer records |
| `products` | Inventory items |
| `sales` | Transaction records |
| `repairs` | Service tickets |
---
## Generated Schema
### customers
```sql
CREATE TABLE customers (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name TEXT NOT NULL,
phone TEXT,
email TEXT,
address TEXT,
notes TEXT,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_customers_name ON customers USING gin(name gin_trgm_ops);
CREATE INDEX idx_customers_phone ON customers(phone);
```
### products
```sql
CREATE TABLE products (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name TEXT NOT NULL,
brand TEXT,
model TEXT,
price DECIMAL(10,2),
cost DECIMAL(10,2),
stock INTEGER DEFAULT 0,
min_stock INTEGER DEFAULT 5,
category TEXT,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_products_brand ON products(brand);
CREATE INDEX idx_products_category ON products(category);
```
### sales
```sql
CREATE TABLE sales (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
customer_id UUID REFERENCES customers(id),
product_id UUID REFERENCES products(id),
quantity INTEGER NOT NULL DEFAULT 1,
unit_price DECIMAL(10,2),
total DECIMAL(10,2),
payment TEXT,
notes TEXT,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_sales_customer ON sales(customer_id);
CREATE INDEX idx_sales_date ON sales(created_at);
```
### repairs
```sql
CREATE TABLE repairs (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
customer_id UUID REFERENCES customers(id),
device TEXT NOT NULL,
brand TEXT,
model TEXT,
problem TEXT,
diagnosis TEXT,
solution TEXT,
status TEXT DEFAULT 'received',
price DECIMAL(10,2),
received_at TIMESTAMPTZ DEFAULT NOW(),
completed_at TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_repairs_customer ON repairs(customer_id);
CREATE INDEX idx_repairs_status ON repairs(status);
```
---
## Data Types
The system automatically selects appropriate types:
| Field Pattern | SQL Type | Example |
|---------------|----------|---------|
| `name`, `title`, `description` | TEXT | Customer name |
| `email` | TEXT (validated) | john@example.com |
| `phone` | TEXT | +1-555-0123 |
| `price`, `cost`, `amount`, `total` | DECIMAL(10,2) | 299.99 |
| `quantity`, `stock`, `count` | INTEGER | 10 |
| `date`, `_at` suffix | TIMESTAMPTZ | 2024-01-15T10:30:00Z |
| `is_`, `has_` prefix | BOOLEAN | true |
| `id` | UUID | a1b2c3d4-... |
| `_id` suffix | UUID (FK) | References another table |
---
## Relationships
Foreign keys are created automatically when fields end with `_id`:
```
customers
│
├──< sales (customer_id → customers.id)
│
└──< repairs (customer_id → customers.id)
products
│
└──< sales (product_id → products.id)
```
---
## Accessing Data
### From Your App (HTMX)
```html
<!-- List all customers -->
<div hx-get="/api/db/customers" hx-trigger="load">
<!-- Get one customer -->
<div hx-get="/api/db/customers/abc123">
<!-- Create customer -->
<form hx-post="/api/db/customers">
<!-- Update customer -->
<form hx-put="/api/db/customers/abc123">
<!-- Delete customer -->
<button hx-delete="/api/db/customers/abc123">
```
### From Chat
> "Show me all customers who bought an iPhone"
The bot queries the database and responds with results.
### API Response Format
```json
{
"data": [
{
"id": "abc123",
"name": "John Smith",
"phone": "+1-555-0123",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z"
}
],
"total": 150,
"limit": 20,
"offset": 0
}
```
---
## Filtering and Querying
### Simple Filters
```
GET /api/db/repairs?status=ready
GET /api/db/products?brand=Apple
GET /api/db/sales?customer_id=abc123
```
### Search
```
GET /api/db/customers?q=john
```
Searches across all text fields.
### Sorting
```
GET /api/db/sales?sort=created_at&order=desc
```
### Pagination
```
GET /api/db/customers?limit=20&offset=40
```
### Comparison Operators
```
GET /api/db/products?price_gt=100 # Greater than
GET /api/db/products?stock_lt=5 # Less than
GET /api/db/products?stock_gte=10 # Greater or equal
GET /api/db/repairs?status_ne=completed # Not equal
```
---
## Schema Storage
Table definitions are stored in `schema.json`:
```json
{
"app": "cellphone-crm",
"tables": {
"customers": {
"columns": {
"id": {"type": "uuid", "primary": true},
"name": {"type": "text", "required": true},
"phone": {"type": "text"},
"email": {"type": "text"}
},
"indexes": ["name", "phone"]
},
"products": {
"columns": {
"id": {"type": "uuid", "primary": true},
"name": {"type": "text", "required": true},
"price": {"type": "decimal"},
"stock": {"type": "integer", "default": 0}
}
}
},
"relationships": [
{"from": "sales.customer_id", "to": "customers.id"},
{"from": "sales.product_id", "to": "products.id"},
{"from": "repairs.customer_id", "to": "customers.id"}
]
}
```
---
## Adding Tables Later
You can ask to add tables to an existing app:
> "Add a suppliers table to my cellphone CRM"
The system will:
1. Create the `suppliers` table
2. Update `schema.json`
3. Add UI elements if requested
---
## Data Import
Import existing data via:
### CSV Upload
```
Upload suppliers.csv to /apps/cellphone-crm/import
```
### API
```bash
curl -X POST /api/db/customers/import \
-H "Content-Type: text/csv" \
--data-binary @customers.csv
```
### Chat
> "Import customers from the Excel file I uploaded"
---
## See Also
- [App Generation](./app-generation.md) - How apps are created
- [REST API](../10-rest/README.md) - Full API reference
- [Storage API](../10-rest/storage-api.md) - File storage

269
src/21-autonomous-tasks/examples.md Normal file
View file

@ -0,0 +1,269 @@
# Examples
> **Real-World Autonomous Tasks**
---
## Example 1: Cellphone Store CRM
### The Request
> "Create a CRM for my cellphone store with customer tracking, inventory, sales, and repair status"
### Generated Application
**URL:** `/apps/cellphone-crm`
**Tables Created:**
| Table | Fields |
|-------|--------|
| `customers` | id, name, phone, email, address, notes |
| `products` | id, name, brand, model, price, cost, stock |
| `sales` | id, customer_id, product_id, quantity, total, date |
| `repairs` | id, customer_id, device, problem, status, price |
**Features:**
- Customer list with search by name or phone
- Product inventory with low stock alerts
- Sales entry linked to customer and product
- Repair status board (Kanban style)
- Daily sales summary
### Execution
```
Step 1: Create database tables .................. ✓ (15s)
Step 2: Generate customer management UI ........ ✓ (45s)
Step 3: Generate product inventory UI .......... ✓ (30s)
Step 4: Generate sales tracking UI ............. ✓ (40s)
Step 5: Generate repair status board ........... ✓ (50s)
Step 6: Add search and filters ................. ✓ (25s)
Total time: 3 minutes 25 seconds
```
---
## Example 2: Restaurant Reservations
### The Request
> "Build a reservation system for my restaurant with table management and waitlist"
### Generated Application
**URL:** `/apps/restaurant-reservations`
**Tables Created:**
| Table | Fields |
|-------|--------|
| `tables` | id, number, capacity, location, status |
| `reservations` | id, guest_name, phone, party_size, date, time, table_id, status |
| `waitlist` | id, guest_name, phone, party_size, added_at, estimated_wait |
**Features:**
- Visual table layout with availability
- Reservation calendar view
- Real-time waitlist management
- SMS notification integration (if configured)
- Daily booking summary
---
## Example 3: Property Management
### The Request
> "Create a system to manage rental properties with tenants, leases, and maintenance requests"
### Generated Application
**URL:** `/apps/property-manager`
**Tables Created:**
| Table | Fields |
|-------|--------|
| `properties` | id, address, type, bedrooms, bathrooms, rent, status |
| `tenants` | id, name, phone, email, emergency_contact |
| `leases` | id, property_id, tenant_id, start_date, end_date, rent, deposit |
| `maintenance` | id, property_id, tenant_id, issue, priority, status, assigned_to |
| `payments` | id, lease_id, amount, date, method, status |
**Features:**
- Property listing with filters
- Tenant directory with lease history
- Maintenance request tracking (priority + status)
- Payment tracking with due date alerts
- Lease expiration reminders
---
## Example 4: Gym Membership
### The Request
> "Build a gym membership system with class scheduling and attendance tracking"
### Generated Application
**URL:** `/apps/gym-manager`
**Tables Created:**
| Table | Fields |
|-------|--------|
| `members` | id, name, phone, email, plan, start_date, expiry_date |
| `classes` | id, name, instructor, day, time, capacity, room |
| `enrollments` | id, member_id, class_id, enrolled_at |
| `attendance` | id, member_id, check_in, check_out |
| `payments` | id, member_id, amount, date, plan |
**Features:**
- Member check-in/check-out
- Class schedule with enrollment
- Attendance reports
- Membership expiry alerts
- Revenue tracking
---
## Example 5: Event Planning
### The Request
> "Create an event planning tool with guest lists, vendors, and budget tracking"
### Generated Application
**URL:** `/apps/event-planner`
**Tables Created:**
| Table | Fields |
|-------|--------|
| `events` | id, name, date, venue, budget, status |
| `guests` | id, event_id, name, email, rsvp_status, dietary_needs, table |
| `vendors` | id, event_id, name, service, contact, cost, status |
| `tasks` | id, event_id, task, assignee, due_date, status |
| `expenses` | id, event_id, category, description, amount, paid |
**Features:**
- Event dashboard with countdown
- Guest list with RSVP tracking
- Vendor management
- Task checklist
- Budget vs actual spending
---
## Example 6: Medical Clinic
### The Request
> "Build a patient management system for a small clinic with appointments and medical records"
### Generated Application
**URL:** `/apps/clinic-manager`
**Tables Created:**
| Table | Fields |
|-------|--------|
| `patients` | id, name, dob, phone, email, address, insurance |
| `appointments` | id, patient_id, doctor, date, time, reason, status |
| `records` | id, patient_id, date, diagnosis, treatment, notes, doctor |
| `prescriptions` | id, record_id, medication, dosage, duration |
**Features:**
- Patient search and history
- Appointment calendar
- Medical record timeline per patient
- Prescription tracking
- Daily appointment list per doctor
---
## Example 7: Inventory for Small Business
### The Request
> "Simple inventory tracking with suppliers, purchase orders, and stock alerts"
### Generated Application
**URL:** `/apps/inventory`
**Tables Created:**
| Table | Fields |
|-------|--------|
| `products` | id, sku, name, category, quantity, min_stock, location |
| `suppliers` | id, name, contact, email, phone, address |
| `purchase_orders` | id, supplier_id, status, total, created_at |
| `order_items` | id, order_id, product_id, quantity, unit_price |
| `stock_movements` | id, product_id, type, quantity, reason, date |
**Features:**
- Product list with stock levels
- Low stock alerts dashboard
- Supplier directory
- Purchase order creation
- Stock movement history
---
## Task Complexity Guide
| Complexity | Tables | Time | Example |
|------------|--------|------|---------|
| **Simple** | 1-2 | 1-2 min | Contact list, simple tracker |
| **Medium** | 3-5 | 3-5 min | CRM, basic inventory |
| **Complex** | 6-10 | 5-10 min | Full business management |
| **Large** | 10+ | 10+ min | ERP-style systems |
---
## Tips for Good Results
### Be Specific
✅ **Good:**
> "CRM for cellphone store with customers, products, sales, and repair tracking with status workflow"
❌ **Vague:**
> "Business app"
### Mention Key Features
✅ **Good:**
> "Inventory system with low stock alerts when below 10 units"
❌ **Missing detail:**
> "Inventory system"
### Include Workflows
✅ **Good:**
> "Repair tracking with statuses: received, diagnosing, repairing, ready, delivered"
❌ **No workflow:**
> "Track repairs"
---
## See Also
- [Task Workflow](./workflow.md) - How tasks are processed
- [App Generation](./app-generation.md) - Technical details
- [Data Model](./data-model.md) - Table structure

328
src/21-autonomous-tasks/progress.md Normal file
View file

@ -0,0 +1,328 @@
# Progress Tracking
> **Know Where Your Task Is**
---
## Overview
Every autonomous task shows real-time progress so you always know:
- What step is running
- How far along it is
- How much time remains
- If anything needs your attention
---
## The Progress View
```
┌────────────────────────────────────────────────────────────────┐
│ Cellphone Store CRM │
│ │
│ [████████████████████░░░░░░░░░░] 65% │
│ │
│ Step 2 of 4: Generate application UI │
│ ├─ Customer list view ✓ │
│ ├─ Product list view ✓ │
│ ├─ Sales form ◐ (in progress) │
│ └─ Repair board ○ (pending) │
│ │
│ Started: 2 min ago │
│ ETA: 3 min remaining │
│ │
│ [Pause] [Cancel] │
└────────────────────────────────────────────────────────────────┘
```
---
## Progress Indicators
| Symbol | Meaning |
|--------|---------|
| ✓ | Completed |
| ◐ | In progress |
| ○ | Pending |
| ⚠ | Needs attention |
| ✕ | Failed |
| ⏸ | Paused |
---
## Step States
Each step goes through these states:
```
pending → running → completed
↘ failed
↘ skipped
```
### State Details
| State | Description | Action |
|-------|-------------|--------|
| `pending` | Waiting to start | None needed |
| `running` | Currently executing | Monitor progress |
| `completed` | Successfully finished | None needed |
| `failed` | Encountered error | Review and retry/skip |
| `skipped` | Intentionally bypassed | None needed |
| `paused` | Waiting for resume | Click Resume |
| `approval` | Needs your approval | Approve or reject |
---
## Real-Time Updates
Progress updates via WebSocket:
```javascript
// Connect to task updates
const ws = new WebSocket('/ws/tasks');
ws.onmessage = (event) => {
const update = JSON.parse(event.data);
switch (update.type) {
case 'progress':
// Update progress bar
updateProgress(update.percent);
break;
case 'step_complete':
// Mark step as done
markStepComplete(update.step);
break;
case 'approval_needed':
// Show approval dialog
showApproval(update.approval);
break;
case 'task_complete':
// Show completion
showComplete(update.result);
break;
}
};
```
---
## Stored Progress
Progress is persisted to the database so you can:
### Resume After Interruption
If you close your browser or lose connection:
1. Task continues running on the server
2. When you return, progress is restored
3. You see exactly where it is
### Continue Later
If you pause a task:
1. Current state is saved
2. Come back anytime
3. Click Resume to continue from the exact point
### Review History
```sql
-- task_progress table
task_id | step | percent | status | updated_at
----------|---------|---------|-----------|--------------------
abc123 | 1 | 100 | completed | 2024-01-15 10:00:15
abc123 | 2 | 65 | running | 2024-01-15 10:02:30
abc123 | 3 | 0 | pending | NULL
abc123 | 4 | 0 | pending | NULL
```
---
## Progress API
### Get Task Progress
```http
GET /api/tasks/{task_id}/progress
```
**Response:**
```json
{
"task_id": "abc123",
"title": "Cellphone Store CRM",
"status": "running",
"progress": 65,
"current_step": 2,
"total_steps": 4,
"started_at": "2024-01-15T10:00:00Z",
"eta_seconds": 180,
"steps": [
{
"order": 1,
"name": "Create database tables",
"status": "completed",
"progress": 100,
"duration_ms": 15000
},
{
"order": 2,
"name": "Generate application UI",
"status": "running",
"progress": 65,
"substeps": [
{"name": "Customer list", "done": true},
{"name": "Product list", "done": true},
{"name": "Sales form", "done": false},
{"name": "Repair board", "done": false}
]
},
{
"order": 3,
"name": "Add search and filters",
"status": "pending",
"progress": 0
},
{
"order": 4,
"name": "Configure workflows",
"status": "pending",
"progress": 0
}
]
}
```
### Subscribe to Updates
```http
WS /ws/tasks/{task_id}
```
Receives real-time progress updates.
---
## Progress in Chat
Ask your bot about task progress:
> "How's my CRM task going?"
**Bot response:**
```
📊 Your Cellphone Store CRM task is 65% complete.
Currently: Generating application UI
- ✓ Customer list view
- ✓ Product list view
- ⏳ Sales form (in progress)
- ⏳ Repair board
ETA: About 3 minutes remaining.
```
---
## Notifications
Get notified when:
| Event | Notification |
|-------|--------------|
| Task starts | "Your CRM task has started" |
| Step completes | "Step 1 complete: Database created" |
| Approval needed | "⚠️ Approval required for Step 3" |
| Task completes | "✅ Your CRM is ready!" |
| Task fails | "❌ Task failed at Step 2" |
### Notification Channels
- **Browser** - Desktop notifications
- **Email** - For long-running tasks
- **Chat** - Bot sends you updates
- **Mobile** - Push notifications (if app installed)
---
## Time Estimates
The system estimates remaining time based on:
1. **Historical data** - How long similar steps took before
2. **Current progress** - How fast the current step is moving
3. **Complexity** - More complex apps take longer
### Estimate Accuracy
| Task Complexity | Estimate Accuracy |
|-----------------|-------------------|
| Simple (1-2 tables) | ±20% |
| Medium (3-5 tables) | ±30% |
| Complex (6+ tables) | ±50% |
---
## Handling Slow Tasks
If a task is taking longer than expected:
### Check Progress
```
"Status of my CRM task"
```
### See Detailed Logs
```
"Show logs for my CRM task"
```
### Cancel and Retry
```
"Cancel my CRM task and start over"
```
---
## Progress Best Practices
### Monitor Long Tasks
For tasks over 10 minutes:
- Enable email notifications
- Check in periodically
- Have fallback plans
### Pause Before Leaving
If you need to leave:
- Pause the task
- It saves state
- Resume when ready
### Review Failed Steps
When a step fails:
1. Check the error message
2. Understand what went wrong
3. Retry, skip, or modify
---
## See Also
- [Task Workflow](./workflow.md) - The complete task flow
- [App Generation](./app-generation.md) - What gets generated
- [Examples](./examples.md) - Real task examples

283
src/21-autonomous-tasks/workflow.md Normal file
View file

@ -0,0 +1,283 @@
# Task Workflow
> **From Intent to Working Application**
---
## The Four Phases
Every autonomous task goes through four phases:
```
DESCRIBE → PLAN → EXECUTE → DELIVER
```
---
## Phase 1: Describe
You describe what you want in plain language:
> "Create a CRM for my cellphone store"
The system extracts:
| Element | Extracted Value |
|---------|-----------------|
| **Action** | Create application |
| **Type** | CRM |
| **Domain** | Cellphone retail |
| **Implied entities** | customers, products, sales |
### Good Descriptions
| ✅ Good | ❌ Too Vague |
|---------|--------------|
| "CRM for cellphone store with customer tracking and repair status" | "Make an app" |
| "Sales dashboard showing daily revenue and top products" | "Dashboard" |
| "Inventory system with stock alerts when below 10 units" | "Track stuff" |
### Adding Context
Be specific about your needs:
```
"Create a CRM for my cellphone store with:
- Customer list with name, phone, email
- Product inventory with brand, model, price, stock
- Sales tracking linked to customers and products
- Repair status board (received, diagnosing, repairing, ready, delivered)
- Search by customer name or phone number"
```
---
## Phase 2: Plan
The system creates an execution plan:
```
┌────────────────────────────────────────────────────────────────┐
│ TASK: Cellphone Store CRM │
│ Confidence: 92% | Risk: Low | ETA: 5 minutes │
├────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: Create database tables [CRITICAL] │
│ → customers, products, sales, repairs │
│ │
│ Step 2: Generate application UI [HIGH] │
│ → List views, forms, navigation │
│ │
│ Step 3: Add search and filters [MEDIUM] │
│ → Name search, status filters │
│ │
│ Step 4: Configure repair workflow [MEDIUM] │
│ → Status transitions, notifications │
│ │
└────────────────────────────────────────────────────────────────┘
```
### Plan Review
Before execution, you can:
- **Accept** - Proceed with the plan
- **Modify** - Adjust steps or requirements
- **Cancel** - Discard and start over
### Step Priorities
| Priority | Meaning |
|----------|---------|
| **CRITICAL** | Must succeed for app to work |
| **HIGH** | Core functionality |
| **MEDIUM** | Important features |
| **LOW** | Nice to have |
---
## Phase 3: Execute
The system executes each step:
```
[████████████████████░░░░░░░░░░] 65%
Step 2 of 4: Generate application UI
├─ Creating customer list view... ✓
├─ Creating product list view... ✓
├─ Creating sales form...
└─ Remaining: repair board, navigation
ETA: 2 minutes
```
### Execution Modes
| Mode | Behavior | Best For |
|------|----------|----------|
| **Automatic** | Runs all steps without stopping | Trusted, simple tasks |
| **Supervised** | Pauses before each step | Learning, complex tasks |
| **Dry Run** | Shows what would happen | Testing, verification |
### Pause and Resume
Tasks can be paused at any time:
```
[PAUSED] Step 2 of 4: Generate application UI
Progress saved. Resume anytime with:
→ Click "Resume" in Tasks
→ Say "continue my CRM task"
```
When you resume, execution continues from exactly where it stopped.
---
## Phase 4: Deliver
When complete, you receive:
```
┌────────────────────────────────────────────────────────────────┐
│ ✅ TASK COMPLETE │
├────────────────────────────────────────────────────────────────┤
│ │
│ Application: Cellphone Store CRM │
│ URL: /apps/cellphone-crm │
│ │
│ Created: │
│ 📋 4 database tables (customers, products, sales, repairs) │
│ 📱 5 views (lists + forms) │
│ 🔍 Search by name, phone, status │
│ 📊 Repair status workflow │
│ │
│ [Open App] [View Details] [Create Another] │
│ │
└────────────────────────────────────────────────────────────────┘
```
---
## Stored Steps
Every step is stored in the database:
```sql
-- task_steps table
task_id | step_order | name | status | progress
------------|------------|-------------------------|-----------|----------
abc123 | 1 | Create database tables | completed | 100
abc123 | 2 | Generate application UI | completed | 100
abc123 | 3 | Add search and filters | completed | 100
abc123 | 4 | Configure repair flow | completed | 100
```
### Why Store Steps?
1. **Resume interrupted tasks** - Power outage? Network issue? Just continue.
2. **Track progress** - Know exactly where a task is
3. **Debug failures** - See which step failed and why
4. **Audit trail** - Record of what was done
---
## Error Handling
When a step fails:
```
[ERROR] Step 3: Add search and filters
Error: Could not create full-text index on 'customers' table
Reason: Column 'notes' exceeds maximum indexable length
Options:
[Retry] - Try the step again
[Skip] - Continue without this feature
[Modify] - Change the approach
[Cancel] - Stop the task
```
### Automatic Recovery
For transient errors (network timeouts, temporary unavailability), the system automatically retries up to 3 times with exponential backoff.
---
## Approvals
High-impact steps may require approval:
```
┌────────────────────────────────────────────────────────────────┐
│ ⚠️ APPROVAL REQUIRED │
├────────────────────────────────────────────────────────────────┤
│ │
│ Step: Create database tables │
│ │
│ This will create 4 new tables: │
│ • customers (6 columns) │
│ • products (7 columns) │
│ • sales (5 columns) │
│ • repairs (8 columns) │
│ │
│ Impact: Database storage increase ~1MB │
│ │
│ [Approve] [Modify] [Reject] │
│ │
└────────────────────────────────────────────────────────────────┘
```
### What Requires Approval?
| Action | Default |
|--------|---------|
| Create tables | Auto-approve |
| Delete data | Requires approval |
| External API calls | Configurable |
| Email sending | Requires approval |
| File deletion | Requires approval |
---
## Task States
```
┌─────────────┐
│ DRAFT │ Task created, not started
└──────┬──────┘
│
┌──────▼──────┐
│ PLANNING │ Generating execution plan
└──────┬──────┘
│
┌──────▼──────┐
│ READY │ Plan complete, awaiting start
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
┌──────▼──────┐ ┌───▼───┐ ┌─────▼─────┐
│ RUNNING │ │PAUSED │ │ APPROVAL │
└──────┬──────┘ └───┬───┘ │ PENDING │
│ │ └─────┬─────┘
│ │ │
└────────────┼───────────┘
│
┌────────────┼────────────┐
│ │ │
┌──────▼──────┐ ┌───▼───┐ ┌─────▼─────┐
│ COMPLETED │ │FAILED │ │ CANCELLED │
└─────────────┘ └───────┘ └───────────┘
```
---
## See Also
- [App Generation](./app-generation.md) - How apps are built
- [Progress Tracking](./progress.md) - Monitoring your tasks
- [Examples](./examples.md) - Real-world workflows

10
src/SUMMARY.md
View file

@ -61,6 +61,7 @@
- [Console Mode](./04-gbui/console-mode.md)
- [Monitoring Dashboard](./04-gbui/monitoring.md)
- [HTMX Architecture](./04-gbui/htmx-architecture.md)
- [Dev Chat Widget](./04-gbui/dev-chat.md)
- [Suite Applications](./04-gbui/apps/README.md)
- [Suite - Full Desktop](./04-gbui/apps/suite.md)
- [Chat - AI Assistant](./04-gbui/apps/chat.md)
@ -372,6 +373,15 @@
- [Best Practices](./17-testing/best-practices.md)
- [CI/CD Integration](./17-testing/ci-cd.md)
# Part XVI - Autonomous Tasks
- [Chapter 17: Autonomous Tasks](./21-autonomous-tasks/README.md)
- [Task Workflow](./21-autonomous-tasks/workflow.md)
- [App Generation](./21-autonomous-tasks/app-generation.md)
- [Data Model](./21-autonomous-tasks/data-model.md)
- [Progress Tracking](./21-autonomous-tasks/progress.md)
- [Examples](./21-autonomous-tasks/examples.md)
# Appendices
- [Appendix A: Database Model](./15-appendix/README.md)