Predicator

Predicator is a secure, non-evaluative condition engine for end-user boolean predicates. A user-authored expression like score > 85 AND active compiles to a flat instruction list run by a small stack VM - there is no eval, no Code.eval_string, and no dynamic code execution anywhere in the pipeline, so untrusted input can never become code.

The language covers comparisons, arithmetic, logical operators, dates and durations, lists and objects, nested data access, and both builtin and custom functions.

Installation

Add predicator to your list of dependencies in mix.exs:

def deps do
  [
    {:predicator, "~> 3.8"}
  ]
end

Predicator requires Elixir 1.18 or later and has no runtime dependencies.

Quick Start

iex> Predicator.evaluate!("score > 85 AND active", %{"score" => 92, "active" => true})
true

iex> {:ok, instructions} = Predicator.compile("score > threshold")
iex> Predicator.evaluate!(instructions, %{"score" => 95, "threshold" => 80})
true

iex> Predicator.evaluate("score > 85", %{"score" => 92})
{:ok, true}

Documentation

• Language reference - operators, builtin functions, data types, and error shapes
• ISA reference - the instruction set specification: opcodes, stack effects, error semantics, and versioning
• Nested data access - dot and bracket notation over deep contexts
• Custom functions - extending the function set per evaluation
• Location expressions - SCXML assignment targets and writing into a context
• Architecture and language reference - the grammar with precedence, the compilation pipeline, and the component map
• Architecture decision records - the reasoning behind the design

Migrating from =

Using = for equality still works but is deprecated: parsing one now emits a warning, and Predicator 4.0 makes expression-position = a parse error - = is reserved for assignment in the forthcoming statement grammar. Migrate to == before upgrading, or silence the warning with config :predicator, deprecation_warnings: false. See ADR-0002 for the reasoning.

Cross-Language Siblings

Predicator's Elixir implementation is the reference implementation of the instruction set (the ISA), which is versioned. Ruby and JavaScript siblings, in the riddler/predicator monorepo, adopt each ISA version on their own schedule; a sibling running behind the current version is an expected, documented state, not a defect. See ADR-0003 for the reasoning and docs/architecture.md for what each sibling currently supports. docs/isa.md is the specification a sibling implements against.

Development

See CLAUDE.md for the contributor workflow and docs/architecture.md for the quality-check commands.

License

MIT - see LICENSE.