Why reflexes.

Typing what you want is easy. Trusting what runs is the hard part.

Everyone wants to type what they mean and have the computer do it. What nobody gives you is a reason to trust what runs. An action taken on a guess costs more than one that never ran. Trust needs three things.

• Every value comes from you. From what you typed, or from a list you own.
• The confidence is shown. Every answer carries a probability, so you can set a bar on it.
• What cannot be undone asks first. Every time, whatever the number.

Reflexes are built for exactly these three. If you answer for what an automation did, you already know why. The rest of this page shows how. Every terminal line on this page is one that evoke printed in its test suite. There, a file of written answers stands in for the classifier. Most reflexes in these sessions are stand-ins kept for the tests, such as lights. They print a line, change nothing, and cannot be installed.

Your words pick a program. They never write one.

A reflex's manifest says, in plain words, what its program does and which inputs it takes. A classifier reads your sentence: Jev, TypeSafe AI's model. It answers three kinds of closed question, and gives every answer a probability.

1. 01Which reflex?One of the installed reflexes, or none of them.
2. 02Which values?An option the author listed, one of your own words, or a piece of the sentence, checked against its range.
3. 03Is that all you said?The call is read back against your sentence. When it leaves part of it out, the call waits for your yes.

Every answer is a choice among things that already exist. So evoke guarantees that every value is one the reflex allows. It cannot guarantee that it read you right. That is why a bar, set by what the program changes, decides what runs without a question.

How your sentence fills a reflex → Why a sentence picks and never writes →

A number beside every answer, and a bar for each effect.

The classifier's provider trains its probabilities to be calibrated: across many answers, those given 0.85 should be right about 85 times in 100. evoke shows every one, and evoke test checks your own sentences. The weakest answer is the decision's confidence. A reflex that reads runs at 0.8 or above, one that writes at 0.9, and one that cannot be undone always asks.

$ evoke try "kill the lights"
  which reflex            lights 0.95   (none of them 0.03 · timer 0.01)
  room                    not said 0.87   (den 0.10 · office 0.03)
  state                   off 0.74   (on 0.19 · dim 0.06)
  → asks: lights state="off" room=?
$ evoke try "kill the lights in the den"
  which reflex            lights 0.95   (none of them 0.03 · timer 0.01)
  room                    den 0.92   (not said 0.05 · office 0.03)
  state                   off 0.94   (on 0.03 · dim 0.02)
  → runs: lights room="den" state="off"  0.92

Three words moved the weakest answer from 0.74 to 0.92. An ask became a run. You can read every judgment, and you can move the bar in a file you own.

When a decision runs, asks, confirms or stops →

It asks before a risky step or a value out of range, and stops when nothing fits.

The value of all this is what it refuses to do. A refusal only shows when something would have gone wrong, so here are three. Nothing ran under its bar, and nothing that cannot be undone ran without a yes.

$ evoke "restart the computer"
  power action="restart" · destructive · weakest: route 0.98
  Make the laptop restart now?  [y]es [n]o [t]each > n
[2]
$ evoke "set the volume to 150 percent"
  How loud, in percent?  150 percent is outside 0–100  > 40
  volume level="40"  0.96
volume set to 40%
$ evoke "make it cosy"
  lights 0.45 · none 0.40 · timer 0.10 · volume 0.05 · route floor 0.50
[2]

At 0.98 it was sure, and it still asked, because a reflex that cannot be undone always asks. A volume of 150 percent never reached a program. evoke named the allowed range, 0 to 100, and asked for a value inside it. A sentence that fits no reflex ran nothing, and the ranking shows why.

Approval set by risk →

Written once. Shared. Improved by everyone.

What a reflex says about itself is a file, its manifest: the readable definition of a decision. So it can be shared like any file. evoke add fetches it from git, checks it, and locks it by content. A collection grows the way packages did, one recipe at a time. The manifest below, lights, is an illustration from the tests.

reflex = 1

description = """
Turn the lights in one room on, off, or dim them.
Ceiling and lamp lights only."""
not_for = ["colour scenes and schedules", "asking whether a light is on"]
tags    = ["home", "lighting"]
effect  = "write"
confirm = "Set the {room} lights {state}?"
run     = "lights.mts"

