READ

The READ keyword loads content from files stored in the bot’s drive storage, enabling bots to access documents, data files, and other stored resources.

Syntax

content = READ "filename"
content = READ "path/to/filename"
data = READ "filename.csv" AS TABLE
lines = READ "filename.txt" AS LINES

Parameters

Parameter	Type	Description
`filename`	String	Path to the file in the bot’s storage
`AS TABLE`	Flag	Parse CSV/Excel files as structured data
`AS LINES`	Flag	Return content as array of lines

Description

READ retrieves file content from the bot’s configured storage (drive bucket). It supports:

Text files (.txt, .md, .json, .xml, .csv)
Documents (.pdf, .docx) — automatically extracts text
Spreadsheets (.xlsx, .csv) — can parse as structured data
Binary files — returned as base64 encoded string

The file path is relative to the bot’s storage root. Use forward slashes for subdirectories.

Examples

Basic File Read

' Read a text file
content = READ "welcome-message.txt"
TALK content

Read from Subdirectory

' Read file from nested folder
template = READ "templates/email/welcome.html"

Read JSON Data

' Read and parse JSON configuration
config_text = READ "config.json"
config = JSON_PARSE(config_text)

TALK "Current theme: " + config.theme

Read CSV as Table

' Load CSV data as structured table
products = READ "inventory/products.csv" AS TABLE

FOR EACH product IN products
    TALK product.name + ": $" + product.price
NEXT

Read as Lines

' Read file as array of lines
faq_lines = READ "faq.txt" AS LINES

TALK "We have " + LEN(faq_lines) + " FAQ entries"

FOR EACH line IN faq_lines
    IF INSTR(line, user_question) > 0 THEN
        TALK "Found relevant FAQ: " + line
    END IF
NEXT

Read PDF Document

' Extract text from PDF
contract_text = READ "documents/contract.pdf"
TALK "Contract length: " + LEN(contract_text) + " characters"

' Use LLM to analyze
summary = LLM "Summarize the key points of this contract:\n\n" + contract_text
TALK summary

Read Excel Spreadsheet

' Load Excel data
sales_data = READ "reports/sales-q1.xlsx" AS TABLE

total = 0
FOR EACH row IN sales_data
    total = total + row.amount
NEXT

TALK "Total Q1 sales: $" + FORMAT(total, "#,##0.00")

Working with Different File Types

Text Files

' Plain text - returned as string
notes = READ "notes.txt"
readme = READ "README.md"

JSON Files

' JSON - returned as string, use JSON_PARSE for object
json_text = READ "data.json"
data = JSON_PARSE(json_text)

CSV Files

' CSV as string
csv_raw = READ "data.csv"

' CSV as structured table (recommended)
csv_data = READ "data.csv" AS TABLE
first_row = csv_data[0]

Documents

' PDF - text extracted automatically
pdf_content = READ "report.pdf"

' Word documents - text extracted automatically
doc_content = READ "proposal.docx"

Error Handling

ON ERROR RESUME NEXT

content = READ "optional-file.txt"

IF ERROR THEN
    PRINT "File not found, using default"
    content = "Default content"
END IF

Check File Exists

' List directory to check if file exists
files = LIST "documents/"

found = false
FOR EACH file IN files
    IF file.name = "report.pdf" THEN
        found = true
        EXIT FOR
    END IF
NEXT

IF found THEN
    content = READ "documents/report.pdf"
ELSE
    TALK "Report not found. Would you like me to generate one?"
END IF

Common Use Cases

Load Email Template

' Read HTML template and fill variables
template = READ "templates/order-confirmation.html"

' Replace placeholders
email_body = REPLACE(template, "{{customer_name}}", customer.name)
email_body = REPLACE(email_body, "{{order_id}}", order.id)
email_body = REPLACE(email_body, "{{total}}", FORMAT(order.total, "$#,##0.00"))

SEND MAIL customer.email, "Order Confirmation", email_body

Process Data File

' Read customer list and send personalized messages
customers = READ "campaigns/target-customers.csv" AS TABLE

FOR EACH customer IN customers
    IF customer.opted_in = "yes" THEN
        message = "Hi " + customer.first_name + ", check out our new products!"
        SEND SMS customer.phone, message
    END IF
NEXT

TALK "Campaign sent to " + LEN(customers) + " customers"

Load Bot Configuration

' Read bot settings from file
settings_text = READ "bot-settings.json"
settings = JSON_PARSE(settings_text)

' Apply settings
SET BOT MEMORY "greeting", settings.greeting
SET BOT MEMORY "language", settings.language
SET BOT MEMORY "max_retries", settings.max_retries

Knowledge Base Lookup

' Read FAQ document for quick lookups
faq_content = READ "knowledge/faq.md"

' Search for relevant section
IF INSTR(user_question, "return") > 0 THEN
    ' Extract return policy section
    start_pos = INSTR(faq_content, "## Return Policy")
    end_pos = INSTR(faq_content, "##", start_pos + 1)
    policy = MID(faq_content, start_pos, end_pos - start_pos)
    TALK policy
END IF

File Path Rules

Path	Description
`file.txt`	Root of bot’s storage
`folder/file.txt`	Subdirectory
`folder/sub/file.txt`	Nested subdirectory
`../file.txt`	Not allowed — no parent traversal
`/absolute/path`	Not allowed — paths are always relative

Configuration

Configure storage settings in config.csv:

name,value
drive-provider,seaweedfs
drive-url,http://localhost:8333
drive-bucket,my-bot
drive-read-timeout,30

Implementation Notes

Implemented in Rust under src/file/mod.rs
Automatically detects file encoding (UTF-8, UTF-16, etc.)
PDF extraction uses pdf-extract crate
DOCX extraction parses XML content
Maximum file size: 50MB (configurable)
Files are cached in memory for repeated reads

WRITE — Save content to files
LIST — List files in a directory
DOWNLOAD — Download files from URLs
UPLOAD — Upload files to storage
DELETE FILE — Remove files
GET — Read from URLs or files

READ is the primary keyword for accessing stored files. It handles text extraction from various document formats, supports structured data parsing for CSV/Excel files, and integrates seamlessly with the bot’s storage system. Use it to load templates, process data files, access configuration, and work with uploaded documents.

General Bots Documentation