Usage

In Spec We Trust

One of the problem while devolopping a voice assistant using Snips is that we otfen endup having a missmatch between assistant possible intents and intents action. This can also happen that there is a slot name missmatch due to for example a console app that was developped by a developper and the action by another.

To fix this issue, we developped a tool that behave like this:

1. we expose manually for each action a “spec contract in yml” about which intents and slot the action will use, with a format as follow:

your_app_dir/my_action_n1/spec.yml

name: "My Action Code"

version: "0.0.2"
supported_snips_version: ["0.60.1", "0.62.3", ...]
updated_at: "12/04/2019"

slots:
   slot_name_A: "slot_type_startwith_1"
   slot_name_B: "slot_type_startwith_2"
   ...

coverage:
    intent1:
         [ ["slot_name_B", "+"], ["slot_name_A", "?"] ],
    intent2:
         [ ["slot_name_B", 1], ["slot_name_A", "{1,4}" ],
...

that coverage section is the one used to specify what to check you can either write it as shown upper or specify only the intent meaning all subcase like this:

coverage:
    intent1:
    intent2:

Note: this second method “mask” possible code coverage problem so we highly encourage you to use the first version (it will allow more fine grained analysis by our tools)

About the pattern quantifiers

The current implementation used of slot sequence pattern rule are only based on the quantity of each slot expected in the intent by the action code handler. And the following quantifiers follow as mutch as possible the regexp one. Here is the list of what is implemented now:

  • “+” between 1 and n
  • “*” between 0 and n
  • “?” between 0 and 1
  • “{1,10}” between 1 and 10
  • 3 always 3

If the action code is not yours you obviously do not want to add the spec file in this 3rd party directory (who knows what will happen at next update). But you can create a spec file in one of your managed action code following the name convention: your_app_dir/my_action_n1/{my_3rd_pary_action}.spec.yml where my_3rd_pary_action is the 3rd party action code folder name

  1. A cli match the concordence of both and report inconsistencies.
snips-app spec check --assistant_dir ... --actions_dir ...

(I invite you to alias snips-app to sap)

A typical report of the CLI looks like this:

Analysing spec for:
     assistant: /home/epi/open/projects/snips-app-helpers/tests/fixtures/assistant_1/assistant.json
     app dir: /home/epi/open/projects/snips-app-helpers/tests/fixtures/actions_1

Detected spec:
        - @ Likhitha.Today/spec.yml applied to Likhitha.Today
        - @ Likhitha.Today/ozie.Calculations.spec.yml applied to ozie.Calculations
          ...

Intents do not seem to be covered by any action code:
        - currencyConverter
          ...
        Remarks:
                This might be due to missing spec in some action codes else you
                should take it seriously as no response at all will be given by your
                assistant to final user.

Some Intents seems to be hooked multiple times:
        - intent getCurrentTime in actions: ['Today', 'Music Player']
          ...
        Remarks:
                While it might be legit do not forget that it means each time you
                trigger this intent n actions will be performed

Action waiting intent not in assistant:
        - MySuperFakeIntent from action: Music Player
        Remarks:
                This should not be a problem except that it consume resource with
                useless purpose

Missing spec for following actions:
        - Snips.Smart_Lights_-_Hue
          ...

Guess The Spec

As a first step if you already have a big assistant and do not want to add all specs manually, a system allow to guess what should be the good spec for each action code based on what intent and slots names are detected in the action code to use it you can directly use the following cli

snips-app spec auto-guess --spec_store ... --assistant_dir ... --actions_dir ...

The Spec Middleware

Once you have the specs defined as bellow you can use it to various purposes.

One of them is to match a action spec to an assistant spec, without modifying any of both. This is usefull in the case you want a console app and action to communicate but both beeing open 3rd party, or you develop only the action and dislike the interface. How is that possible ?

Thank to a middleware action code.

What it does ?

based on a routing file written in yml by the user, in the following form

routing.yml

# routing table

"original_intent1":
   to: "routed_intent1"
   slots:
       original_slot_1: routed_slot_1
       original_slot_1: routed_slot_2
       ...
...

Then it you want to make your redirection work you need to install the action src/actions/snips-app-middleware with the routing.yml file in the same host and configure the config.ini to point to this one.