1. Home
  2. Light Switch ex

Light Switch ex

Overview

This example provides very simple implementation for NLI-powered light switch. You can say something like "Turn the lights off in the entire house" or "Switch on the illumination in the master bedroom closet". You can modify intent callbacks to perform the actual light switching using HomeKit or Arduino-based controllers.

Complexity:
Source code: GitHub
Review: All Examples at GitHub

Create New Project

You can create new Scala projects in many ways - we'll use NLPCraft CLI to accomplish this task:

Data Model

We are going to start with declaring the static part of our model using YAML which we will later load using NCModelFileAdapter in our Scala-based model implementation. Open src/main/resources/light_switch.yaml file and replace its content with the following YAML:

id: "nlpcraft.lightswitch.ex"
name: "Light Switch Example Model"
version: "1.0"
description: "NLI-powered light switch example model."
            
macros:
  - name: "<ACTION>"
    macro: "{turn|switch|dial|let|set|get|put}"
  - name: "<KILL>"
    macro: "{shut|kill|stop|eliminate}"
  - name: "<ENTIRE_OPT>"
    macro: "{entire|full|whole|total|_}"
  - name: "<FLOOR_OPT>"
    macro: "{upstairs|downstairs|{1st|2nd|3rd|4th|5th|top|ground} floor|_}"
  - name: "<TYPE>"
    macro: "{room|closet|attic|loft|{store|storage} {room|_}}"
  - name: "<LIGHT>"
    macro: "{all|_} {it|them|light|illumination|lamp|lamplight}"
                                
enabledBuiltInTokens: []

permutateSynonyms: true
sparse: true

elements:
  - id: "ls:loc"
    description: "Location of lights."
    synonyms:
      - "<ENTIRE_OPT> <FLOOR_OPT> {kitchen|library|closet|garage|office|playroom|{dinning|laundry|play} <TYPE>}"
      - "<ENTIRE_OPT> <FLOOR_OPT> {master|kid|children|child|guest|_} {bedroom|bathroom|washroom|storage} {<TYPE>|_}"
      - "<ENTIRE_OPT> {house|home|building|{1st|first} floor|{2nd|second} floor}"

  - id: "ls:on"
    groups:
      - "act"
    description: "Light switch ON action."
    synonyms:
      - "<ACTION> {on|up|_} <LIGHT> {on|up|_}"
      - "<LIGHT> {on|up}"

  - id: "ls:off"
    groups:
      - "act"
    description: "Light switch OFF action."
    synonyms:
      - "<ACTION> <LIGHT> {off|out}"
      - "{<ACTION>|<KILL>} {off|out} <LIGHT>"
      - "<KILL> <LIGHT>"
      - "<LIGHT> <KILL>"
      - "no <LIGHT>"

intents:
  - "intent=ls term(act)={has(tok_groups, 'act')} term(loc)={# == 'ls:loc'}*"

There are number of important points here:

  • Line 6 defines several macros that are used later on throughout the model's elements to shorten the synonym declarations. Note how macros coupled with option groups shorten overall synonym declarations 1000:1 vs. manually listing all possible word permutations.
  • Lines 22, 23 define model properties that allow for multi-word synonyms in this model to be sparse and permutate them for better detection. These two properties generally enable a free-form natural language comprehension.
  • Lines 26, 33, 41 define three model elements: the location of the light, and actions to turn the light on and off. Action elements belong to the same group act which will be used in our intent (line 42). Note that these model elements are defined mostly through macros we have provided above.
  • On line 52 we define a non-conversational intent ls that requires one action (a token belonging to the group act) and optional list of light locations (zero or more tokens with ID ls:loc) - by default we assume the entire house as a default location.

Now that our model is ready let's create a Java class that would load this model and provide the actual callback for when the intent ls is detected in the user input.

Model Class

Open src/main/scala/demo/LightSwitch.scala file and replace its content with the following code:

package demo

import org.apache.nlpcraft.model.{NCIntentTerm, _}

