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-website.git
The following commit(s) were added to refs/heads/master by this push:
new 5e0f22d WIP.
5e0f22d is described below
commit 5e0f22d88e4dff6c678e41be4dd9139740994428
Author: Aaron Radzinski <[email protected]>
AuthorDate: Tue Aug 18 18:02:18 2020 -0700
WIP.
---
first-example.html | 94 ++++++++++++++++++++++++++++++++++++---------------
server-and-probe.html | 16 ++++-----
2 files changed, 74 insertions(+), 36 deletions(-)
diff --git a/first-example.html b/first-example.html
index 28265f3..3a9b26e 100644
--- a/first-example.html
+++ b/first-example.html
@@ -31,7 +31,7 @@ id: first_example
<li>We'll use Mac OS/Linux environment</li>
<li>We'll use Scala to implement our model</li>
<li>We'll use <a target=_
href="https://maven.apache.org/install.html";>Maven</a> to create and build our
project</li>
- <li>We'll use <a target=_
href="https://www.jetbrains.com/idea/";>JetBrains IDEA</a> as our Scala/Java
IDE</li>
+ <li>We'll use <a target=_
href="https://www.jetbrains.com/idea/";>JetBrains IDEA</a> as our Scala/Java IDE
(any IDE would work the same way)</li>
</ul>
</section>
<section id="new_project">
@@ -67,7 +67,7 @@ id: first_example
<section id="add_nlpcraft">
<h3 class="section-title">Add NLPCraft</h3>
<p>
- We also need to add NLPCraft dependency to our new project. Open
<code>pom.xml</code> file and replace
+ We need to add NLPCraft dependency to our new project. Open
<code>pom.xml</code> file and replace
<code>dependencies</code> section with the following code:
</p>
<pre class="brush: xml, highlight: [3, 4, 5]">
@@ -115,7 +115,7 @@ id: first_example
Let's add new <code>lightswitch_model.yml</code> file containing
our model's static configuration in YAML
into <code>src/main/java/examples</code> folder with the following
content:
</p>
- <pre class="brush: js, highlight: [1, 14, 21, 28]">
+ <pre class="brush: js, highlight: [14, 21, 28]">
id: "nlpcraft.lightswitch.ex"
name: "Light Switch Example Model"
version: "1.0"
@@ -152,8 +152,7 @@ id: first_example
- "no <LIGHT>"
</pre>
<p>
- Notice the model ID <code>nlpcraft.lightswitch.ex</code> as well
as semantic model elements
- that we'll use later:
+ Notice three semantic model elements that we'll use later in our
intent definition (lines 14, 21, and 28):
</p>
<ul>
<li><code>ls:loc</code></li>
@@ -162,21 +161,34 @@ id: first_example
</ul>
<p>
Model element <code>ls:loc</code> defines a location where we want
to control the lights. Model
- elements <code>ls:on</code> and <code>ls:off</code> defines
corresponding "on" and "off" lights
+ elements <code>ls:on</code> and <code>ls:off</code> define
corresponding "on" and "off" lights
actions. We'll use these elements in our model's intent-based
matching logic.
</p>
<p>
- Next let's go ahead and add model's logic. Create new
<code>LightSwitchModel.scala</code> file along side
+ Next let's go ahead and add model's logic which we'll write in
Scala (this code can be converted to Java or Kotlin almost as is).
+ Create new <code>LightSwitchModel.scala</code> file along side
<code>lightswitch_model.json</code> configuration file and copy
the following model code into it:
</p>
- <pre class="brush: java, highlight: [7,9,10]">
-package examples;
+ <pre class="brush: java, highlight: [5, 6, 7, 21, 22]">
+package examples
-import org.apache.nlpcraft.model._
-import org.apache.nlpcraft.model.NCIntentTerm
+import org.apache.nlpcraft.model.{NCIntentTerm, _}
-class LightSwitchModel extends
NCModelFileAdapter("org/apache/nlpcraft/examples/lightswitch/lightswitch_model.yaml")
{
+class LightSwitchModel extends
NCModelFileAdapter("examples/lightswitch_model.yaml") {
@NCIntent("intent=ls conv=false term(act)={groups @@ 'act'} term(loc)={id
== 'ls:loc'}*")
+ @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]
@@ -186,10 +198,11 @@ class LightSwitchModel extends
NCModelFileAdapter("org/apache/nlpcraft/examples/
if (locToks.isEmpty)
"entire house"
else
- locToks.map(_.getOriginalText).mkString(", ")
+
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}'.")
}
}
@@ -200,26 +213,44 @@ class LightSwitchModel extends
NCModelFileAdapter("org/apache/nlpcraft/examples/
</p>
<ul>
<li>
- On line 6 we use <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCModelFileAdapter.html">NCModelFileAdapter</a>
- adapter and load model static configuration from
<code>lightswitch_model.yml</code> file.
+ On line 5 we use <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCModelFileAdapter.html">NCModelFileAdapter</a>
+ to load its configuration from the external
<code>examples/lightswitch_model.yaml</code> YAML file.
</li>
<li>
Our data model uses intent-based matching of the user input.
Intent is a template and a callback for when
- a template is matched.
- Lines 7, 9 and 10 show the usage of
- <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/inteint/NCIntent.html">@NCIntent</a>
and
- <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/inteint/NCIntent.html">@NCIntentTerm</a>
- annotations that are used to connect the matching logic with a
callback method.
+ a template is matched against user input:
+ <ul>
+ <li>
+ Line 6 uses <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCIntent.html">@NCIntent</a>
+ annotation to define the intent (it can also be
defined in the external model definition).
+ The intent defined here matches
+ two parts: first should be any token belonging to
<code>act</code> group (i.e. "on" or "off" action),
+ and the second should be a zero or more tokens with ID
equal to <code>ls:loc</code> (i.e. optional list of locations).
+ </li>
+ <li>
+ Line 7 uses <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCIntentSample.html">@NCIntentSample</a>
+ annotation that provides a list of sample inputs that
should satisfy the intent above. Although this
+ annotation is optional, the list of samples serves two
important purposes:
+ <ul>
+ <li>
+ It provides documentation for the intent by
providing examples of input sentences that this intent should match on.
+ </li>
+ <li>
+ It can also be used for auto-testing of the
model. See below the <a href="#test">testing</a>
+ section for details.
+ </li>
+ </ul>
+ </li>
+ </ul>
</li>
<li>
- The intent defined through <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/inteint/NCIntent.html">@NCIntent</a>
annotation matches
- two parts: first should be any token belonging to
<code>act</code> group (i.e. "on" or "off" action),
- and the second should be a zero or more tokens with ID equal
to <code>ls:loc</code> (i.e. optional list of locations).
+ Lines 21 and 22 use <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCIntent.html">@NCIntentTerm</a>
+ annotations to connect the matched result with a callback
method formal parameters.
</li>
<li>
- If and when our intent is matched the method
<code>onMatch(...)</code> on line 8 is invoked. It simply
+ When our intent is selected as a matching winner the method
<code>onMatch(...)</code> on line 20 is invoked. It simply
returns a text response that indicates the light status at a
requested location. That's where you can
- also add <a target=_
href="https://developer.apple.com/homekit/";>HomeKit</a>,
+ also add <a target=_
href="https://developer.apple.com/homekit/";>HomeKit</a>,
<a href="https://www.arduino.cc/"; target=_>Ardunio</a> or
other integrations to make a real
lightswitch in your home.
</li>
@@ -240,7 +271,7 @@ class LightSwitchModel extends
NCModelFileAdapter("org/apache/nlpcraft/examples/
<b>VM arguments:</b>
<code>-Dconfig.override_with_env_vars=true</code>
</li>
<li>
- <b>Environment variable:</b>
<code>CONFIG_FORCE_nlpcraft_probe_models.0=org.apache.nlpcraft.examples.lightswitch.LightSwitchModel</code>
+ <b>Environment variable:</b>
<code>CONFIG_FORCE_nlpcraft_probe_models.0=examples.LightSwitchModel</code>
</li>
<li>
<b>Program arguments: </b> <code>-probe</code>
@@ -258,7 +289,7 @@ class LightSwitchModel extends
NCModelFileAdapter("org/apache/nlpcraft/examples/
has been successfully loaded and probe started.
</p>
</section>
- <section>
+ <section id="test">
<h3 class="section-title">Start REST Server</h3>
<p>
REST server listens for requests from client applications and
routes them to the requested data models
@@ -287,6 +318,15 @@ class LightSwitchModel extends
NCModelFileAdapter("org/apache/nlpcraft/examples/
<section>
<h3 class="section-title">Testing</h3>
<p>
+ Remember the <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCIntentSample.html">@NCIntentSample</a>
+ annotation we have used in our Scala code next to intent
definition? Auto-testing utility is relying on it.
+
+
+
+
+
+
+
NLPCraft comes with easy to use <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/test/package-summary.html">test
framework</a> for data models that can be used with
any unit testing framework like JUnit or ScalaTest. It is
essentially a simplified
version of Java REST client that is custom designed for data model
testing.
diff --git a/server-and-probe.html b/server-and-probe.html
index 31204cb..3bc2a66 100644
--- a/server-and-probe.html
+++ b/server-and-probe.html
@@ -308,11 +308,10 @@ id: server_and_probe
| Down-Link | localhost:8202 |
| Up-Link | localhost:8201 |
+-----------------+--------------------------------------------------+
- | Models | org.apache.nlpcraft.examples.alarm.AlarmModel
|
- | | org.apache.nlpcraft.examples.echo.EchoModel
|
- | |
org.apache.nlpcraft.examples.helloworld.HelloWorldModel |
- | | org.apache.nlpcraft.examples.time.TimeModel
|
- | | org.apache.nlpcraft.examples.weather.WeatherModel
|
+ | Models | org.apache.nlpcraft.examples.alarm.AlarmModel |
+ | | org.apache.nlpcraft.examples.echo.EchoModel |
+ | | org.apache.nlpcraft.examples.time.TimeModel |
+ | | org.apache.nlpcraft.examples.weather.WeatherModel|
+-----------------+--------------------------------------------------+
| Lifecycle | |
| JARs Folder | |
@@ -327,7 +326,6 @@ id: server_and_probe
+================================================================================+
| nlpcraft.alarm.ex | Alarm Example Model | 1.0 | 1
| 419 |
| nlpcraft.weather.ex | Weather Example Model | 1.0 | 3
| 9045 |
- | nlpcraft.helloworld.ex | HelloWorld Example Model | 1.0 | 0
| 0 |
| nlpcraft.time.ex | Time Example Model | 1.0 | 1
| 432 |
| nlpcraft.echo.ex | Echo Example Model | 1.0 | 0
| 0 |
+--------------------------------------------------------------------------------+
@@ -363,10 +361,10 @@ id: server_and_probe
<p>
Default configuration is available in
<code>build/<b>nlpcraft.conf</b></code> file and it is extensively documented.
It has subsections
for the server and probe configuration. When server and the probe
use different files these whole sections should be
- placed into an individual file:
+ placed into an individual files:
</p>
<p>
- Server configuration file:
+ Server configuration file (e.g. <code>server_nlpcraft.conf</code>):
</p>
<pre class="brush: js">
nlpcraft {
@@ -376,7 +374,7 @@ nlpcraft {
}
</pre>
<p>
- Probe configuration file:
+ Probe configuration file (e.g. <code>probe_nlpcraft.conf</code>):
</p>
<pre class="brush: js">
nlpcraft {
