Alarm Clock _ex

Overview

This simple example provides a "alarm clock" implementation where you can ask to set the timer for a specific duration from now expressed in hours, minutes and/or seconds. You can say "ping me in 3 minutes", "buzz me in an hour and 15 minutes", or "set my alarm for 30 secs". When the timers is up it will simply print out "BEEP BEEP BEEP" in the data probe console.

Complexity:
Source code: GitHub

Create New Project

You can create new Java project in many different ways - we'll use Maven archetype generation for that. In your home folder run the following command:

            mvn archetype:generate -DgroupId=examples -DartifactId=my-app -DarchetypeVersion=1.4 -DinteractiveMode=false
        

This will create my-app folder with the following default maven project structure:

├── pom.xml
└── src
    ├── main
    │   └── java
    │       └── examples
    │           └── App.java
    └── test
        └── java
            └── examples
                └── AppTest.java
        

For our example we'll use JetBrain's IntelliJ IDEA. Create new IDEA project from this source folder (make sure to pick JDK 8 or later JDK and language support). Let's also delete auto-generated files App.java and AppTest.java from our project as we won't be using them.

Add NLPCraft

Next we need to add NLPCraft dependency to our new project. Open pom.xml file and replace dependencies section with the following code:

            <dependencies>
                <dependency>
                    <groupId>org.apache.nlpcraft</groupId>
                    <artifactId>nlpcraft</artifactId>
                    <version>0.7.0</version>
                </dependency>
            </dependencies>
        

Also make sure that you have correct JDK version (11 or above) for the maven compiler plugin:

            <properties>
                <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
                <maven.compiler.source>11</maven.compiler.source>
                <maven.compiler.target>11</maven.compiler.target>
            </properties>
        

IDEA should automatically reload the project with newly updated pom.xml file and we should be ready now to develop our data model.

Data Model

We are going to start with declaring the static part of our semantic model using JSON which we will later load using NCModelFileAdapter in our Java-based model implementation. Create new alarm_model.json file and add the following model declaration into it:

{
    "id": "nlpcraft.alarm.ex",
    "name": "Alarm Example Model",
    "version": "1.0",
    "description": "Alarm example model.",
    "enabledBuiltInTokens": [
        "nlpcraft:num"
    ],
    "elements": [
        {
            "id": "x:alarm",
            "description": "Alarm token indicator.",
            "synonyms": [
                "{ping|buzz|wake|call|hit} {me|up|me up|*}",
                "{set|*} {my|*} {wake|wake up|*} {alarm|timer|clock|buzzer|call} {up|*}"
            ]
        }
    ],
    "intents": [
        "intent=alarm term={id=='x:alarm'} term(nums)={id=='nlpcraft:num' && ~nlpcraft:num:unittype=='datetime' && ~nlpcraft:num:isequalcondition==true}[0,7]"
    ]
}
        

There are number of important points here:

• Line 7 indicates that we'll be using built-in token nlpcraft:num (and therefore it needs to be explicitly enabled).
• Line 11 defines the only custom model element we'll need. It's ID is x:alarm and it is defined through synonyms. It basically means a verb to set up an alarm clock.
• On line 20 we define an intent alarm that we are going to be looking for in the user input that consists of two terms: one for x:alarm element (defined above) and another one for up to 7 numeric values of unit type datetime (minutes, seconds, hours, etc.).

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 alarm is detected in the user input.

Model Class

Let's create new Java class in AlarmModel.java with the following code:

package org.apache.nlpcraft.examples.alarm;

import org.apache.nlpcraft.model.*;
import java.time.*;
import java.time.format.*;
import java.util.*;

import static java.time.temporal.ChronoUnit.*;

public class AlarmModel extends NCModelFileAdapter {
    private static final DateTimeFormatter FMT =
        DateTimeFormatter.ofPattern("HH'h' mm'm' ss's'").withZone(ZoneId.systemDefault());

    private final Timer timer = new Timer();

    public AlarmModel() {
        // Loading the model from the file in the classpath.
        super("org/apache/nlpcraft/examples/alarm/alarm_model.json");
    }

