botbook/src/06-gbdialog/keywords.md

# Keyword Reference

This section lists every BASIC keyword implemented in the GeneralBots engine. Each keyword page includes:

* **Syntax** – Exact command format
* **Parameters** – Expected arguments
* **Description** – What the keyword does
* **Example** – A short snippet showing usage

The source code for each keyword lives in `src/basic/keywords/`. Only the keywords listed here exist in the system.

## Important: Case Insensitivity

**All variables in General Bots BASIC are case-insensitive.** The preprocessor normalizes variable names to lowercase automatically.

```basic
' These all refer to the same variable
host = "https://api.example.com"
result = GET Host + "/endpoint"
TALK HOST
```

Keywords are also case-insensitive but conventionally written in UPPERCASE:

```basic
' Both work identically
TALK "Hello"
talk "Hello"
```

## Configuration Variables (param-*)

Variables defined with `param-` prefix in `config.csv` are automatically available in scripts without the prefix:

```csv
name,value
param-host,https://api.example.com
param-limit,100
param-pages,50
```

```basic
' Access directly (lowercase, no param- prefix)
result = GET host + "/items?limit=" + limit
```

See [Script Execution Flow](./script-execution-flow.md) for complete details.

---

## Complete Keyword List (Flat Reference)

| Keyword | Category | Description |
|---------|----------|-------------|
| `ADD BOT` | Multi-Agent | Add a bot to the current session with triggers |
| `ADD MEMBER` | Communication | Add member to a group |
| `ADD SUGGESTION` | UI | Add clickable suggestion button |
| `ADD TOOL` | Tools | Register a tool for the session |
| `AGGREGATE` | Data | Perform SUM, AVG, COUNT, MIN, MAX operations |
| `BOOK` | Special | Book an appointment |
| `BOT REFLECTION` | Multi-Agent | Enable agent self-analysis and improvement |
| `BROADCAST TO BOTS` | Multi-Agent | Send message to all bots in session |
| `CLEAR HEADERS` | HTTP | Clear all HTTP headers |
| `CLEAR KB` | Knowledge | Unload knowledge base from session |
| `CLEAR SUGGESTIONS` | UI | Remove all suggestion buttons |
| `CLEAR TOOLS` | Tools | Remove all registered tools |
| `COMPRESS` | Files | Create ZIP archive |
| `COPY` | Files | Copy a file |
| `CREATE DRAFT` | Communication | Create email draft |
| `CREATE SITE` | Tools | Generate a website |
| `CREATE TASK` | Tools | Create a task |
| `DELEGATE TO BOT` | Multi-Agent | Send task to another bot |
| `DELETE` | Data | Delete records from table |
| `DELETE FILE` | Files | Delete a file |
| `DELETE HTTP` | HTTP | Send HTTP DELETE request |
| `DOWNLOAD` | Files | Download file from URL |
| `EXIT FOR` | Control | Exit loop early |
| `EXTRACT` | Files | Extract ZIP archive |
| `FILL` | Data | Fill template with data |
| `FILTER` | Data | Filter records by condition |
| `FIND` | Data | Search in files or KB |
| `FIRST` | Data | Get first element |
| `FOR EACH ... NEXT` | Control | Loop through items |
| `FORMAT` | Data | Format strings and dates |
| `GENERATE PDF` | Files | Generate PDF from template |
| `GET` | Variables | Get variable or API data |
| `GET BOT MEMORY` | Memory | Retrieve bot-level persisted data |
| `GET USER MEMORY` | Memory | Retrieve user-level persisted data (cross-bot) |
| `GRAPHQL` | HTTP | Execute GraphQL query |
| `GROUP BY` | Data | Group data by field |
| `HEAR` | Dialog | Get input from user |
| `IF ... THEN ... ELSE ... END IF` | Control | Conditional logic |
| `INSERT` | Data | Insert new record |
| `INSTR` | String | Find position of substring |
| `IS NUMERIC` | String | Check if value is numeric |
| `JOIN` | Data | Join two datasets |
| `LAST` | Data | Get last element |
| `LIST` | Files | List directory contents |
| `LLM` | AI | Query language model |
| `MAP` | Data | Map field names |
| `MERGE` | Data | Merge data into table |
| `MERGE PDF` | Files | Merge multiple PDFs |
| `MOVE` | Files | Move or rename file |
| `ON` | Events | Event handler |
| `PATCH` | HTTP | Send HTTP PATCH request |
| `PIVOT` | Data | Create pivot table |
| `POST` | HTTP | Send HTTP POST request |
| `PRINT` | Debug | Debug output to console |
| `PUT` | HTTP | Send HTTP PUT request |
| `READ` | Files | Read file content |
| `REMEMBER` | Memory | Store user-specific memory |
| `RUN BASH` | Code Execution | Execute Bash script in sandbox |
| `RUN JAVASCRIPT` | Code Execution | Execute JavaScript in sandbox |
| `RUN PYTHON` | Code Execution | Execute Python code in sandbox |
| `SAVE` | Data | Save data to table (upsert) |
| `SAVE FROM UNSTRUCTURED` | Data | Extract structured data from text |
| `SEND MAIL` | Communication | Send email |
| `SET` | Variables | Set variable value |
| `SET BOT MEMORY` | Memory | Persist data at bot level |
| `SET CONTEXT` | AI | Add context for LLM |
| `SET HEADER` | HTTP | Set HTTP header |
| `SET SCHEDULE` | Events | Schedule script execution |
| `SET USER` | Session | Set user context |
| `SET USER FACT` | Memory | Store a fact about the user |
| `SET USER MEMORY` | Memory | Persist data at user level (cross-bot) |
| `SOAP` | HTTP | Execute SOAP API call |
| `SWITCH ... CASE ... END SWITCH` | Control | Switch statement |
| `SYNCHRONIZE` | Data | Sync API data to table (planned) |
| `TALK` | Dialog | Send message to user |
| `TRANSFER CONVERSATION` | Multi-Agent | Hand off conversation to another bot |
| `UPDATE` | Data | Update existing records |
| `USE MODEL` | AI | Switch LLM model for subsequent operations |
| `USER FACTS` | Memory | Get all stored user facts |
| `UPLOAD` | Files | Upload file to storage |
| `USE KB` | Knowledge | Load knowledge base |
| `USE TOOL` | Tools | Register tool definition |
| `USE WEBSITE` | Knowledge | Associate website with session |
| `WAIT` | Control | Pause execution |
| `WEATHER` | Special | Get weather information |
| `WEBHOOK` | Events | Create webhook endpoint |
| `WHILE ... WEND` | Control | While loop |
| `WRITE` | Files | Write content to file |

