botserver/docs/HEAR_VALIDATION_REFERENCE.md

# HEAR Keyword - Input Validation Reference

> Complete reference for HEAR keyword with automatic input validation in General Bots BASIC

## Overview

The `HEAR` keyword waits for user input with optional automatic validation. When using `HEAR AS <TYPE>`, the system will:

1. Wait for user input
2. Validate against the specified type
3. **Automatically retry** with a helpful error message if invalid
4. Return the normalized/parsed value once valid

This eliminates the need for manual validation loops and provides a consistent, user-friendly experience.

---

## Table of Contents

1. [Basic HEAR](#basic-hear)
2. [Text Validation Types](#text-validation-types)
3. [Numeric Types](#numeric-types)
4. [Date/Time Types](#datetime-types)
5. [Brazilian Document Types](#brazilian-document-types)
6. [Contact Types](#contact-types)
7. [Menu Selection](#menu-selection)
8. [Media Types](#media-types)
9. [Authentication Types](#authentication-types)
10. [Examples](#examples)
11. [Best Practices](#best-practices)

---

## Basic HEAR

```basic
' Simple HEAR without validation - accepts any input
HEAR response
TALK "You said: " + response
```

---

## Text Validation Types

### HEAR AS EMAIL

Validates email address format and normalizes to lowercase.

```basic
TALK "What's your email address?"
HEAR email AS EMAIL
TALK "We'll send confirmation to: " + email
```

**Validation:**
- Must contain `@` symbol
- Must have valid domain format
- Normalized to lowercase

**Error message:** "Please enter a valid email address (e.g., user@example.com)"

---

### HEAR AS NAME

Validates name format (letters, spaces, hyphens, apostrophes).

```basic
TALK "What's your full name?"
HEAR name AS NAME
TALK "Nice to meet you, " + name + "!"
```

**Validation:**
- Minimum 2 characters
- Maximum 100 characters
- Only letters, spaces, hyphens, apostrophes
- Auto-capitalizes first letter of each word

**Error message:** "Please enter a valid name (letters and spaces only)"

---

### HEAR AS URL

Validates and normalizes URL format.

```basic
TALK "Enter your website URL:"
HEAR website AS URL
TALK "I'll check " + website
```

**Validation:**
- Valid URL format
- Auto-adds `https://` if protocol missing

**Error message:** "Please enter a valid URL"

---

### HEAR AS PASSWORD

Validates password strength (minimum requirements).

```basic
TALK "Create a password (minimum 8 characters):"
HEAR password AS PASSWORD
' Returns "[PASSWORD SET]" - actual password stored securely
```

**Validation:**
- Minimum 8 characters
- Returns strength indicator (weak/medium/strong)
- Never echoes the actual password

**Error message:** "Password must be at least 8 characters"

---

### HEAR AS COLOR

Validates and normalizes color values.

```basic
TALK "Pick a color:"
HEAR color AS COLOR
TALK "You selected: " + color  ' Returns hex format like #FF0000
```

**Accepts:**
- Named colors: "red", "blue", "green", etc.
- Hex format: "#FF0000" or "FF0000"
- RGB format: "rgb(255, 0, 0)"

**Returns:** Normalized hex format (#RRGGBB)

---

### HEAR AS UUID

Validates UUID/GUID format.

```basic
TALK "Enter the transaction ID:"
HEAR transaction_id AS UUID
```

---

## Numeric Types

### HEAR AS INTEGER

Validates and parses integer numbers.

```basic
TALK "How old are you?"
HEAR age AS INTEGER
TALK "In 10 years you'll be " + STR(age + 10)
```

**Validation:**
- Accepts whole numbers only
- Removes formatting (commas, spaces)
- Returns numeric value

**Error message:** "Please enter a valid whole number"

---

### HEAR AS FLOAT / DECIMAL

Validates and parses decimal numbers.

```basic
TALK "Enter the temperature:"
HEAR temperature AS FLOAT
TALK "Temperature is " + STR(temperature) + "°C"
```

**Validation:**
- Accepts decimal numbers
- Handles both `.` and `,` as decimal separator
- Returns numeric value rounded to 2 decimal places

---

### HEAR AS MONEY / CURRENCY / AMOUNT

Validates and normalizes monetary amounts.

```basic
TALK "How much would you like to transfer?"
HEAR amount AS MONEY
TALK "Transferring R$ " + FORMAT(amount, "#,##0.00")
```

**Accepts:**
- "100"
- "100.00"
- "1,234.56" (US format)
- "1.234,56" (Brazilian/European format)
- "R$ 100,00"
- "$100.00"

**Returns:** Normalized decimal value (e.g., "1234.56")

**Error message:** "Please enter a valid amount (e.g., 100.00 or R$ 100,00)"

---

### HEAR AS CREDITCARD / CARD

Validates credit card number using Luhn algorithm.

```basic
TALK "Enter your card number:"
HEAR card AS CREDITCARD
' Returns masked format: "4111 **** **** 1111"
```

**Validation:**
- 13-19 digits
- Passes Luhn checksum
- Detects card type (Visa, Mastercard, Amex, etc.)

**Returns:** Masked card number with metadata about card type

---

## Date/Time Types

### HEAR AS DATE

Validates and parses date input.

```basic
TALK "When is your birthday?"
HEAR birthday AS DATE
TALK "Your birthday is " + FORMAT(birthday, "MMMM d")
```

**Accepts multiple formats:**
- "25/12/2024" (DD/MM/YYYY)
- "12/25/2024" (MM/DD/YYYY)
- "2024-12-25" (ISO format)
- "25 Dec 2024"
- "December 25, 2024"
- "today", "tomorrow", "yesterday"
- "hoje", "amanhã", "ontem" (Portuguese)

**Returns:** Normalized ISO date (YYYY-MM-DD)

**Error message:** "Please enter a valid date (e.g., 25/12/2024 or 2024-12-25)"

---

### HEAR AS HOUR / TIME

Validates and parses time input.

```basic
TALK "What time should we schedule the meeting?"
HEAR meeting_time AS HOUR
TALK "Meeting scheduled for " + meeting_time
```

**Accepts:**
- "14:30" (24-hour format)
- "2:30 PM" (12-hour format)
- "14:30:00" (with seconds)

**Returns:** Normalized 24-hour format (HH:MM)

**Error message:** "Please enter a valid time (e.g., 14:30 or 2:30 PM)"

---

## Brazilian Document Types

### HEAR AS CPF

Validates Brazilian CPF (individual taxpayer ID).

```basic
TALK "Enter your CPF:"
HEAR cpf AS CPF
TALK "CPF validated: " + cpf  ' Returns formatted: 123.456.789-09
```

**Validation:**
- 11 digits
- Valid check digits (mod 11 algorithm)
- Rejects known invalid patterns (all same digit)

**Returns:** Formatted CPF (XXX.XXX.XXX-XX)

**Error message:** "Please enter a valid CPF (11 digits)"

---

### HEAR AS CNPJ

Validates Brazilian CNPJ (company taxpayer ID).

```basic
TALK "Enter your company's CNPJ:"
HEAR cnpj AS CNPJ
TALK "CNPJ validated: " + cnpj  ' Returns formatted: 12.345.678/0001-95
```

**Validation:**
- 14 digits
- Valid check digits

**Returns:** Formatted CNPJ (XX.XXX.XXX/XXXX-XX)

**Error message:** "Please enter a valid CNPJ (14 digits)"

---

## Contact Types

### HEAR AS MOBILE / PHONE / TELEPHONE

Validates phone number format.

```basic
TALK "What's your phone number?"
HEAR phone AS MOBILE
TALK "We'll send SMS to: " + phone
```

**Validation:**
- 10-15 digits
- Auto-formats based on detected country

**Returns:** Formatted phone number

**Error message:** "Please enter a valid mobile number"

---

### HEAR AS ZIPCODE / CEP / POSTALCODE

Validates postal code format.

```basic
TALK "What's your ZIP code?"
HEAR cep AS ZIPCODE
TALK "Your ZIP code is: " + cep
```

**Supports:**
- Brazilian CEP: 8 digits → "12345-678"
- US ZIP: 5 or 9 digits → "12345" or "12345-6789"
- UK postcode: alphanumeric → "SW1A 1AA"

**Returns:** Formatted postal code with country detection

---

## Menu Selection

### HEAR AS "Option1", "Option2", "Option3"

Presents a menu and validates selection.

```basic
TALK "Choose your preferred fruit:"
HEAR fruit AS "Apple", "Banana", "Orange", "Mango"
TALK "You selected: " + fruit
```

**Accepts:**
- Exact match: "Apple"
- Case-insensitive: "apple"
- Numeric selection: "1", "2", "3"
- Partial match: "app" → "Apple" (if unique)

**Automatically adds suggestions** for the menu options.

**Error message:** "Please select one of: Apple, Banana, Orange, Mango"

---

### HEAR AS BOOLEAN

Validates yes/no response.

```basic
TALK "Do you agree to the terms?"
HEAR agreed AS BOOLEAN
IF agreed THEN
    TALK "Thank you for agreeing!"
ELSE
    TALK "You must agree to continue."
END IF
```

**Accepts (true):** "yes", "y", "true", "1", "sim", "ok", "sure", "confirm"

**Accepts (false):** "no", "n", "false", "0", "não", "cancel", "deny"

**Returns:** "true" or "false" (with boolean metadata)

**Error message:** "Please answer yes or no"

---

### HEAR AS LANGUAGE

Validates language code or name.

```basic
TALK "What language do you prefer?"
HEAR language AS LANGUAGE
SET CONTEXT LANGUAGE language
TALK "Language set to: " + language
```

**Accepts:**
- ISO codes: "en", "pt", "es", "fr", "de"
- Full names: "English", "Portuguese", "Spanish"
- Native names: "Português", "Español", "Français"

**Returns:** ISO 639-1 language code

---

## Media Types

### HEAR AS IMAGE / PHOTO / PICTURE

Waits for image upload.

```basic
TALK "Please send a photo of your document:"
HEAR document_photo AS IMAGE
TALK "Image received: " + document_photo
' Returns URL to the uploaded image
```

**Validation:**
- Must receive image attachment
- Accepts: JPG, PNG, GIF, WebP

**Error message:** "Please send an image"

---

### HEAR AS QRCODE

Waits for image with QR code and reads it.

```basic
TALK "Send me a photo of the QR code:"
HEAR qr_data AS QRCODE
TALK "QR code contains: " + qr_data
```

**Process:**
1. Waits for image upload
2. Calls BotModels vision API to decode QR
3. Returns the decoded data

**Error message:** "Please send an image containing a QR code"

---

### HEAR AS AUDIO / VOICE / SOUND

Waits for audio input and transcribes to text.

```basic
TALK "Send me a voice message:"
HEAR transcription AS AUDIO
TALK "You said: " + transcription
```

**Process:**
1. Waits for audio attachment
2. Calls BotModels speech-to-text API
3. Returns transcribed text

**Error message:** "Please send an audio file or voice message"

---

### HEAR AS VIDEO

Waits for video upload and describes content.

```basic
TALK "Send a video of the problem:"
HEAR video_description AS VIDEO
TALK "I can see: " + video_description
```

**Process:**
1. Waits for video attachment
2. Calls BotModels vision API to describe
3. Returns AI-generated description

**Error message:** "Please send a video"

---

### HEAR AS FILE / DOCUMENT / DOC / PDF

Waits for document upload.

```basic
TALK "Please upload your contract:"
HEAR contract AS DOCUMENT
TALK "Document received: " + contract
```

**Accepts:** PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV

**Returns:** URL to the uploaded file

---

## Authentication Types

### HEAR AS LOGIN

Waits for Active Directory/OAuth login completion.

```basic
TALK "Please click the link to authenticate:"
HEAR user AS LOGIN
TALK "Welcome, " + user.name + "!"
```

**Process:**
1. Generates authentication URL
2. Waits for OAuth callback
3. Returns user object with tokens

---

## Examples

### Complete Registration Flow

```basic
TALK "Let's create your account!"

TALK "What's your full name?"
HEAR name AS NAME

TALK "Enter your email address:"
HEAR email AS EMAIL

TALK "Enter your CPF:"
HEAR cpf AS CPF

TALK "What's your phone number?"
HEAR phone AS MOBILE

TALK "Choose a password:"
HEAR password AS PASSWORD

TALK "What's your birth date?"
HEAR birthdate AS DATE

TALK "Select your gender:"
HEAR gender AS "Male", "Female", "Other", "Prefer not to say"

' All inputs are now validated and normalized
TALK "Creating account for " + name + "..."

TABLE new_user
    ROW name, email, cpf, phone, birthdate, gender, NOW()
END TABLE
SAVE "users.csv", new_user

TALK "✅ Account created successfully!"
```

### Payment Flow

```basic
TALK "💳 Let's process your payment"

TALK "Enter the amount:"
HEAR amount AS MONEY

IF amount < 1 THEN
    TALK "Minimum payment is R$ 1.00"
    RETURN
END IF

TALK "How would you like to pay?"
HEAR method AS "Credit Card", "Debit Card", "PIX", "Boleto"

IF method = "PIX" THEN
    TALK "Enter the PIX key (phone, email, or CPF):"
    ' Note: We could create HEAR AS PIX_KEY if needed
    HEAR pix_key
ELSEIF method = "Boleto" THEN
    TALK "Enter the barcode (47-48 digits):"
    HEAR barcode AS INTEGER
END IF

TALK "Confirm payment of R$ " + FORMAT(amount, "#,##0.00") + "?"
HEAR confirm AS BOOLEAN

IF confirm THEN
    TALK "✅ Processing payment..."
ELSE
    TALK "Payment cancelled."
END IF
```

### Customer Support with Media

```basic
TALK "How can I help you today?"
HEAR issue AS "Report a bug", "Request feature", "Billing question", "Other"

IF issue = "Report a bug" THEN
    TALK "Please describe the problem:"
    HEAR description
    
    TALK "Can you send a screenshot of the issue?"
    HEAR screenshot AS IMAGE
    
    TALK "Thank you! We've logged your bug report."
    TALK "Reference: BUG-" + FORMAT(NOW(), "yyyyMMddHHmmss")
    
ELSEIF issue = "Billing question" THEN
    TALK "Please upload your invoice or send the transaction ID:"
    HEAR reference
END IF
```

---

## Best Practices

### 1. Always Use Appropriate Types

```basic
' ❌ Bad - no validation
HEAR email
IF NOT email CONTAINS "@" THEN
    TALK "Invalid email"
    ' Need to implement retry logic...
END IF

' ✅ Good - automatic validation and retry
HEAR email AS EMAIL
' Guaranteed to be valid when we get here
```

### 2. Combine with Context

```basic
SET CONTEXT "You are a helpful banking assistant. 
When asking for monetary values, always confirm before processing."

TALK "How much would you like to withdraw?"
HEAR amount AS MONEY
' LLM and validation work together
```

### 3. Use Menu for Limited Options

```basic
' ❌ Bad - open-ended when options are known
HEAR payment_method
IF payment_method <> "credit" AND payment_method <> "debit" THEN
    ' Handle unknown input...
END IF

' ✅ Good - constrained to valid options
HEAR payment_method AS "Credit Card", "Debit Card", "PIX"
```

### 4. Provide Context Before HEAR

```basic
' ❌ Bad - no context
HEAR value AS MONEY

' ✅ Good - user knows what to enter
TALK "Enter the transfer amount (minimum R$ 1.00):"
HEAR amount AS MONEY
```

### 5. Use HEAR AS for Security-Sensitive Data

```basic
' CPF is automatically validated
HEAR cpf AS CPF

' Credit card passes Luhn check and is masked
HEAR card AS CREDITCARD

' Password never echoed back
HEAR password AS PASSWORD
```

---

## Error Handling

Validation errors are handled automatically, but you can customize:

```basic
' The system automatically retries up to 3 times
' After 3 failures, execution continues with empty value

' You can check if validation succeeded:
HEAR email AS EMAIL
IF email = "" THEN
    TALK "Unable to validate email after multiple attempts."
    TALK "Please contact support for assistance."
    RETURN
END IF
```

---

## Metadata Access

Some validation types provide additional metadata:

```basic
HEAR card AS CREDITCARD
' card = "**** **** **** 1234"
' Metadata available: card_type, last_four

HEAR date AS DATE
' date = "2024-12-25"
' Metadata available: original input, parsed format

HEAR audio AS AUDIO
' audio = "transcribed text here"
' Metadata available: language, confidence
```

---

## Integration with BotModels

Media types (QRCODE, AUDIO, VIDEO) automatically call BotModels services:

| Type | BotModels Endpoint | Service |
|------|-------------------|---------|
| QRCODE | `/api/v1/vision/qrcode` | QR Code detection |
| AUDIO | `/api/v1/speech/to-text` | Whisper transcription |
| VIDEO | `/api/v1/vision/describe-video` | BLIP2 video description |
| IMAGE (with question) | `/api/v1/vision/vqa` | Visual Q&A |

Configure BotModels URL in `config.csv`:
```
botmodels-url,http://localhost:8001
botmodels-enabled,true
```

---

## Summary Table

| Type | Example Input | Normalized Output |
|------|---------------|-------------------|
| EMAIL | "User@Example.COM" | "user@example.com" |
| NAME | "john DOE" | "John Doe" |
| INTEGER | "1,234" | 1234 |
| MONEY | "R$ 1.234,56" | "1234.56" |
| DATE | "25/12/2024" | "2024-12-25" |
| HOUR | "2:30 PM" | "14:30" |
| BOOLEAN | "yes" / "sim" | "true" |
| CPF | "12345678909" | "123.456.789-09" |
| MOBILE | "11999998888" | "(11) 99999-8888" |
| CREDITCARD | "4111111111111111" | "4111 **** **** 1111" |
| QRCODE | [image] | "decoded QR data" |
| AUDIO | [audio file] | "transcribed text" |

---

*HEAR AS validation - Making input handling simple, secure, and user-friendly.*