Rodrigo Rodriguez (Pragmatismo) c26fb1e3a2 Update: General project updates

2025-12-06 11:09:12 -03:00

6.6 KiB

Raw Blame History

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

Summary

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.

6.6 KiB Raw Blame History