---

## Keywords by Category

### Core Dialog Keywords

| Keyword | Syntax | Description |
|---------|--------|-------------|
| TALK | `TALK "message"` | Send message to user |
| HEAR | `HEAR variable` or `HEAR variable AS TYPE` | Get input from user |
| WAIT | `WAIT seconds` | Pause execution |
| PRINT | `PRINT "debug message"` | Debug output to console |

### Variable & Memory

| Keyword | Syntax | Description |
|---------|--------|-------------|
| SET | `SET variable = value` or `let variable = value` | Set variable value |
| GET | `result = GET "path"` | Get variable or fetch data |
| SET BOT MEMORY | `SET BOT MEMORY "key", value` | Persist data at bot level |
| GET BOT MEMORY | `value = GET BOT MEMORY("key")` | Retrieve persisted data |
| SET USER MEMORY | `SET USER MEMORY "key", value` | Persist data at user level (cross-bot) |
| GET USER MEMORY | `value = GET USER MEMORY("key")` | Retrieve user-level data |
| SET USER FACT | `SET USER FACT "key", value` | Store fact about user |
| USER FACTS | `facts = USER FACTS()` | Get all user facts |
| REMEMBER | `REMEMBER "key", value` | Store user-specific memory |

### AI & Context

| Keyword | Syntax | Description |
|---------|--------|-------------|
| LLM | `result = LLM "prompt"` | Query language model |
| SET CONTEXT | `SET CONTEXT "name" AS "value"` | Add context for LLM |
| SET USER | `SET USER userid` | Set user context |
| USE MODEL | `USE MODEL "modelname"` | Switch LLM model (fast/quality/code/auto) |

### Multi-Agent Orchestration

| Keyword | Syntax | Description |
|---------|--------|-------------|
| ADD BOT | `ADD BOT "name" TRIGGER ON "keywords"` | Add bot with triggers |
| DELEGATE TO BOT | `result = DELEGATE "message" TO BOT "name"` | Send task to bot |
| BROADCAST TO BOTS | `BROADCAST "message" TO BOTS` | Message all bots |
| TRANSFER CONVERSATION | `TRANSFER CONVERSATION TO "botname"` | Hand off to bot |
| BOT REFLECTION | `BOT REFLECTION true` | Enable self-analysis |
| BOT REFLECTION INSIGHTS | `insights = BOT REFLECTION INSIGHTS()` | Get analysis results |

### Code Execution (Sandboxed)

| Keyword | Syntax | Description |
|---------|--------|-------------|
| RUN PYTHON | `result = RUN PYTHON "code"` | Execute Python in sandbox |
| RUN JAVASCRIPT | `result = RUN JAVASCRIPT "code"` | Execute JS in sandbox |
| RUN BASH | `result = RUN BASH "code"` | Execute Bash in sandbox |
| RUN ... WITH FILE | `result = RUN PYTHON WITH FILE "script.py"` | Run script file |

