Skip to main content

Getting Started

This walkthrough uses the clothing purchase example to show the normal compile -> eval workflow, with an optional print step for inspecting the compiled bytecode.

Files used in this guide:

  • examples/clothing_purchase.template
  • examples/clothing_purchase.intent.json
  • examples/clothing_purchase.evidence.json

Before you begin:

  • Install the released policy-engine binary.
  • Make sure policy-engine is on your PATH.
  • Run the commands from the directory that contains this guide, or adjust the example paths.

Policy template​

A policy template separates a policy decision into three parts. Consider a clothing purchase example:

  • intent describes what the buyer allows or wants: acceptable categories, optional color and brand preferences, size, budget, etc.
  • evidence describes the concrete listing being evaluated: its category, color, brand, size, price, etc.
  • requires contains the checks that must pass, such as "the listing price must be within budget."

The policy passes only when the evidence satisfies every required check. Checks can also be optional, which means they are applied only when the corresponding optional intent field is present.

1. Compile a template​

Compile the source template into bytecode:

policy-engine compile examples/clothing_purchase.template \
  --out clothing_purchase.bin

Example output:

policy_template_id=4Bh9qrxKWLfPEUFs6hKqtzL75dPQyj9hSLHmDr8wqDap

The policy_template_id is the base58-encoded SHA-256 hash of the compiled bytecode. Because bytecode generation is deterministic, the same template always produces the same ID; any source change that alters the compiled policy yields a different ID.

Whitespace, comments, schema field order, and set literal element order do not define the policy. Changing a constraint, field, template name, literal value, or schema shape does.

The --out flag chooses where the compiled bytecode is written. If you omit it, policy-engine writes out.bin in the current directory.

2. Inspect the compiled template​

Print the compiled bytecode back into a readable template form:

policy-engine print clothing_purchase.bin

Example output:

name clothing_purchase_guard

intent {
  acceptable_brands: optional set<string>
  acceptable_categories: set<string>
  acceptable_colors: optional set<string>
  audience: string
  max_price_cents: int
  size: string
}

evidence {
  audience: string
  brand: string
  category: string
  color: string
  price_cents: int
  size: string
}

requires {
  evidence.category in intent.acceptable_categories;
  evidence.size == intent.size;
  evidence.audience in {"men", "unisex", "women"};
  evidence.audience == intent.audience;
  evidence.price_cents <= intent.max_price_cents;
  optional: evidence.color in intent.acceptable_colors;
  optional: evidence.brand in intent.acceptable_brands;
}

print is useful for inspecting what was actually compiled. Its output is a readable representation of the compiled template, not a byte-for-byte copy of your original source file.

In practice that means:

  • comments are not preserved
  • field order may differ from the original source
  • set literals may appear in sorted order
  • formatting may differ from what you originally wrote

Treat print as an inspection tool for the compiled policy, not as a promise about the exact formatting of your original source.

3. Evaluate the policy​

Evaluate the compiled template against JSON files containing intent and evidence:

policy-engine eval clothing_purchase.bin \
  --intent examples/clothing_purchase.intent.json \
  --evidence examples/clothing_purchase.evidence.json

Example output:

decision=pass

decision=pass means every constraint in the template was satisfied.

If you want to make sure you are evaluating the compiled template you expect, pass the template ID back into eval:

policy-engine eval clothing_purchase.bin \
  --intent examples/clothing_purchase.intent.json \
  --evidence examples/clothing_purchase.evidence.json \
  --check-id 4Bh9qrxKWLfPEUFs6hKqtzL75dPQyj9hSLHmDr8wqDap

4. What the JSON files contain​

The template defines an intent schema and an evidence schema. The CLI reads values for those schemas from JSON files.

Both files are JSON objects. Their fields and values must match the corresponding schema in the template.

For this example, the intent file contains:

{
  "acceptable_categories": ["t-shirt", "polo"],
  "acceptable_colors": ["black", "navy", "white"],
  "acceptable_brands": ["Uniqlo", "Hanes", "Lacoste"],
  "size": "M",
  "audience": "men",
  "max_price_cents": 2500
}

and the evidence file contains:

{
  "category": "t-shirt",
  "color": "navy",
  "brand": "Uniqlo",
  "size": "M",
  "audience": "men",
  "price_cents": 1999
}

For JSON encoding rules, see CLI Reference. For the runtime input model, see Language Reference.

Troubleshooting​

policy-engine: command not found

Make sure the released binary is installed and that the directory containing policy-engine is on your PATH.

failed to read ...

Check that the file path exists and that you are running the commands from the directory containing this guide, or switch to absolute paths.

input validation error: ...

Your JSON file does not match the template's intent or evidence schema. Check the field names, JSON types, required keys, and date formats.

decision=fail

The template compiled and the inputs were readable, but one or more policy constraints did not pass. Use the output lines from eval to see which constraint failed.

template ID mismatch: ...

The bytecode file you are evaluating does not match the template ID you passed to --check-id.

Next steps​