How Formulas Work
KaireonAI includes a safe, sandboxed formula engine for computing personalized values at decision time. The engine follows a strict pipeline:- Tokenizer — Breaks the formula string into tokens (numbers, strings, identifiers, operators, punctuation)
- Parser — Recursive-descent parser builds an Abstract Syntax Tree (AST) from the token stream
- Evaluator — Walks the AST and computes the result structurally
eval, Function, or vm — all evaluation is structural, making it safe by design. Any formula that fails to parse or evaluate returns null rather than throwing an error.
Formulas are defined on computed custom fields within Categories. At decision time, the Recommend API evaluates each formula per candidate offer and merges the results into the response.
Variable Namespaces
Formulas can reference offer custom fields plus every namespace of the canonical decision context, which the engine assembles automatically at decision time (no Enrich node required — the Enrich node is an override):
Variables are resolved as a flat key-value map. Dot notation (e.g.,
customer.loan_amount) is part of the identifier — the engine treats customer.loan_amount as a single variable name, not an object property access.
Operators
Arithmetic Operators
Comparison Operators
All comparison operators return1 for true and 0 for false. String comparisons support only == and !=.
Precedence Summary (highest to lowest)
Parentheses
() override default precedence.
Functions
The engine includes 19 built-in functions, grouped below. Each argument is evaluated first; if any argument isnull, the function returns null.
Numeric
min(a, b) — the smaller of two numbers. min(customer.rate, 25.0)
max(a, b) — the larger of two numbers. max(customer.score, 0)
round(value) / round(value, decimals) — rounds to the nearest integer, or to N decimal places when a second argument is supplied. round(total * 0.0825, 2)
abs(value) — absolute value. abs(customer.balance)
Logic
if(condition, valueIfTrue, valueIfFalse) — returns one of two values based on the condition (a functional alternative to the ? : operator). if(customer.age >= 21, "eligible", "ineligible")
Null handling
coalesce(a, b, ...) — returns the first non-null argument (minimum two arguments). Result type matches the first non-null value. coalesce(customer.rate, base_rate, 5.0)
String
concat(a, b, ...) — joins all arguments as strings (minimum two arguments). concat("Hello ", customer.name)
upper(s) / lower(s) — upper- or lower-cases a string. upper(customer.state)
trim(s) — removes leading and trailing whitespace. trim(customer.name)
replace(s, find, replacement) — replaces every occurrence of find. replace(customer.phone, "-", "")
left(s, n) / right(s, n) — the first / last n characters. left(customer.zip, 3)
substring(s, start, length) — a substring of length characters from start (0-based). substring(customer.id, 0, 4)
Type & utility
cast(value, type) — converts value to "float", "integer", "string", or "boolean". cast(attributes.qty, "integer")
mask(s, pattern) — masks a string, keeping the last N characters where the pattern contains {N}. mask(customer.card, "****{4}") → ****1234
hash(s, algorithm) — hex digest using "sha256", "sha512", or "md5". hash(customer.email, "sha256")
now() — the current time as an ISO-8601 string.
date_format(value, format) — formats a date/timestamp using YYYY, MM, DD, HH, mm, ss tokens (UTC). date_format(customer.joined_at, "YYYY-MM-DD")
String functions require string arguments and numeric functions require numeric
arguments — a type mismatch returns
null. Unknown function names, and functions
called with the wrong number of arguments, also return null.Ternary Expressions
Ternary expressions provide conditional logic:0, "", or null is falsy.
null, the entire ternary returns null.
Type Coercion
Computed fields declare anoutputType of either number or text. This is a metadata hint used for validation and display — the formula engine itself returns whatever type the expression produces:
- Arithmetic operations return numbers
- String operations (
+on two strings,concat) return strings - Comparison operators always return
1or0(numbers) coalescereturns the type of the first non-null argument
outputType that matches your formula’s expected result. The Categories API rejects any computed field that omits either a formula string or an outputType of number or text.
Error Handling
The formula engine is designed to fail gracefully. Every error condition returnsnull rather than throwing:
Null propagation rule: If any operand in a binary operation is
null, the entire operation returns null. This means 5 + null is null, not 5. Use coalesce to guard against missing values.
Real-World Formulas
Simple arithmetic
base_rate custom field.
Customer data lookup
Request-time conditional
Fallback with coalesce
String personalization
Rounded calculation
Conditional discount
Clamping with min/max
Multi-variable calculation
Channel-aware text
Tiered pricing with nested ternary
Scoring with null safety
Validation
UI Validation
The Business Hierarchy page (Category editor) includes a Validate button next to each computed field. Clicking it parses the formula in place and returns either a green check or a red error message describing exactly what failed (unbalanced parentheses, unknown function, missing operand, and so on), so authors can fix mistakes before saving.API Validation
The Categories API enforces the same rules on every create and update request:- Every field with
type: "computed"must have a non-emptyformulastring - Every computed field must have an
outputTypeof either"number"or"text"
400 Bad Request and a validation error describing which field failed.
Related
Business Hierarchy
Define Categories with computed custom fields
Decision Flows
Configure Enrich and Compute stages in flows
Composable Pipeline
V2 pipeline architecture with compute nodes