diff --git a/src/04-gbui/apps/tasks.md b/src/04-gbui/apps/tasks.md index fbfd543a..5c25562b 100644 --- a/src/04-gbui/apps/tasks.md +++ b/src/04-gbui/apps/tasks.md @@ -1,33 +1,69 @@ # Tasks -> **The machine does the work** +> **Describe What You Want, Get a Working App** --- -Tasks Interface - ## 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 + +
-Each task shows: + +
-- Current step number and name -- Progress bar with percentage -- Time elapsed and estimated remaining + + +``` + +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 \ No newline at end of file +- [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 \ No newline at end of file diff --git a/src/04-gbui/dev-chat.md b/src/04-gbui/dev-chat.md new file mode 100644 index 00000000..67ee8d2b --- /dev/null +++ b/src/04-gbui/dev-chat.md @@ -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 + +``` + +--- + +## 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 \ No newline at end of file diff --git a/src/07-gbapp/autonomous-tasks.md b/src/07-gbapp/autonomous-tasks.md index 180e1058..eee82676 100644 --- a/src/07-gbapp/autonomous-tasks.md +++ b/src/07-gbapp/autonomous-tasks.md @@ -4,608 +4,312 @@ --- -Autonomous Task AI Flow - ---- - ## 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 `/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 - -
- Loading leads... -
- - - - - - - - - - -
-

${name}

-

${email}

+ Loading...
``` -### API Binding +### Create Form -The generated HTMX calls map to botserver endpoints automatically: +```html +
+ + + +
+``` -| 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 + +``` + +### Delete + +```html + +``` --- -## 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 + ``` +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 \ No newline at end of file +- [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 \ No newline at end of file diff --git a/src/21-autonomous-tasks/README.md b/src/21-autonomous-tasks/README.md new file mode 100644 index 00000000..66c82478 --- /dev/null +++ b/src/21-autonomous-tasks/README.md @@ -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 \ No newline at end of file diff --git a/src/21-autonomous-tasks/app-generation.md b/src/21-autonomous-tasks/app-generation.md new file mode 100644 index 00000000..1017d2d0 --- /dev/null +++ b/src/21-autonomous-tasks/app-generation.md @@ -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 +
+ Loading customers... +
+``` + +### Create Form + +```html +
+ + + + + + +
+``` + +### Edit in Place + +```html + + ${name} + ${phone} + ${email} + +``` + +### Delete with Confirmation + +```html + +``` + +### Search + +```html + +``` + +### Filter Dropdown + +```html + +``` + +--- + +## 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 + +
+ + +
+``` + +### 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 +
+
+

Customers

+ + +
+ + + + + + + + + + + + +
NamePhoneEmailActions
+
+``` + +### Sales Form + +```html +
+ + + + + + + + +
+``` + +### Repair Status Board + +```html +
+
+

Received

+
+
+
+ +
+

Diagnosing

+
+
+
+ +
+

Repairing

+
+
+
+ +
+

Ready for Pickup

+
+
+
+
+``` + +--- + +## 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 + +
+ + +
+ + +
+``` + +--- + +## 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 \ No newline at end of file diff --git a/src/21-autonomous-tasks/data-model.md b/src/21-autonomous-tasks/data-model.md new file mode 100644 index 00000000..7230fb94 --- /dev/null +++ b/src/21-autonomous-tasks/data-model.md @@ -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/ │ │ +│ │ │ │ +│ │
│ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ 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 + + + + +
+ + +``` + +### 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 + +
+ + +
+ + +
+ + + + + +