### Knowledge Base

| Keyword | Syntax | Description |
|---------|--------|-------------|
| USE KB | `USE KB "kbname"` | Load knowledge base |
| CLEAR KB | `CLEAR KB` or `CLEAR KB "kbname"` | Unload knowledge base |
| USE WEBSITE | `USE WEBSITE "url"` | Associate website with session |
| FIND | `result = FIND "file", "filter"` | Search in files or KB |

### Tools & Automation

| Keyword | Syntax | Description |
|---------|--------|-------------|
| ADD TOOL | `ADD TOOL "toolname"` | Register tool for session |
| USE TOOL | `USE TOOL "toolname"` | Load tool definition |
| CLEAR TOOLS | `CLEAR TOOLS` | Remove all registered tools |
| CREATE TASK | `CREATE TASK "title", "description"` | Create a task |
| CREATE SITE | `CREATE SITE "alias", "template", "prompt"` | Generate a website |
| CREATE DRAFT | `CREATE DRAFT "to", "subject", "body"` | Create email draft |

### UI & Interaction

| Keyword | Syntax | Description |
|---------|--------|-------------|
| ADD SUGGESTION | `ADD SUGGESTION "key" AS "display text"` | Add clickable button |
| CLEAR SUGGESTIONS | `CLEAR SUGGESTIONS` | Remove all buttons |

### Data Operations

| Keyword | Syntax | Description |
|---------|--------|-------------|
| SAVE | `SAVE "table", var1, var2, var3` | Save data (upsert) |
| INSERT | `result = INSERT "table", data` | Insert new record |
| UPDATE | `rows = UPDATE "table", "filter", data` | Update records |
| DELETE | `rows = DELETE "table", "filter"` | Delete records |
| MERGE | `result = MERGE "table", data, "key"` | Merge data into table |
| FILTER | `result = FILTER data, "condition"` | Filter records |
| AGGREGATE | `result = AGGREGATE "SUM", data, "field"` | Aggregate operations |
| JOIN | `result = JOIN left, right, "key"` | Join datasets |
| PIVOT | `result = PIVOT data, "row", "value"` | Create pivot table |
| GROUP BY | `result = GROUP BY data, "field"` | Group data |
| SYNCHRONIZE | `SYNCHRONIZE endpoint, table, key, pageVar, limitVar` | Sync API to table |
| MAP | `result = MAP data, "old->new"` | Map field names |
| FILL | `result = FILL data, template` | Fill template |
| FIRST | `result = FIRST collection` | Get first element |
| LAST | `result = LAST collection` | Get last element |
| FORMAT | `result = FORMAT value AS "pattern"` | Format strings/dates |

### File Operations

| Keyword | Syntax | Description |
|---------|--------|-------------|
| READ | `content = READ "path"` | Read file content |
| WRITE | `WRITE "path", content` | Write to file |
| DELETE FILE | `DELETE FILE "path"` | Delete a file |
| COPY | `COPY "source", "destination"` | Copy a file |
| MOVE | `MOVE "source", "destination"` | Move/rename file |
| LIST | `files = LIST "path/"` | List directory |
| UPLOAD | `url = UPLOAD file, "path"` | Upload file |
| DOWNLOAD | `path = DOWNLOAD "url", "local"` | Download file |
| COMPRESS | `archive = COMPRESS files, "name.zip"` | Create ZIP |
| EXTRACT | `files = EXTRACT "archive.zip", "dest/"` | Extract ZIP |
| GENERATE PDF | `result = GENERATE PDF "template", data, "output.pdf"` | Generate PDF |
| MERGE PDF | `result = MERGE PDF files, "merged.pdf"` | Merge PDFs |

### HTTP & API Operations

| Keyword | Syntax | Description |
|---------|--------|-------------|
| POST | `result = POST "url", data` | HTTP POST request |
| PUT | `result = PUT "url", data` | HTTP PUT request |
| PATCH | `result = PATCH "url", data` | HTTP PATCH request |
| DELETE HTTP | `result = DELETE HTTP "url"` | HTTP DELETE request |
| SET HEADER | `SET HEADER "name", "value"` | Set HTTP header |
| CLEAR HEADERS | `CLEAR HEADERS` | Clear all headers |
| GRAPHQL | `result = GRAPHQL "url", "query", vars` | GraphQL query |
| SOAP | `result = SOAP "wsdl", "operation", params` | SOAP call |

### Flow Control