    @NCIntentRef("alarm")
    @NCIntentSample({
        "Ping me in 3 minutes",
        "Buzz me in an hour and 15mins",
        "Set my alarm for 30s"
    })
    private NCResult onMatch(
        NCIntentMatch ctx,
        @NCIntentTerm("nums") List<NCToken> numToks
    ) {
        if (ctx.isAmbiguous())
            throw new NCRejection("Not exact match.");

        long unitsCnt = numToks.stream().map(tok -> (String)tok.meta("num:unit")).distinct().count();

        if (unitsCnt != numToks.size())
            throw new NCRejection("Ambiguous time units.");

        LocalDateTime now = LocalDateTime.now();
        LocalDateTime dt = now;

        for (NCToken num : numToks) {
            String unit = num.meta("nlpcraft:num:unit");

            // Skip possible fractional to simplify.
            long v = ((Double)num.meta("nlpcraft:num:from")).longValue();

            if (v <= 0)
                throw new NCRejection("Value must be positive: " + unit);

            switch (unit) {
                case "second": { dt = dt.plusSeconds(v); break; }
                case "minute": { dt = dt.plusMinutes(v); break; }
                case "hour": { dt = dt.plusHours(v); break; }
                case "day": { dt = dt.plusDays(v); break; }
                case "week": { dt = dt.plusWeeks(v); break; }
                case "month": { dt = dt.plusMonths(v); break; }
                case "year": { dt = dt.plusYears(v); break; }

                default:
                    // It shouldn't be assert, because 'datetime' unit can be extended.
                    throw new NCRejection("Unsupported time unit: " + unit);
            }
        }

        long ms = now.until(dt, MILLIS);

        assert ms >= 0;

        timer.schedule(
            new TimerTask() {
                @Override
                public void run() {
                    System.out.println(
                        "BEEP BEEP BEEP for: " + ctx.getContext().getRequest().getNormalizedText() + ""
                    );
                }
            },
            ms
        );

        return NCResult.text("Timer set for: " + FMT.format(dt));
    }

    @Override
    public void onDiscard() {
        // Clean up when model gets discarded (e.g. during testing).
        timer.cancel();
    }
}
        

There's a bit of a logic here that deals mostly with taking multiple numeric values and converting them into a single number of milliseconds that the alarm clock needs to be set up for. Let's review it step by step:

• On line 10 our class extends NCModelFileAdapter that allows us to load most of the model declaration from the external JSON or YAML file (line 18) and only provide functionality that we couldn't express in declarative portion in JSON.
• Line 27 defines method onMatch as a callback for intent alarm when it is detected in the user input. Method parameter numToks will get up to 7 tokens of type nlpcraft:num (see intent definition above).
• Note the line 22 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.
• The rest of the method onMatch implementation is a relatively straight forward Java code that calculates timer delay from multiple numeric units and their types. In the end (line 68) it schedules a timer to print "BEEP BEEP BEEP" at calculated time. For simplicity, this message will be printed right in the data probe console.
• On the line 82 the intent callback simply returns a confirmation message telling for what actual time the alarm clock was set.

Start Data Probe _optional

NLPCraft data models get deployed into data probe. Let's start a standalone data probe with our newly created data model. To start data probe we need to configure Run Configuration in IDEA with the following parameters:

• Main class: org.apache.nlpcraft.NCStart
• VM arguments: -Dconfig.override_with_env_vars=true
• Environment variable: CONFIG_FORCE_nlpcraft_probe_models.0=org.apache.nlpcraft.examples.alarm.AlarmModel
• Program arguments: -probe

Start this run configuration and make sure you have positive console output indicating that our model has been successfully loaded and probe started.

Start REST Server

REST server listens for requests from client applications and routes them to the requested data models via connected data probes. REST server starts the same way as the data probe. Configure new Run Configuration in IDEA with the following parameters:

• Main class: org.apache.nlpcraft.NCStart
• Program arguments: -server

Once started ensure that your REST server console output shows that data probe is connected and the REST server is listening on the default localhost:8081 endpoint.

At this point we've developed our data model, deployed it into the data probe, and started the REST server. To test it, we'll use the built-in test framework that allows you to write convenient unit tests against your data model.

Testing

Let's develop a unit test for our model. Remember the @NCIntentSample annotation we have used in our code next to intent definition? Auto-testing utility is relying on it.

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 annotations and their corresponding callback methods, submitting each sample input sentences from @NCIntentSample annotation 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.

Let's configure IDEA Runtime Configuration (remember - there's no need to write any additional code here):

• Main class: org.apache.nlpcraft.model.tools.test.NCTestAutoModelValidator
• VM options: -DNLPCRAFT_TEST_MODELS=org.apache.nlpcraft.examples.alarm.AlarmModel

Start this Runtime Configuration and you should be getting standard log in the output console.

Done! 👌

You've created alarm clock data model, deployed it into the data probe, started the REST server and tested this model using the built-in test framework.