Z-Script overview
Say it in words first
Z-Script lets you add small rules to your assistant: tidy a name before deciding, flag a large amount, check whether a message mentions a refund. You do not need to be a programmer. Every script is a sentence you would say anyway, written in a slightly stricter shape.
The one rule to learn: each instruction sits inside round brackets, and the action word comes first.
- In words: make it lowercase. As a script:
(lower it) - In words: get the name from the input. As a script:
(get input :name)
When instructions are put inside each other, read from the inside out, the way you would follow a recipe: the innermost bracket happens first.
(trim (lower (get input :name))) reads as: get the name, then make it lowercase, then remove the spaces at the ends.
Sentences and their scripts
Each script below was run on the engine; the output column is what it returned.
| You would say | Script | Input | Output |
|---|
| Make the name lowercase | (lower (get input :name)) | {"name": "MUHAMMAD AHMED"} | "muhammad ahmed" |
| ...and remove spaces at the ends | (trim (lower (get input :name))) | {"name": " MUHAMMAD AHMED "} | "muhammad ahmed" |
| Is the word refund in the message? | (contains? (lower (get input :message)) "refund") | {"message": "I want a REFUND for order 42"} | true |
| If the amount is over 500, say needs-approval, otherwise ok | (if (> (get input :amount) 500) "needs-approval" "ok") | {"amount": 750} | "needs-approval" |
| Join first and last name with a space | (str (get input :first) " " (get input :last)) | {"first": "Sara", "last": "Khan"} | "Sara Khan" |
| How many items are in the cart? | (len (get input :items)) | {"items": ["pen", "book", "bag"]} | 3 |
A few words you will use most: get (take a value from the input), lower / upper (change letter case), trim (remove outer spaces), contains? (is this text inside that one?), if (choose between two results), str (put text together), len (how many). The full list is in built-ins.
Why it is safe to let anyone write rules
- A script can only use the values you pass in. It cannot reach your database, files or the internet.
- Every script is checked before it runs: a misspelled word or a missing bracket is reported with its position, and nothing runs.
- Every run has a budget (called fuel), so a mistake can never run forever. The same script on the same input always stops at the same step with the same answer.
In the Studio, the Scripts page has a Visual Blocks view, so you can build the same rules by arranging blocks instead of typing brackets.
Check and run a script
curl -sS http://127.0.0.1:8700/v1/scripts/check \
-H 'Content-Type: application/json' \
-d '{"script":"(trim (lower input))"}'
curl -sS http://127.0.0.1:8700/v1/scripts/run \
-H 'Content-Type: application/json' \
-d '{"script":"(trim (lower input))","input":" Example ","fuel":1000}'
Fuel is an execution budget. A successful script result does not make a security policy correct or authorize an application action. Attach scripts only at request hooks supported by the endpoint and SDK you use.