This is an automated email from the ASF dual-hosted git repository.
aradzinski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nlpcraft.git
The following commit(s) were added to refs/heads/master by this push:
new 9bc4e1b Update README.md
9bc4e1b is described below
commit 9bc4e1b767b8d81a9414a478ee3704462f339b38
Author: Aaron Radzinski <[email protected]>
AuthorDate: Tue Oct 20 12:27:54 2020 -0700
Update README.md
---
README.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 110 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index dddfab3..ef49ba4 100644
--- a/README.md
+++ b/README.md
@@ -78,7 +78,116 @@ When using NLPCraft you will be dealing with three main
components:
**REST server** provides REST endpoint for user applications to securely query
data sources using NLI via data models deployed in data probes.
[Learn more >](https://nlpcraft.apache.org/docs.html)
-
+
+## Example
+As a quick example let's consider a very simple implementation for NLI-powered
light switch. Our app should understand something like
+``Turn the lights off in the entire house`` or ``Switch on the illumination in
the master bedroom closet``. You can easily
+modify intent callbacks to perform the actual light switching using HomeKit or
Arduino-based controllers.
+
+### Add NLPCraft
+Add NLPCraft dependency to your project:
+```xml
+<dependencies>
+ <dependency>
+ <groupId>org.apache.nlpcraft</groupId>
+ <artifactId>nlpcraft</artifactId>
+ <version>0.7.0</version>
+ </dependency>
+</dependencies>
+```
+NOTE: **0.7.0** should be the latest NLPCraft version.
+
+### Define Data Model
+Declare the static part of the data model using YAML which we will later load
in our Scala-based model implementation:
+```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|control|let|set|get|put}"
+ - name: "<ENTIRE_OPT>"
+ macro: "{entire|full|whole|total|*}"
+ - name: "<LIGHT>"
+ macro: "{all|*} {it|them|light|illumination|lamp|lamplight}"
+enabledBuiltInTokens: [] # This example doesn't use any built-in tokens.
+elements:
+ - id: "ls:loc"
+ description: "Location of lights."
+ synonyms:
+ - "<ENTIRE_OPT> {upstairs|downstairs|*}
{kitchen|library|closet|garage|office|playroom|{dinning|laundry|play} room}"
+ - "<ENTIRE_OPT> {upstairs|downstairs|*}
{master|kid|children|child|guest|*} {bedroom|bathroom|washroom|storage}
{closet|*}"
+ - "<ENTIRE_OPT> {house|home|building|{1st|first} floor|{2nd|second}
floor}"
+
+ - id: "ls:on"
+ groups:
+ - "act"
+ description: "Light switch ON action."
+ synonyms:
+ - "<ACTION> <LIGHT>"
+ - "<ACTION> on <LIGHT>"
+
+ - id: "ls:off"
+ groups:
+ - "act"
+ description: "Light switch OFF action."
+ synonyms:
+ - "<ACTION> <LIGHT> {off|out}"
+ - "{<ACTION>|shut|kill|stop|eliminate} {off|out} <LIGHT>"
+ - "no <LIGHT>"
+intents:
+ - "intent=ls conv=false term(act)={groups @@ 'act'} term(loc)={id ==
'ls:loc'}*"
+```
+
+### Model Implementation
+Create intent callbacks (Scala in this example) in model implementation:
+```scala
+package org.apache.nlpcraft.examples.lightswitch
+
+import org.apache.nlpcraft.model.{NCIntentTerm, _}
+
+class LightSwitchModel extends
NCModelFileAdapter("org/apache/nlpcraft/examples/lightswitch/lightswitch_model.yaml")
{
+ @NCIntentRef("ls")
+ @NCIntentSample(Array(
+ "Turn the lights off in the entire house.",
+ "Switch on the illumination in the master bedroom closet.",
+ "Get the lights on.",
+ "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."
+ ))
+ 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(_.meta[String]("nlpcraft:nlp:origtext")).mkString(", ")
+
+ // Add HomeKit, Arduino or other integration here.
+
+ // By default - just return a descriptive action string.
+ NCResult.text(s"Lights '$status' in '${locations.toLowerCase}'.")
+ }
+}
+```
+NOTES:
+ - We are loading our static model declaration that we've defined above using
`NCModelFileAdapter`.
+ - Annotation `@NCIntentRef` references the intent defined in our YAML model
definition.
+ - We use `@NCIntentSample` to provide sample sentences that should satisfy
this intent. These
+ samples are used for model auto-testing and synonyms analysis.
+
+[Learn more >](http://nlpcraft.apache.org/examples/light_switch.html)
+
## Copyright
Copyright (C) 2020 Apache Software Foundation
