Data Types and Utilities

This page documents the ABL type system, lookup tables for reference-based validation, and attachment handling for file and media uploads.

Data Types

ABL has a type system used for variable declarations, gather field types, tool parameter signatures, and runtime validation. Types are divided into primitives and complex types.

Primitive types

Primitive types represent single scalar values.

Type	Description	Example values
`string`	Unicode text of arbitrary length.	`"hello"`, `"USD"`, `""`
`number`	IEEE 754 double-precision floating point.	`42`, `3.14`, `-1`, `0`
`boolean`	True or false.	`true`, `false`
`date`	Calendar date without time.	`"2024-03-15"`
`datetime`	Date with time and timezone.	`"2024-03-15T10:30:00Z"`

String

Strings are the most common type in ABL. They are used for text input, identifiers, messages, and any unstructured data.

GATHER:
  customer_name:
    prompt: "What is your name?"
    type: string
    required: true

Number

Numbers represent all numeric values, including integers and floating-point numbers. ABL does not distinguish between integer and float types.

GATHER:
  amount:
    prompt: "How much would you like to transfer?"
    type: number
    required: true
    validate: min(1)

Boolean

Booleans represent true/false values. In conditions, the following values are treated as falsy: false, 0, "", "false", null, undefined, empty arrays, and empty objects. Everything else is truthy.

MEMORY:
  session:
    - customer_verified
      TYPE: boolean
      INITIAL: false

Date

Dates represent calendar dates without a time component. They are stored as ISO 8601 date strings (YYYY-MM-DD).

GATHER:
  departure_date:
    prompt: "When would you like to depart?"
    type: date
    required: true

Datetime

Datetimes include both date and time with timezone information. They are stored as ISO 8601 datetime strings.

MEMORY:
  session:
    - session_start_time
      TYPE: datetime
      INITIAL: NOW()

Complex types

Complex types represent structured or composite values.

array<T>

An ordered collection of elements, optionally typed by item type.

# In type definitions
type: array<string>          # Array of strings
type: array<number>          # Array of numbers
type: array<object>          # Array of objects

In memory declarations:

MEMORY:
  session:
    - cart_items
      TYPE: array
      INITIAL: []

Array type definition (IR)

{ kind: 'array', itemType: TypeDefinition }

Property	Type	Description
`kind`	`'array'`	Discriminant for array type.
`itemType`	`TypeDefinition`	Type of each element in the array.

object `<{...}>`

A structured record with named, typed fields.

# In type definitions
type: object<{name: string, age: number, active: boolean}>

In tool return types:

TOOLS:
  get_user(id: string) -> {name: string, email: string, role: string}

Object type definition (IR)

{ kind: 'object', properties: Record<string, TypeDefinition> }

Property	Type	Description
`kind`	`'object'`	Discriminant for object type.
`properties`	`Record<string, TypeDefinition>`	Map of field names to their types.

enum<[…]>

A constrained set of allowed string values.

GATHER:
  transfer_type:
    prompt: "Is this domestic or international?"
    type: string
    validate: enum(domestic, international)

Enum type definition (IR)

{ kind: 'enum', values: string[] }

Property	Type	Description
`kind`	`'enum'`	Discriminant for enum type.
`values`	`string[]`	Allowed values.

union<[…]>

A value that can be one of several types. Useful for fields that accept different formats.

# In type definitions
type: union<[string, number]>    # Either a string or a number

Union type definition (IR)

{ kind: 'union', types: TypeDefinition[] }

Property	Type	Description
`kind`	`'union'`	Discriminant for union type.
`types`	`TypeDefinition[]`	Possible types for the value.

nullable<T>

Wraps another type to indicate it can also be null.

# In type definitions
type: nullable<string>           # String or null
type: nullable<number>           # Number or null

Nullable type definition (IR)

{ kind: 'nullable', innerType: TypeDefinition }

Property	Type	Description
`kind`	`'nullable'`	Discriminant for nullable type.
`innerType`	`TypeDefinition`	The underlying type that can also be null.

Type definitions in ABL contexts

Variable declarations

In MEMORY: session and persistent variable declarations, use the TYPE property:

MEMORY:
  session:
    - order_total
      TYPE: number
      INITIAL: 0
    - items
      TYPE: array
    - customer_profile
      TYPE: object

Gather fields

Gather fields use the type property with primitive type names:

GATHER:
  name:
    prompt: "What is your name?"
    type: string
    required: true
  age:
    prompt: "How old are you?"
    type: number
    required: true
  departure_date:
    prompt: "When do you depart?"
    type: date
    required: true

Tool parameters

Tool parameters declare types inline in the signature:

