Expression language

Everywhere Ballast asks you for a boolean — the expression on a condition or loop node, or an expression-type check — it evaluates the same tiny language. It is deliberately not Python's eval. The evaluator parses your text into an abstract syntax tree, walks the entire tree and rejects any node type, name, attribute, or call that is not on an explicit allowlist, and only then interprets it against your run state. There is no bytecode, no__builtins__, and no way to reach the host.

How an expression is evaluated

Every expression passes through the same five stages, in order. The first stage to object raises an ExpressionError with a message that is safe to show in a step's output.

The pre-flight walk (stages 3–4) is also exposed on its own: validate_expressionruns everything except stage 5. That is how the builder validates a condition node's expression, and how an expressioncheck is checked before it is stored — a malformed expression is a 400 at save time, not a surprise at run time.

The evaluation scope

An expression sees the run's public state: the original run input, every agent's output_key, every tool result, and any value written by an upstream node. Each is available directly by its key name. The original run input is also available whole under input, and its top-level keys are spread into state as names in their own right.

• score, category, draft_reply— a bare name resolves to that state variable, or raises Unknown variable if it is not present yet
• input — the whole run-input object, so input.get('ticket') works even before any node has run
• state— an alias for the entire variables dictionary, handy when a key name is awkward or you want a .get() with a default

Allowed syntax

The interpreter permits exactly the constructs below. Anything not in this list — comprehensions, lambdas, f-strings, walrus, assignment, starred args, generator expressions — is rejected by the whitelist walk.

Whitelisted builtins

Thirteen builtins are callable by name. Nothing else is — open, eval, getattr, __import__, print, and every other name raises Function 'name' is not allowed.

Whitelisted methods

Method calls are the only form of attribute access allowed, and only for these twenty-two names. The evaluator does not care what type the receiver is — it evaluates the receiver, confirms the method name is whitelisted, and calls it. Calling a method a value does not have (e.g. .upper() on a number) fails the node like any runtime error.

Hard limits

Expressions that pass

Copy-paste patterns. Each assumes the named variables exist in state (from run input, an agent's output_key, or a tool result).

# numeric threshold on an agent's output
int(score) >= 70

# chained comparison — a valid range in one expression
0 <= int(score) <= 100

# category routing, normalized
category.strip().lower() == 'billing'

# substring check on a free-text summary
'unusual' in str(summary).lower()

# inspect a structured tool result
raw_data['status_code'] == 200

# safe access with a default (never raises Unknown variable)
data.get('region', 'unknown') != 'unknown'

# combine conditions
int(score) >= 70 and category != 'spam'

# membership against a literal list
category in ['billing', 'refund', 'chargeback']

# a gate decision recorded by an upstream human gate
approval_review.get('approved') == True

# length + shape guard before trusting a reply
len(draft_reply) > 20 and not draft_reply.isdigit()

# ternary that produces a truthy label, then tests it
('escalate' if int(score) > 90 else '') != ''

# the input alias — available before any node runs
input.get('priority') == 'high'

# the state alias with a default
state.get('retries_left') is not None

# keyword argument on a builtin
sorted(scores, reverse=True)[0] > 90

Expressions that are rejected

Each of these is refused by the whitelist walk before evaluation. The comment shows the exact ExpressionError message.

__import__('os').system('rm -rf /')   # Name '__import__' is not allowed
open('/etc/passwd').read()            # Function 'open' is not allowed
().__class__.__bases__                # Access to '__class__' is not allowed
score.__class__                       # Access to '__class__' is not allowed
reply.format(x=1)                     # Method 'format' is not allowed
data.pop('k')                         # Method 'pop' is not allowed
[x for x in items]                    # Disallowed syntax: ListComp
lambda x: x                           # Disallowed syntax: Lambda
(x := 5)                              # Disallowed syntax: NamedExpr
f"score is {score}"                   # Disallowed syntax: JoinedStr
score = 5                             # Syntax error: … (assignment doesn't parse in eval mode)
2 ** 999                              # Exponent too large
missing_var + 1                       # Unknown variable 'missing_var'

Error messages

Every failure is an ExpressionError. The message surfaces on the failing step (for condition and loop nodes) or in a check's detail as expression error: ….

Condition nodes

A condition node evaluates its expression against public state and coerces the result with bool(...). The engine then follows only the outgoing edges whose branch matches:

• A truthy result follows edges labelled true (an edge's condition_value or, failing that, its label, matched case-insensitively)
• A falsy result follows edges labelled false
• An edge with no condition_value and no label always fires, regardless of the result

The step's output records what happened: { "expression": "…", "result": true }. If a condition has no matching branch for the result it produced — commonly a missing falseedge — the run simply ends at that node. The validate endpoint emits a warning for that case.

{
  "id": "gate_on_score",
  "type": "condition",
  "config": {
    "label": "Score >= 70?",
    "expression": "int(score) >= 70"
  }
}
// edges out of gate_on_score:
//   { "source": "gate_on_score", "target": "auto_reply", "condition_value": "true" }
//   { "source": "gate_on_score", "target": "human_review", "condition_value": "false" }

Loop nodes

A loop node combines the same expression with a hard iteration cap. It continues only when both hold:

keep_going = bool(eval_expression(expression, state)) and iteration <= max_iterations

max_iterations defaults to 5. The engine tracks the iteration count in a hidden state key, __loop_<node_id>, which it increments as each pass begins — so on the first evaluation iteration is 1. Because the counter is prefixed with __, your expression cannot read it directly; write to a normal state variable if you need to reason about progress inside the loop body. When the loop finally stops, the engine clears the counter so a later re-entry starts fresh.

Like a condition, the loop follows true edges (back into the body) while it continues and false edges when it stops. The cap is a guarantee: even a permanently-truthy expression cannot run more than max_iterations times.

{
  "id": "refine",
  "type": "loop",
  "config": {
    "label": "Refine until confident",
    "expression": "float(confidence) < 0.9",
    "max_iterations": 3
  }
}
// continues while confidence < 0.9 AND it has looped 3 times or fewer;
// the 'true' edge re-enters the refinement body, 'false' exits.

Expression checks

The third home for this language is the expression check type on evaluations. The mechanics are identical, with two additions to scope: an expression check also sees cost_usd, duration_ms, and input as names, because a check runs against the finished run rather than a mid-run state. A check that raises records expression error: … as a failed result and never disturbs the run itself.

# the reply must not leak an internal error string
'error' not in draft_reply.lower()

# stay under a per-run budget using the metric names
cost_usd <= 0.05 and duration_ms < 8000

# echo a field from the original input
input.get('locale') == 'en-US'