The command context¶
Every command script runs with a command context: a table named ctx that
describes the invocation. It tells the script what command fired, what was said,
and what the trigger pattern captured. ctx is a per-invocation object, not part
of the amri.* function library, so it is documented here rather
than in the API reference.
ctx.command¶
ctx.command holds the facts about this invocation.
| Field | Value |
|---|---|
ctx.command.name |
The command's name, as declared in the profile. |
ctx.command.trigger_type |
How it fired: "speech", "input", "variable", "lifecycle", or "script". |
ctx.command.confidence |
The recognition confidence for this utterance, from 0.0 to 1.0. It is 0 for non-speech triggers. |
ctx.command.pattern |
The trigger pattern that matched. |
ctx.command.profile |
Present only inside a lifecycle hook (on_load / on_unload), where it names the profile the hook runs under. It is absent in ordinary command bodies. |
All hardware triggers, whether key, mouse, or device button, report
trigger_type == "input". Which device fired is in ctx.command.pattern, not the
type.
confidence is speech-only
ctx.command.confidence is meaningful only when trigger_type is "speech".
A command fired by a key, a variable change, or amri.task.start reports 0,
so guard on the trigger type before treating a low number as a weak match.
ctx.captures¶
ctx.captures holds the named values pulled from the trigger pattern. Each entry
is a string, keyed by the capture name from the pattern. For a pattern
search [for;] {query...}, read the spoken text as ctx.captures.query:
See Captures for how patterns name and constrain the values they capture.
ctx.args¶
ctx.args holds the argument table passed when a command is launched as a task
with amri.task.start(name, args). It is absent when the command was triggered
by speech or input directly. Use it to hand data to a command you run from another
script.
Query functions¶
ctx also carries functions that read the command registry and the recent
dispatch history. Call them with a dot, not a colon.
| Call | Returns |
|---|---|
ctx.command_exists(name) |
true if a command named name is currently registered. |
ctx.command_count() |
The number of registered commands. |
ctx.last_command() |
The name of the most recently dispatched command, or nil if none. |
ctx.last_spoken() |
The text of the last phrase Amri recognized, or nil if none. |
ctx.history([n]) |
A table of the n most-recently dispatched command names, most recent first ([1] is the newest). n defaults to 10. |
Example¶
This script reads a capture and uses the confidence to reject a weak match. Its
command declares the pattern set power {level:low;medium;high}, so
ctx.captures.level is one of those three words.
-- set_power.lua
if ctx.command.confidence < 0.5 then
amri.log.warn("low confidence, ignoring: " .. ctx.command.pattern)
return
end
local level = ctx.captures.level
amri.input.text(level)
amri.log.info(ctx.command.name .. " set power to " .. level)
To keep a value across invocations rather than reading it fresh each time, store it with the variable API.