[config]
bridge = "Hue bridge address"

[args.room]
ask   = "Which room?"
vocab = "rooms"

[args.state]
ask         = "What should the lights do?"
options.on  = "Switch on."
options.off = "Switch off."
options.dim = "Lower the brightness without switching off."

[args.brightness]
ask      = "How bright, in percent?"
pick     = "number"
range    = [1, 100]
optional = true

[examples]
"turn on the kitchen lights"   = { state = "on" }
"dim the office to 30 percent" = { state = "dim", brightness = "30 percent" }

[tests]
"make it darker in here" = { state = "dim" }
"light a candle"         = false

It learns the way you phrase things.

Type t at a confirm, and your sentence becomes an example in your overlay. An overlay is your own wording for one reflex, in a file laid over the one it ships with. Your vocabulary is a file you own too. The reflex underneath is untouched, so an update never loses your words.

$ evoke "kill the lights"
  Which room?  [1] den  [2] office  [+] add one  [0] none of these  > 1
  lights room="den" state="off" · write · weakest: state 0.74
    a write runs at 0.90 or more
  Set the den lights off?  [y]es [n]o [t]each > t
+ overlays/lights.toml  [examples] "kill the lights" = { state = "off" }
den lights off

The lesson is one line in a file of yours. The next decision reads it. A team shares its lessons the way it shares its dotfiles.

Your team's words, on How it works →

Two things in one sentence, planned before either runs.

Each part is decided as one sentence would be. The plan is shown first, numbered. A step can take a value from an earlier step. That step's reflex must say what its result holds, and the later step must take that kind of value. A part that matches nothing refuses the whole request before anything runs.

$ evoke "look up dana's address and email them"
  1  contact name="dana"  0.95
  2  mail · takes email from 1
dana <dana@example.com>
  2  mail to="dana@example.com"  0.94
drafted to dana@example.com
$ evoke "kill the lights in the den and feed the cat"
  1  lights room="den" state="off"  0.92
  2  "feed the cat" · no reflex
[2]

them names the address the first step found. mail needed one, and took it. In the second sentence, «feed the cat» matched no reflex, so nothing ran at all. contact and this mail are stand-ins from the tests. Weaving, in the manual →

How one result reaches the next step →

What software looks like when words select programs.

If the idea holds, the pieces are in place. Here is the road, one stage at a time. The first three work today. The rest could follow from them.

1. 01Your laptop.The collection installed, your key in place. Fifteen reflexes for everyday Mac tasks, written once and shared.
2. 02Your apps.The SDK puts the same decisions inside your application. The examples sketch an ops bot, an inbox, a runbook and an approval step as patterns.
3. 03A plan you read before it runs.A request becomes numbered steps that show their confidence and ask when they must. That is how automation earns trust, one line at a time.
4. 04Every program with a manifest.An application ships its reflexes the way it ships a package. Install it, and the words come with it.
5. 05Your words, everywhere.Your vocabulary and your lessons are files. They could follow you from the laptop to the phone to the device on the wall.
6. 06Engines chosen by their numbers.Jev is the first adapter of a design bound to none. The next is chosen by how honest its probabilities are.

The whole picture, from one reflex to plans across machines: where evoke is going.

Ideas like this live or die in the first year.

A shared recipe is used by everyone who installs it, so a small flaw compounds, and so does care. Four things are held to from the start.

• The format is frozen. A manifest key is never removed or given a new meaning, so every recipe ever tagged stays readable.
• The manual is tested. Its sessions are transcripts that the test suite replays against the built binary on every change.
• The bars are yours to read and change. Each one has a default from the adapter, and one line in evoke.toml moves it. evoke test checks how your own sentences are read.
• One core, three ways in. The CLI, the package manager and the SDK share it, so a decision is the same wherever it is made.

Quality is the strategy, not a finish. A reflex written well once is right for everyone who installs it, for as long as the format lasts.

Start in your terminal, or in your app.

One small binary on macOS and Linux. Node next to it, for reflexes written in JavaScript.

Either way, you need a key from TypeSafe AI in TYPESAFE_API_KEY before your first sentence. Get started has every step.

Then follow the first ten minutes in the manual, or see six examples, each with its request, its result and what it needs.