class LightSwitch extends NCModelFileAdapter("light_switch.yaml") {
    @NCIntentRef("ls")
    @NCIntentSample(Array(
        "Turn the lights off in the entire house.",
        "Turn off all lights now",
        "Switch on the illumination in the master bedroom closet.",
        "Get the lights on.",
        "Lights up in the kitchen.",
        "Please, put the light out in the upstairs bedroom.",
        "Set the lights on in the entire house.",
        "Turn the lights off in the guest bedroom.",
        "Could you please switch off all the lights?",
        "Dial off illumination on the 2nd floor.",
        "Please, no lights!",
        "Kill off all the lights now!",
        "No lights in the bedroom, please.",
        "Light up the garage, please!",
        "Kill the illumination now!"
    ))
    def onMatch(
        @NCIntentTerm("act") actTok: NCToken,
        @NCIntentTerm("loc") locToks: List[NCToken]
    ): NCResult = {
        val status = if (actTok.getId == "ls:on") "on" else "off"
        val locations =
            if (locToks.isEmpty)
                "entire house"
            else
                locToks.map(_.getOriginalText()).mkString(", ")

        // Add HomeKit, Arduino or other integration here.

        // By default - return a descriptive action string.
        NCResult.text(s"Lights '$status' in '${locations.toLowerCase}'.")
    }
}

The intent callback logic is very simple - we return a descriptive confirmation message back (explaining what lights were changed). With action and location detected, you can add the actual light switching using HomeKit or Arduino devices. Let's review this implementation step by step:

  • On line 5 our class extends NCModelFileAdapter that allows us to load most of the model declaration from the external YAML file and only provide functionality that we couldn't express in declarative portion in YAML.
  • Line 6 annotates method onMatch as a callback for the intent ls when it is detected in the user input. Note that intent ls is defined in the light_switch.yaml file that was loaded by NCModelFileAdapter class.
  • Note the line 7 where we use @NCIntentSample annotation to provide samples of the user input that this intent should match. Apart from documentation purpose these samples will be used when we will be testing out model below.
  • Lines 25 and 26 map terms from detected intent to the formal method parameters of the onMatch method.
  • On the line 38 the intent callback simply returns a confirmation message.

Build Project

Once we have our model ready let's go to ~/LightSwitch directory and run the Maven build:

            $ cd ~/LightSwitch
            $ mvn clean package

At this stage we have our project built and we are ready to start testing.

Start Server

Run the following command to start local REST server, if it hasn't been started already, from the NLPCraft installation directory:

NOTES:

  • REST server is a "fire-and-forget" component that you generally need to start it only once for this and other examples.
  • Run bin/nlpcraft.sh help --cmd=start-server to get a full help on this command.
  • NLPCraft CLI is available as nlpcraft.sh for and nlpcraft.cmd for .

Testing

Remember the @NCIntentSample annotation we have used in our model code next to intent definition?

Part of the test framework, the auto-validator class NCTestAutoModelValidator takes one or more model IDs (or class names) and performs validation. Validation consists of starting an embedded probe with a given model, scanning for @NCIntentSample and @NCIntentSampleRef annotations and their corresponding callback methods, submitting each sample input sentences from these annotations and checking that resulting intent matches the intent the sample was attached to. Note that auto-testing does not require any additional code to be written - the class gathers all required information from the model itself.

As always, you can launch model auto-validator as any other Java class but we'll use NLPCraft CLI to do it more conveniently:

            $ bin/nlpcraft.sh test-model --cp=~/LightSwitch/target/classes --mdls=demo.LightSwitch

NOTES:

  • Run bin/nlpcraft.sh help --cmd=test-model to get a full help on this command.
  • Note that you can use retest-model command in REPL mode to re-run the last model test avoiding the retyping of all required parameters.
  • NLPCraft CLI is available as nlpcraft.sh for and nlpcraft.cmd for .

Look at the output of this command and you will see the test results for all our sample utterances:

Rinse & Repeat

Typical development cycle consists of:

All of these operations can be performed from NLPCraft CLI in REPL mode or from any IDE.

NOTE: you don't need to restart REST server every time - it only needs to be started once.

Done! 👌

You've created light switch data model, started the REST server and tested this model using the built-in test framework.