Follow a sentence all the way to an action.

One request, from the words you type to the program that runs. Seven short parts, each shown on the same example. Read them in order, or jump to the one you need.

01What a reflex contains
02What your sentence contributes
03Run, ask, confirm, or stop
04One result reaches the next step
05A program continues a workflow
06Your team's vocabulary
07What your application owns

A reflex

An installed reflex is a program with a manifest.

This is contact, the first reflex of the walkthrough. Its manifest states its purpose, its inputs, what its result holds, and how careful to be. The classifier reads these words. The program receives the values.

contact/reflex.tomlby the author

reflex = 1

description = """
Look up a person's email address in the team directory.
One person at a time; prints the address."""

not_for = ["writing to anyone", "phone numbers", "adding a person to the directory"]
tags    = ["people"]
effect  = "read"
confirm = "Look up {name}'s address?"
run     = "contact.mts"

[args.name]
ask   = "Whose address?"
vocab = "people"

[yields]
email = "email"

[examples]
"look up dana's address"    = {}
"what is sam's email"       = {}
"find the address for dana" = {}

description · not_for: The purpose, and its edges. What it does in plain words, then the near misses it must not take.
effect: How careful to be. A read only observes, so it runs at a lower bar than a write.
confirm: Its own question. The line a person answers when evoke is not sure.
[args.name]: The input it accepts. A name from your own word list, people. Every input has one source: the author's options, your words, a piece of the sentence, or a yes/no switch.
[yields]: What its result holds. An email address. A later step that needs one can take it.

Inspect the example definition →

Your sentence

Your sentence picks the reflex and fills its inputs.

evoke turns every installed manifest into closed questions and asks the classifier all of them at once. Each answer is a probability. Nothing in the answer is a new value: only a choice among what already exists.

01Which reflex?One choice over every installed reflex, or none of them. Built from each description and its examples.
02Does it fit?A yes or no per reflex, so a sentence that asks for two things is noticed.
03Which value?One choice per input: an option, one of your words, or a piece of the sentence found by code. Or unstated.

evoke try

$ evoke try "kill the lights in the den"
  lights 0.91 · none 0.06 · timer 0.02 · volume 0.01
  room   den 0.85 · unstated 0.10 · office 0.05
  state  off 0.88 · on 0.05 · dim 0.05 · unstated 0.02
  fits   lights 0.70 · timer 0.05 · volume 0.05
  run · weakest: room 0.85

a missing value

$ evoke "kill the lights"
  Which room?  [1] den  [2] office  [+] add one  > 1
  lights room="den" state="off" · write · weakest: state 0.58
  Set the den lights off?  [y]es [n]o [t]each > y
den lights off

1«den» matched a word of yours. Rooms are a vocabulary you filled. The classifier read the word's meaning, and the program gets its value.
2«kill» meant off at 0.88. An option the author listed, chosen from the sentence. Without «in the den», the room was unstated, so evoke asked.
3Some things are never read from a sentence. A setting like a bridge address, or a secret, is supplied once with evoke config.

evoke try decides and runs nothing. The lights reflex here comes from the product's own tests. Every judgment, explained →

The gate

Run, ask, confirm, or stop.

The weakest answer is the decision's confidence. Each effect has a bar. Confidence is evidence the policy uses. It is not a guarantee that the reading is right. So what cannot be undone always asks.

Every number is calibrated. 0.85 means right about 85 times in 100. The bars are lines in a file you own, and a read may never run at a higher bar than a write.

RunOver the bar, every required input stated. The call prints with its confidence, then the result.
AskA required input was not stated, or a value fell outside its range. evoke asks the input's own question and decides again.
ConfirmUnder the bar, or a second reflex fits well too, or a piece of the sentence went unused. And always, for a destructive reflex.
StopNothing fits, and evoke abstains: the ranking prints and nothing runs. In a sentence of several steps, one part that fits nothing stops the whole sentence.

Read the decision details →

A handoff

What one step finds, the next one takes.

A reflex declares what its result holds. A later step that lacks a value of that kind takes it. The plan says so before anything runs.

Same kind, so it binds. «them» in the sentence names step 1. Its email field is an address, and mail needs one for to.

evoke

$ evoke "look up dana's address and email them"
  1  contact name="dana"  0.90
  2  mail · takes email from 1
dana <dana@example.com>
  2  mail to="dana@example.com"  0.88
drafted to dana@example.com

1The plan comes first. Two numbered lines, and what step 2 takes from step 1. A required input is filled. An optional one is decided again, with the value written into the sentence.
2Nothing is guessed. A reference that two fields could satisfy stops with a line naming them. A part that matches nothing refuses the whole sentence.

Explore the chaining example →

A continuation

A program can name the next step.

Beside its one line of text, a reflex may return data. An application loop reads next from that data and submits it as the next sentence. This is the runbook pattern, a second way to chain, where the program decides what follows.

Three reflexes, one loop. Every hop is a decision like any other. The loop is six lines of your code, and it stops the moment a step does not run.

~/runbook

$ node runbook.ts "drain the primary"
primary drained
Promote the replica now?  [y]es [n]o > y
replica promoted
writes landing on the new primary

1Two ways to chain, two owners. A handoff is planned by evoke from declared outputs. A continuation is chosen by the program, and driven by your loop.

View the runbook example →

Your words

Your names and phrases stay in your files.

A vocabulary maps your words to the values a program needs. An overlay adds your phrases and your wording. Both lay over the shipped manifest, and an update keeps them.

One merge rule. Your file adds and replaces wording. It cannot change the contract: the inputs, their sources, the program. A file of yours that will not parse makes the reflex inactive, never looser.

evoke show

$ evoke show lights
  description = "Turn the lights in one room on, off, or dim them.\nCeiling and lamp lights only."
  …
  [args.state]
+ ask = "On, off or dim?"
  options.on = "Switch on."
  …
  [examples]
  "turn on the kitchen lights" = { state = "on" }
+ "kill the lights" = { state = "off" }

1A + marks a line of yours. Teach one with evoke teach, or with t at any question. Edit the file by hand if you like.
2An update reports, never overwrites. New wording upstream is taken where you had none, and yours is kept where you did.

View the tuning guide →

Your application

What stays yours to decide.

evoke decides which call a sentence means, and whether it may run. Four things remain the application's.

Who may ask for what.A decision is plain data your code holds before it runs. Check the person, the account, the time of day. The approval example waits for a second person.
What the programs do.A reflex runs with your permissions and there is no sandbox yet. Read what you install. Its effect is the author's claim, and you can only tighten it.
What happens after a partial run.A step that fails stops the steps after it. Nothing already done is rolled back. Your application decides what to do with what ran.
Where the key goes.One request per decision leaves the machine, to the classifier you chose, with your key. Nothing goes to evoke.build.

Read the security manual →

Every reflex you install is one more thing you can ask for.

That is the direction: every program with a manifest, and your words following you from one device to the next. The idea page lays out six stages, and three exist today.

Explore examples Why reflexes →