TOOLS:
  search_flights(origin: string, destination: string, date: date, passengers: number) -> {flights: {id: string, price: number, departure: datetime}[], total: number}

Supported parameter types:

Type	Description
`string`	Text parameter.
`number`	Numeric parameter.
`boolean`	Boolean parameter.
`date`	Date parameter.
`datetime`	Datetime parameter.
`object`	Structured object.
`string[]`	Array of strings.
`number[]`	Array of numbers.

Tool return types

Tool return types use object literal notation with field names and types:

-> {field1: type1, field2: type2, nested: {sub_field: type3}[]}

The ToolReturn structure supports nested objects and arrays:

Property	Type	Description
`type`	`string`	Type name (`string`, `number`, `object`, etc.).
`fields`	`Record<string, ToolReturn>`	Sub-fields (for `object` type).
`items`	`ToolReturn`	Item type (for array types).
`optional`	`boolean`	Whether this field is optional in the response.

Variable sources

Variables in ABL have a source that indicates their origin:

Source	Description
`system`	Set by the runtime (for example, session ID, timestamp).
`user`	Set by user input (gather fields, direct input).
`agent`	Set by agent logic (SET assignments, tool results).
`computed`	Derived from other variables via expressions.

STATE:
  user:
    language:
      type: string
      source: user
  system:
    session_id:
      type: string
      source: system

Type coercion at runtime

The runtime applies type coercion in these contexts:

Context	Behavior
Comparison	Strings are parsed to numbers for numeric comparisons. Booleans become 0/1.
Assignment	Values are stored as-is. No implicit conversion on write.
Function calls	Math functions coerce string arguments to numbers. String functions coerce null to `""`.
Tool parameters	Values are coerced to match the declared parameter type before sending.
Gather validation	User input is validated and coerced to the declared gather field type.

For detailed coercion rules in expression evaluation, see Expressions & functions — Type coercion rules.

Complete TypeDefinition reference

The full TypeDefinition type is a union of primitive type names and complex type objects:

TypeDefinition =
  | 'string'
  | 'number'
  | 'boolean'
  | 'date'
  | 'datetime'
  | { kind: 'array', itemType: TypeDefinition }
  | { kind: 'object', properties: Record<string, TypeDefinition> }
  | { kind: 'enum', values: string[] }
  | { kind: 'union', types: TypeDefinition[] }
  | { kind: 'nullable', innerType: TypeDefinition }

TypeDefinition is the structural type algebra used for MEMORY: variables and tool signatures. GATHER fields and ENTITIES: entries use a broader entity type set that additionally includes text, free_text, integer, float, currency, email, phone, enum, pattern, and location. Those extra type names are not part of TypeDefinition.

Lookup Tables

Lookup tables provide reference-based validation for gather fields and expressions. They define sets of valid values that the runtime uses to validate user input, suggest corrections, and perform fuzzy matching. The LOOKUP_TABLES: block declares named tables with their data source and matching configuration.

Overview

ABL supports three lookup table sources:

Inline — static values defined directly in the ABL file.
Collection — values stored in a tenant-scoped database collection.
API — values fetched from an external HTTP endpoint.

LOOKUP_TABLES:
  airport_codes:
    source: inline
    values: [JFK, LAX, ORD, SFO, MIA, ATL, DFW, SEA]
    case_sensitive: false
    fuzzy_match: true
    fuzzy_threshold: 0.85

  hotel_chains:
    source: collection
    table_name: "hotel_chains"
    field: "name"
    case_sensitive: false
    fuzzy_match: true
    fuzzy_threshold: 0.8

  currency_codes:
    source: api
    endpoint: "https://api.reference.com/v1/currencies"
    field: "code"
    timeout_ms: 5000
    case_sensitive: true
    fuzzy_match: false

Inline lookup tables

Inline tables define their values directly in the ABL file. Use them for small, stable reference sets.

Syntax

LOOKUP_TABLES:
  transfer_types:
    source: inline
    values: [domestic, international]
    case_sensitive: false
    fuzzy_match: false

When to use inline tables

The value set is small (fewer than ~100 entries).
The values rarely change.
No external dependency is acceptable.

Collection lookup tables

Collection tables read values from a tenant-scoped database collection. The platform resolves the table_name to the correct storage location based on the current tenant.

Syntax

LOOKUP_TABLES:
  product_catalog:
    source: collection
    table_name: "products"
    field: "product_name"
    case_sensitive: false
    fuzzy_match: true
    fuzzy_threshold: 0.85

When to use collection tables

The value set is large or changes frequently.
Values are managed through an admin interface or data pipeline.
Different tenants have different valid values.

