.gbdialog Dialogs

The .gbdialog package contains BASIC scripts that define conversation flows, tool integrations, and bot behavior.

What is .gbdialog?

.gbdialog files are written in a specialized BASIC dialect that controls:

Tool execution and integrations
LLM prompting and context
Knowledge base activation
Session and memory management
External API calls

Modern Approach: Let the LLM Work

Minimal BASIC Philosophy

Instead of complex logic, use the LLM’s natural understanding:

' Example from announcements.gbai/update-summary.bas
' Generate summaries from documents
text = GET "announcements.gbkb/news/news.pdf"
resume = LLM "In a few words, resume this: " + text
SET BOT MEMORY "resume", resume

' Example from law.gbai/case.bas
' Load context and let LLM answer questions
text = GET "case-" + cod + ".pdf"
text = "Based on this document, answer the person's questions:\n\n" + text
SET CONTEXT text
TALK "Case loaded. You can ask me anything about the case."

Key Components

1. LLM Integration

' LLM is for background processing only - generates content once for all users
' Example: Generate a summary that all users will see
text = GET "document.pdf"
summary = LLM "Summarize this document: " + text
SET BOT MEMORY "daily_summary", summary

' For interactive conversations, use SET CONTEXT and TALK
SET CONTEXT "user_type" AS "premium customer"
TALK "How can I help you today?"

2. Tool Execution

' Define tools with parameters
PARAM name AS string LIKE "John Smith" DESCRIPTION "Customer name"
PARAM email AS string LIKE "john@example.com" DESCRIPTION "Email"

' LLM automatically knows when to call this
SAVE "customers.csv", name, email
TALK "Registration complete!"

3. Knowledge Base Usage

See Knowledge Base documentation for details.

' Activate knowledge base collections
USE KB "products"
USE KB "policies"

' The system AI searches these automatically during conversations
' No LLM command needed - just TALK to the user
TALK "What product information can I help you with?"

Script Structure

Entry Point: start.bas (Optional)

The start.bas file in the .gbdialog folder is optional, but required if you want to activate tools or knowledge bases:

' Optional start script - needed only to activate tools/KB
USE KB "company_docs"
USE TOOL "book-meeting"
USE TOOL "check-status"
TALK "Welcome! How can I assist you today?"

When you need start.bas:

To activate knowledge bases with USE KB
To activate tools with USE TOOL
To set initial context or configuration

When you don’t need start.bas:

For simple conversational bots
When the LLM can handle everything without tools/KB
For basic Q&A without document search

Tool Definitions

Create separate .bas files for each tool. See KB and Tools for more information:

' enrollment.bas - The LLM knows when to use this
PARAM student_name AS string
PARAM course AS string
DESCRIPTION "Enrolls a student in a course"

SAVE "enrollments.csv", student_name, course, NOW()
TALK "Enrolled successfully!"

Best Practices

1. Minimal Logic

' Good - Let system AI handle the conversation naturally
TALK "How can I help you?"
' System AI understands context and responds appropriately

' Avoid - Don't micromanage the flow
' IF user_says_this THEN do_that...

2. Clear Tool Descriptions

DESCRIPTION "This tool books appointments for customers"
' The LLM uses this description to know when to call the tool

3. Context Over Conditions

' Provide context, not rules
SET CONTEXT "business_hours" AS "9AM-5PM weekdays"
TALK "When would you like to schedule?"
' System AI naturally understands to mention hours when relevant

4. Trust the System AI

' The system AI handles conversations naturally
TALK "Hello! I'm here to help."
' System handles greetings, questions, complaints naturally

Common Patterns

Document Summarization - Background Processing (from announcements.gbai)

' Schedule automatic updates - runs in background
SET SCHEDULE "59 * * * *"

' Fetch and summarize documents ONCE for all users
text = GET "announcements.gbkb/news/news.pdf"
resume = LLM "In a few words, resume this: " + text
SET BOT MEMORY "resume", resume  ' Stored for all users

Interactive Case Analysis - User Conversations (from law.gbai)

' Ask for case number - interactive with user
TALK "What is the case number?"
HEAR cod

' Load case document
text = GET "case-" + cod + ".pdf"

IF text THEN 
    ' Set context for system AI to use in conversation
    text = "Based on this document, answer the person's questions:\n\n" + text
    SET CONTEXT text 
    TALK "Case loaded. Ask me anything about it."
ELSE
    TALK "Case not found, please try again."
END IF

Tool Definition Pattern

' Tool parameters (auto-discovered by LLM)
PARAM name AS string
PARAM email AS string
DESCRIPTION "Enrollment tool"

' Tool logic (called when LLM decides)
SAVE "enrollments.csv", name, email
TALK "Successfully enrolled " + name

Multi-Collection Search

USE KB "products"
USE KB "reviews"  
USE KB "specifications"

' System AI searches these collections automatically during conversation
TALK "What would you like to know about our products?"

Advanced Features

Memory Management

See Storage documentation for persistent data options.

SET BOT MEMORY "company_policy", policy_text
' Available across all sessions

retrieved = GET BOT MEMORY "company_policy"

External APIs

See External APIs chapter for integration patterns.

result = GET "https://api.example.com/data"
' For background processing only
summary = LLM "Summarize this data: " + result
SET BOT MEMORY "api_summary", summary

Suggestions

See UI Interface for UI integration.

ADD SUGGESTION "Schedule Meeting" AS "schedule"
ADD SUGGESTION "View Products" AS "products"
' UI shows these as quick actions

Error Handling

The system handles errors gracefully:

Syntax errors caught at compile time
Runtime errors logged but don’t crash
LLM provides fallback responses
Timeouts prevent infinite operations

Script Execution

Scripts run in a sandboxed environment with:

Access to session state
LLM generation capabilities
Knowledge base search
Tool execution rights
External API access (configured)

Migration from Traditional Bots

Old Way (Complex Logic)

' DON'T DO THIS - 1990s style
' IF INSTR(user_input, "order") > 0 THEN
'   IF INSTR(user_input, "status") > 0 THEN
'     TALK "Checking order status..."
'   ELSE IF INSTR(user_input, "new") > 0 THEN
'     TALK "Creating new order..."
'   END IF
' END IF

New Way (System AI Intelligence)

' DO THIS - Let system AI handle conversation naturally
TALK "How can I help you with your order?"
' System AI understands context and intent automatically

The key is to trust the system AI and write less code for more intelligent behavior.

Important Distinction

LLM Command: For background/batch processing, generates content ONCE, stored in BOT MEMORY for all users
Interactive Conversations: Use HEAR/TALK/SET CONTEXT, system AI handles the natural conversation flow

General Bots Documentation