Documentation Index
Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
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 three namespaces of variables:| Namespace | Source | Example | When Available |
|---|---|---|---|
fieldName | Other custom field values on the offer | base_rate, offer_price | Always — values come from the offer’s custom fields |
customer.* | Enriched data from schema tables via the Enrich stage | customer.loan_amount, customer.balance | When an Enrich stage is configured in the Decision Flow |
attributes.* | Request-time attributes from the Recommend API body | attributes.tier, attributes.channel | When the caller passes attributes in the Recommend request |
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
| Operator | Description | Example | Precedence |
|---|---|---|---|
+ | Addition (numbers) or concatenation (strings) | base_rate + 1.5 | 4 |
- | Subtraction | price - discount | 4 |
* | Multiplication | quantity * unit_price | 5 |
/ | Division (returns null on divide by zero) | total / count | 5 |
% | Modulo (returns null on mod by zero) | index % 3 | 5 |
- (unary) | Negation | -score | 6 |
Comparison Operators
All comparison operators return1 for true and 0 for false. String comparisons support only == and !=.
| Operator | Description | Example | Precedence |
|---|---|---|---|
> | Greater than | customer.age > 18 | 3 |
< | Less than | customer.score < 50 | 3 |
>= | Greater than or equal | customer.age >= 21 | 3 |
<= | Less than or equal | balance <= 0 | 3 |
== | Equal (numbers or strings) | attributes.tier == "gold" | 3 |
!= | Not equal (numbers or strings) | customer.status != "inactive" | 3 |
Precedence Summary (highest to lowest)
| Level | Operators |
|---|---|
| 6 | Unary - |
| 5 | *, /, % |
| 4 | +, - |
| 3 | >, <, >=, <=, ==, != |
| 1 | ? : (ternary) |
() override default precedence.
Functions
The engine includes six built-in functions:| Function | Signature | Description | Example | Return Type |
|---|---|---|---|---|
min | min(a, b) | Returns the smaller of two numbers | min(customer.rate, 25.0) | number |
max | max(a, b) | Returns the larger of two numbers | max(customer.score, 0) | number |
round | round(value) or round(value, decimals) | Rounds to nearest integer, or to N decimal places | round(total * 0.0825, 2) | number |
abs | abs(value) | Returns the absolute value | abs(customer.balance) | number |
coalesce | coalesce(a, b, ...) | Returns the first non-null argument (minimum 2 args) | coalesce(customer.rate, base_rate, 5.0) | number or string |
concat | concat(a, b, ...) | Joins all arguments as strings (minimum 2 args) | concat("Hello ", customer.name) | string |
Unknown function names return
null. Functions 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 API validation (CreateCategorySchema) enforces that every computed field specifies both a formula and a valid outputType.
Error Handling
The formula engine is designed to fail gracefully. Every error condition returnsnull rather than throwing:
| Condition | Behavior |
|---|---|
Division by zero (10 / 0) | Returns null |
Modulo by zero (10 % 0) | Returns null |
| Missing or undefined variable | Returns null (use coalesce to provide a default) |
null variable value | Returns null (null propagates through all operations) |
| Syntax error or unparseable formula | Returns null |
| Mismatched parentheses | Returns null |
| Empty formula | Returns null |
| Unknown function name | Returns null |
| Wrong argument count for a function | Returns null |
| Type mismatch (e.g., arithmetic on strings) | Returns null |
| Unterminated string literal | Returns null |
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 for computed fields. Clicking it runsvalidateFormula() which tokenizes and parses the formula, returning either { valid: true } or { valid: false, error: "..." } with a descriptive error message.
API Validation
TheCreateCategorySchema and UpdateCategorySchema Zod schemas include .superRefine() logic that validates computed fields on every API call:
- Every field with
type: "computed"must have a non-emptyformulastring - Every computed field must have an
outputTypeof either"number"or"text"
400 response.
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