API lookup tables

API tables fetch values from an external HTTP endpoint at runtime. The response is expected to contain an array of objects; the field property specifies which object field to match against.

Syntax

LOOKUP_TABLES:
  exchange_rates:
    source: api
    endpoint: "https://api.rates.example.com/v1/currencies"
    field: "currency_code"
    timeout_ms: 3000
    case_sensitive: true
    fuzzy_match: false

When to use API tables

Values come from a third-party system that maintains its own data.
Real-time accuracy is important (for example, live exchange rates, inventory).
The dataset is too large to store locally.

Lookup table properties

Property	Type	Required	Default	Description
`source`	`string`	Yes	`inline`	Data source type: `inline`, `collection`, or `api`. Legacy aliases: `mongodb` → `collection`, `http` → `api`.
`values`	`string[]`	No	—	Static values (required for `source: inline`).
`map`	`Record<string,string>`	No	—	Inline key → value mapping (an alternative to `values`; keys become the valid values).
`table_name`	`string`	No	—	Logical table name (required for `source: collection`). Alias: `collection`.
`endpoint`	`string`	No	—	HTTP endpoint URL (required for `source: api`).
`field`	`string`	No	—	Field within the data source to match against.
`headers`	`Record<string,string>`	No	—	Custom HTTP headers for `source: api` (for example, an `Authorization` header).
`timeout_ms`	`number`	No	`5000`	Request timeout in milliseconds (for `source: api`).
`case_sensitive`	`boolean`	No	`false`	Whether matching is case-sensitive.
`fuzzy_match`	`boolean`	No	`false`	Whether fuzzy (approximate) matching is enabled.
`fuzzy_threshold`	`number`	No	`0.85`	Minimum similarity score (0.0—1.0) for fuzzy matches to be accepted.

Table names must match ^[a-z_][a-z0-9_]*$ and field names ^[a-zA-Z_][a-zA-Z0-9_.]*$. A small inline map table can also be written in shorthand: my_table: { key1: value1, key2: value2 }.

Fuzzy matching

When fuzzy_match: true, the runtime uses string similarity algorithms to find the closest match when an exact match is not found. This handles typos, abbreviations, and minor variations.

Similarity threshold

The fuzzy_threshold controls how similar a user’s input must be to a valid value for the match to be accepted:

Threshold	Behavior
`0.95`	Very strict. Only near-exact matches accepted.
`0.85`	Default. Tolerates minor typos and abbreviations.
`0.75`	Lenient. Accepts more variation but increases false positive risk.
`0.50`	Very lenient. Useful for short strings where small edits are significant.

Example: fuzzy matching for airport codes

LOOKUP_TABLES:
  airports:
    source: inline
    values: [JFK, LAX, ORD, SFO, MIA, ATL, DFW, SEA]
    case_sensitive: false
    fuzzy_match: true
    fuzzy_threshold: 0.8

With this configuration:

"jfk" matches JFK (case-insensitive exact match).
"SFP" matches SFO (fuzzy match, 1 character difference).
"XYZ" doesn’t match any value (below threshold).

Field mapping

The field property specifies which field in the data source to match with. For collection and API sources, the data is typically an array of objects. The field tells the runtime which property to compare:

# Given API response: [{"code": "USD", "name": "US Dollar"}, {"code": "EUR", "name": "Euro"}]
LOOKUP_TABLES:
  currencies:
    source: api
    endpoint: "https://api.reference.com/v1/currencies"
    field: "code"
    case_sensitive: true
    fuzzy_match: false

User input is matched with the code field of each object in the response.

Using lookup tables

A GATHER field references a lookup table through its semantics.lookup metadata, which names the table used to validate and normalize the collected value (applying the table’s case-sensitivity, fuzzy matching, and threshold):

GATHER:
  destination_airport:
    prompt: "What's your destination airport code?"
    type: string
    required: true
    semantics:
      lookup: airports

Tool parameters can source a value from a lookup table via SOURCE: lookup(<table>) in a .tools.abl parameter block (see Tools); this resolves to a {{lookup:<table>:<key>}} value at runtime.

Timeout and error handling

For API-sourced tables, specify a timeout_ms to control how long the runtime waits for the external service:

LOOKUP_TABLES:
  products:
    source: api
    endpoint: "https://catalog.internal/api/v1/products"
    field: "sku"
    timeout_ms: 3000
    case_sensitive: true
    fuzzy_match: false

If the API call times out or returns an error, the runtime:

Logs a warning.
Falls back to accepting the user’s input without validation.
Emits a trace event indicating the lookup failure.

Attachments