| Keyword | Syntax | Description |
|---------|--------|-------------|
| IF...THEN...ELSE | `IF condition THEN ... ELSE ... END IF` | Conditional |
| FOR EACH...NEXT | `FOR EACH item IN collection ... NEXT item` | Loop |
| EXIT FOR | `EXIT FOR` | Exit loop early |
| `WHILE...WEND` | `WHILE condition ... WEND` | While loop |
| `SWITCH...CASE` | `SWITCH value CASE x ... END SWITCH` | Switch statement |
| `REPORT` | `SEND EMAIL admin, REPORT` | Access sync statistics |
| `RESET REPORT` | `RESET REPORT` | Clear sync statistics |

### Events & Scheduling

| Keyword | Syntax | Description |
|---------|--------|-------------|
| ON | `ON "event" CALL handler` | Event handler |
| SET SCHEDULE | `SET SCHEDULE "cron"` | Schedule execution |
| WEBHOOK | `WEBHOOK "endpoint"` | Create webhook |

### Communication

| Keyword | Syntax | Description |
|---------|--------|-------------|
| SEND MAIL | `SEND MAIL "to", "subject", "body"` | Send email |
| ADD MEMBER | `ADD MEMBER "email", "group"` | Add to group |

### Special Functions

| Keyword | Syntax | Description |
|---------|--------|-------------|
| BOOK | `BOOK "appointment"` | Book appointment |
| WEATHER | `weather = WEATHER "location"` | Get weather |
| INSTR | `pos = INSTR(string, search)` | Find substring |
| IS NUMERIC | `result = IS NUMERIC(value)` | Check if numeric |
| SAVE FROM UNSTRUCTURED | `data = SAVE FROM UNSTRUCTURED text, schema` | Extract structured data |

---

## Syntax Rules

### DO ✅

```basic
' Variable names (no underscores in names)
let ticketnumber = "TKT001"
let useremail = "user@example.com"

' SAVE with field names = variable names
SAVE "table.csv", ticketnumber, useremail, status

' Keywords with spaces
SET BOT MEMORY "last_ticket", ticketnumber
SET CONTEXT "name" AS "description"
ADD SUGGESTION "key" AS "Display text"
CLEAR SUGGESTIONS
USE KB "myknowledge"
USE TOOL "mytool"

' GET BOT MEMORY as function
let lastticket = GET BOT MEMORY("last_ticket")
```

### DON'T ❌

```basic
' NO: Complex object operations
SET object.field = value  ' WRONG
SAVE "table", object.id, object  ' WRONG

' NO: IF for input validation (use HEAR AS TYPE instead)
IF value = "" THEN  ' OK for logic, but for input use:
HEAR value AS STRING  ' Better - validates input type
```

---

## Prompt Blocks

Special multi-line blocks for AI configuration and formatted output:

| Block | Purpose | Documentation |
|-------|---------|---------------|
| `BEGIN SYSTEM PROMPT ... END SYSTEM PROMPT` | Define AI persona, rules, capabilities | [Prompt Blocks](./prompt-blocks.md) |
| `BEGIN TALK ... END TALK` | Formatted multi-line messages with Markdown | [Prompt Blocks](./prompt-blocks.md) |

```basic
BEGIN SYSTEM PROMPT
You are a helpful assistant for AcmeStore.
Rules:
1. Always be polite
2. Never discuss competitors
END SYSTEM PROMPT

BEGIN TALK
**Welcome!** 🎉

I can help you with:
• Orders
• Tracking
• Returns
END TALK
```

---

## Script Structure

### No MAIN Function

Scripts execute from line 1 - no `MAIN` or entry point needed:

```basic
' ✅ CORRECT - Start directly
TALK "Hello!"
ADD TOOL "my-tool"

' ❌ WRONG - Don't use MAIN
SUB MAIN()
    TALK "Hello"
END SUB
```

### SUB and FUNCTION for Reuse

Use for helper code within tools, not as entry points:

```basic
FUNCTION CalculateTotal(price, quantity)
    RETURN price * quantity
END FUNCTION

SUB NotifyAdmin(message)
    SEND EMAIL admin1, message
END SUB

' Execution starts here
total = CalculateTotal(19.99, 3)
CALL NotifyAdmin("Order processed")
```

See [Script Execution Flow](./script-execution-flow.md) for entry points and lifecycle.

---

## Notes

- Keywords are case-insensitive (TALK = talk = Talk)
- Variables are case-insensitive (host = HOST = Host)
- String parameters can use double quotes or single quotes
- Comments start with REM or '
- Line continuation uses underscore (_)
- Objects are created with `#{ key: value }` syntax
- Arrays use `[item1, item2, ...]` syntax
- param-* config values become global variables

---

## See Also

- [Script Execution Flow](./script-execution-flow.md) - Entry points and lifecycle
- [Prompt Blocks](./prompt-blocks.md) - BEGIN SYSTEM PROMPT & BEGIN TALK
- [Basics](./basics.md) - Core concepts
- [Examples](./examples-consolidated.md) - Real-world patterns