Synonyms¶

Synonyms collapse several spoken words onto one stored value, so your command handles a single value no matter how the phrase was said.

A capture stores whatever word matched. If two patterns, or one list, offer different words for the same idea, the capture ends up with several values that mean the same thing. Synonyms alias the extra words to one canonical value, so the rest of the command only deals with that one value.

How it works¶

Synonyms are declared per command in a [command.synonyms] table, one entry per capture name. Each entry is an array of groups. A group is itself an array, and the first item in the group is the canonical value. Every other item in the group maps to that first item.

Resolution happens after Amri works out what you said and before the value is stored: the spoken word is looked up in the groups and replaced with the canonical value. A word not listed in any group maps to itself. Because the swap happens first, everything downstream, including a value branch, sees only canonical values.

An alias can be more than one word. "emergency stop" and "all stop" can both alias to "stop", the same way single words do.

Example¶

Two phrasings fill the same position capture. Without synonyms it would hold four values (up, down, deploy, retract). The synonym table folds deploy into up and retract into down, so the response only handles two:

[[command]]
name = "Landing Gear"
description = "Raise or lower the landing gear."
category = "flight"

[command.trigger]
pattern = [
    "[landing;] gear {position:up;down}",
    "{position:deploy;retract} [landing;] gear",
]

[command.synonyms]
position = [
    ["up", "deploy"],       # first item is canonical
    ["down", "retract"],
]

[command.response.position]
"up"   = "amri.input.tap('g')"
"down" = "amri.input.tap('h')"

Say "gear up", "gear down", "deploy landing gear", or "retract landing gear". The response only needs the two canonical keys.

Synonyms alias, maps remap

A synonym changes which value gets stored. A value map leaves the stored value alone and changes only what a shared action string substitutes. Synonyms run first, then maps. Use a synonym to normalise the spoken form; use a map to turn a value into a key name.