Attachments define file and media upload fields that the agent collects from the user. The ATTACHMENTS: block declares named attachment fields with their content category, processing options, and validation constraints. Attachments work alongside GATHER fields to collect structured data through conversation.

Overview

ABL supports four attachment categories, each with specialized processing capabilities:

Category	Use cases	Processing features
`document`	PDFs, Word docs, spreadsheets, text files	OCR, text extraction
`image`	Photos, screenshots, scanned documents	OCR, image analysis
`audio`	Voice recordings, audio messages	Transcription
`video`	Screen recordings, instructional clips	Keyframe extraction, transcription

ATTACHMENTS:
  id_document:
    prompt: "Please upload a photo of your government-issued ID."
    category: image
    required: true
    max_file_size_mb: 10
    allowed_types: [image/jpeg, image/png, image/webp]
    ocr_enabled: true

  supporting_docs:
    prompt: "Upload any supporting documents (invoices, contracts, etc.)."
    category: document
    required: false
    max_file_size_mb: 25
    allowed_types: [application/pdf, image/jpeg, image/png]
    ocr_enabled: true

Attachment field properties

Property	Type	Required	Default	Description
`name`	`string`	Yes	—	Unique identifier for the attachment field (the YAML key).
`prompt`	`string`	Yes	—	Message displayed to the user when requesting the upload.
`category`	`string`	No	`document`	Content category: `document`, `image`, `audio`, or `video`.
`required`	`boolean`	No	`true`	Whether the attachment is mandatory.
`max_file_size_mb`	`number`	No	—	Maximum file size in megabytes. Alias: `max_size_mb`.
`allowed_types`	`string[]`	No	—	Allowed MIME types. If omitted, all types for the category are accepted.
`ocr_enabled`	`boolean`	No	`false`	Enable OCR text extraction for `document` and `image` categories.
`transcription_enabled`	`boolean`	No	`false`	Enable audio transcription for `audio` and `video` categories. Alias: `transcription`.
`key_frame_extraction`	`boolean`	No	`false`	Enable keyframe extraction for `video` category.

The DSL keyword for the MIME allowlist is allowed_types (it populates the field’s allowed MIME types). allowed_mime_types is not recognized by the .agent.abl parser.

Document attachments

Document attachments handle file uploads such as PDFs, Word documents, spreadsheets, and plain text files. When OCR is enabled, the runtime extracts text content from the uploaded document and makes it available in the session context.

ATTACHMENTS:
  bank_statement:
    prompt: "Please upload your most recent bank statement."
    category: document
    required: true
    max_file_size_mb: 25
    allowed_types: [application/pdf]
    ocr_enabled: true

Common document MIME types

MIME type	Description
`application/pdf`	PDF documents
`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	Word (.docx)
`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	Excel (.xlsx)
`text/plain`	Plain text
`text/csv`	CSV files

Image attachments

Image attachments handle photo and screenshot uploads. OCR extracts text from images (useful for scanned documents, receipts, and ID cards).

ATTACHMENTS:
  receipt_photo:
    prompt: "Take a photo of your receipt or upload an image."
    category: image
    required: true
    max_file_size_mb: 10
    allowed_types: [image/jpeg, image/png, image/webp, image/heic]
    ocr_enabled: true

Common image MIME types

MIME type	Description
`image/jpeg`	JPEG images
`image/png`	PNG images
`image/webp`	WebP images
`image/heic`	HEIC images (iOS)
`image/gif`	GIF images
`image/tiff`	TIFF images

Audio attachments

Audio attachments handle voice recordings and audio messages. When transcription is enabled, the runtime converts the audio to text.

ATTACHMENTS:
  voice_message:
    prompt: "Record or upload a voice message describing the issue."
    category: audio
    required: false
    max_file_size_mb: 50
    allowed_types: [audio/mpeg, audio/wav, audio/ogg, audio/webm]
    transcription_enabled: true

Common audio MIME types

MIME type	Description
`audio/mpeg`	MP3 files
`audio/wav`	WAV files
`audio/ogg`	OGG audio
`audio/webm`	WebM audio
`audio/mp4`	AAC/M4A files

Video attachments

Video attachments handle video file uploads. Two processing features are available:

Transcription extracts speech from the video’s audio track.
Keyframe extraction captures representative frames from the video for visual analysis.

ATTACHMENTS:
  screen_recording:
    prompt: "Upload a screen recording showing the issue."
    category: video
    required: false
    max_file_size_mb: 100
    allowed_types: [video/mp4, video/webm, video/quicktime]
    transcription_enabled: true
    key_frame_extraction: true

Common video MIME types

