[voice] Support custom rules on item metadata

[GiviMAD]

Hello OpenHAB maintainers, I would like to merge these PR which is a continuation of #3853 to include support for custom rules declared on the item metadata namespace voice system.

It introduces a breaking change over it because it changes the dynamic token from * to $*$. These way it looks similar to the other supported special tokens $name$ and $cmd$.

I let here a small summary of the interpreter functionality after these PR.

BR

---

The Standard Interpreter

The built-in text rule engine in OpenHAB.

Target item resolution

The interpreter resolves the item name based on the its label/synonyms and it's parent label/synonyms.

An example of the possible situations will be:

If you have Group item labeled as TV with a Dimmer child Brightness.
The interpreter understands these phrases as the same turn off tv, turn off brightness, turn off tv brightness and turn off brightness tv.

If you add a Switch child labeled as Power to the group.
The interpreter understands now also the phrases turn off power, turn off tv power and turn off power tv.
But the turn off tv phase now detect a collision because two matching items accept the OFF command.

Name prevalence

One way you can solve this is by using the name prevalence, items with start with other items names take prevalence over them.

If the Switch item has the name tv and the and Dimmer item the name tv_brightness there will be no collisions between them and the OFF command will target the Switch item.

Exact match label/synonym prevalence

Other way you can solve this is by using the exact match prevalence, items with have an exact match on their label/synonyms take prevalence.

If the Switch item has the synonym TV there will be no collisions between them and the OFF command will target the Switch item.

Location prevalence

The dialog processor forward its locationItem to the standard interpreter to be used for reducing collisions on the target resolution.

If you have two items labeled as Light but one is a child of the location item you have configured for the dialog execution, the item takes prevalence.

The location takes prevalence over an exact match.

Built-in rules

The interpreter includes built-in rules for English, German, French, Italian and Spanish for common uses cases like.
Implementation could be found in the standard interpreter source code.

Examples:

Turn on <ITEM_LABEL>.
Turn off <ITEM_LABEL>.
Play the <ITEM_NAME>.
Pause the <ITEM_NAME>.
...

Item description rules

The interpreter also creates rules for your item descriptions for English, German, French, Italian and Spanish.

If you have a Dimmer item called Light with command description 100=high the interpreter will also understand the phrase Set light to high.

Item custom rules.

You can register custom rules into the interpreter using items and the metadata namespace voice-system.

The examples of valid values:

"start? watch|watching $*$ on $name$":
Matches "start watching some show on tv" sends command "some show", or "some_show_id" if item command description contains `some_show_id=some show`.

"watch|play $*$ on tv":
Matches "play some show on tv" sends command "some show", or "some_show_id" if item command description contains `some_show_id=some show`.

"watch|play $cmd$":
Matches "play some show" and sends command "some_show_id" only if the item command description contains `some_show_id=some show`.

"start? watch|watching $cmd$ at|on? $name$":
Matches "watch some show tv" only if item command description contains `some_show_id=some show`, sends command "some_show_id".

As you can see there are some reserved tokens and characters:

• $name$ defines the place of the item name (resolved as explained before), is optional.
• $cmd$ defines the place of a command label, extracted from the item command description.
• $*$ defines the place of a command, whose value is not constrained.
• | defines alternative word tokens.
• ? defines optional word token.

The item metadata namespace voice-system allows two possible configurations:

• isTemplate: The rule defined on these item metadata will not target it but similar items (items with same tags and semantic).
• isSilent: The interpreter will say nothing in case these rule is executed correctly (util if you plan on trigger a rule and talk from it).

Note that if the isTemplate config is false, the rule target is limited to the item that registers it. When it's true the item registering the rule gets excluded of matching with it.

Note that when you use the option isTemplate in rules without the $name$ token, collisions are still solved based on location. So you can have a play $cmd$ here rule which is scoped to the dialog location.

There are some limitations:

• Rule should contain $cmd$ or $*$ but not both.
• Rules that include $name$ and $*$ should have at least one non optional token between them.
• Rules can not start by $name$ or $*$, neither by them prefixed only of optional tokens.
• Rules can not contain $name$, $cmd$ or $*$ multiple times.

[GiviMAD]

Build error seems unrelated to the PR.
It reports filter:="(&(osgi.wiring.package=org.apache.directory.api.ldap.model.cursor)(version>=2.1.0)(!(version>=3.0.0)))"]].
I have detected the problem I'm importing the Tuple class from that package. Fixing it.

[GiviMAD]

@dalgwen after these PR you can use the standard interpreter to create custom rules that target items by its tags or semantic as you ask once in the forum. Thank you for bringing the idea to the table.

[GiviMAD]

Closed by error, I reverted a couple of lines in the getMatchingItems method because of a bug I just discover testing it, I have rebased the change into a single commit.

[kaikreuzer]

Thanks, just some minor syntax requests.

[GiviMAD]

Thank you for the review!
I have also added a fix for the template functionality and its test.

[kaikreuzer]

Thanks!

[openhab-bot]

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/dialog-processing-with-the-pulseaudiobinding/148191/1