MIME type	Description
`video/mp4`	MP4 video
`video/webm`	WebM video
`video/quicktime`	QuickTime (MOV)

OCR processing

When ocr_enabled: true, the runtime processes uploaded documents and images through an OCR pipeline that:

Detects text regions in the file.
Extracts text content.
Stores the extracted text in the session context under the attachment field name.

The extracted text is accessible in expressions and template strings:

# After OCR, the text is available as the attachment field name
SET:
  id_text = id_document.extracted_text

Transcription processing

When transcription_enabled: true, the runtime processes audio and video files through a transcription pipeline:

Extracts the audio track (for video files).
Runs speech-to-text transcription.
Stores the transcript in the session context.

SET:
  message_text = voice_message.transcript

Keyframe extraction

When key_frame_extraction: true, the runtime extracts representative frames from video files:

Analyzes the video for scene changes.
Captures keyframes at scene boundaries.
Stores the keyframes as an array of image references.

SET:
  frames = screen_recording.keyframes

File size and MIME type validation

The runtime validates uploaded files against the declared constraints before processing:

If the file exceeds max_file_size_mb, the upload is rejected with an error message.
If the file’s MIME type is not in allowed_types, the upload is rejected.
If allowed_types is omitted, all standard MIME types for the category are accepted.

Complete attachment example

ATTACHMENTS:
  government_id:
    prompt: "Please upload a clear photo of your government-issued ID (passport, driver's license, or national ID card)."
    category: image
    required: true
    max_file_size_mb: 10
    allowed_types: [image/jpeg, image/png, image/webp]
    ocr_enabled: true

  proof_of_address:
    prompt: "Upload a utility bill or bank statement from the last 3 months as proof of address."
    category: document
    required: true
    max_file_size_mb: 25
    allowed_types: [application/pdf, image/jpeg, image/png]
    ocr_enabled: true

  voice_authorization:
    prompt: "Record a voice message stating: 'I authorize this wire transfer of {{amount}} {{currency}} to {{beneficiary_name}}.'"
    category: audio
    required: false
    max_file_size_mb: 10
    allowed_types: [audio/mpeg, audio/wav, audio/webm]
    transcription_enabled: true

Expressions & functions — type coercion in expressions and built-in type-checking functions
Memory & Constraints — TYPE declarations in session and persistent variables, attachment data in session
GATHER — gather field types and lookup-based validation
NLU — entity extraction that may reference lookup tables

​Data Types

​Primitive types

​String

​Number

​Boolean

​Date

​Datetime

​Complex types

​array<T>

Array type definition (IR)

​object <{...}>

Object type definition (IR)

​enum<[…]>

Enum type definition (IR)

​union<[…]>

Union type definition (IR)

​nullable<T>

Nullable type definition (IR)

​Type definitions in ABL contexts

​Variable declarations

​Gather fields

​Tool parameters

​Tool return types

​Variable sources

​Type coercion at runtime

​Complete TypeDefinition reference

​Lookup Tables

​Overview

​Inline lookup tables

​Syntax

​When to use inline tables

​Collection lookup tables

​Syntax

​When to use collection tables

​API lookup tables

​Syntax

​When to use API tables

​Lookup table properties

​Fuzzy matching

​Similarity threshold

​Example: fuzzy matching for airport codes

​Field mapping

​Using lookup tables

​Timeout and error handling

​Attachments

​Overview

​Attachment field properties

​Document attachments

​Common document MIME types

​Image attachments

​Common image MIME types

​Audio attachments

​Common audio MIME types

​Video attachments

​Common video MIME types

​OCR processing

​Transcription processing

​Keyframe extraction

​File size and MIME type validation

​Complete attachment example

​Related pages

Data Types

Primitive types

String

Number

Boolean

Date

Datetime

Complex types

array<T>

object `<{...}>`

enum<[…]>

union<[…]>

nullable<T>

Type definitions in ABL contexts

Variable declarations

Gather fields

Tool parameters

Tool return types

Variable sources

Type coercion at runtime

Complete TypeDefinition reference

Lookup Tables

Overview

Inline lookup tables

Syntax

When to use inline tables

Collection lookup tables

Syntax

When to use collection tables

API lookup tables

Syntax

When to use API tables

Lookup table properties

Fuzzy matching

Similarity threshold

Example: fuzzy matching for airport codes

Field mapping

Using lookup tables

Timeout and error handling

Attachments

Overview

Attachment field properties

Document attachments

Common document MIME types

Image attachments

Common image MIME types

Audio attachments

Common audio MIME types

Video attachments

Common video MIME types

OCR processing

Transcription processing

Keyframe extraction

File size and MIME type validation

Complete attachment example

Related pages