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 8e1a67f WIP.
8e1a67f is described below
commit 8e1a67f9d2434b66bec7bedbb9312d643b381564
Author: Aaron Radzinski <[email protected]>
AuthorDate: Wed Mar 31 20:59:17 2021 -0700
WIP.
---
_layouts/default.html | 1 +
blogs/quick_intro_apache_nlpcraft.html | 2 +-
data-model.html | 2 +-
examples/light_switch.html | 2 +-
ext/syntaxhighlighter/scripts/shBrushIdl.js | 36 +++++++++++++
first-example.html | 4 +-
intent-matching.html | 81 ++++++++++++++++++++++++++---
7 files changed, 115 insertions(+), 13 deletions(-)
diff --git a/_layouts/default.html b/_layouts/default.html
index f273009..343032f 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -73,6 +73,7 @@ layout: compress
<script src="/ext/syntaxhighlighter/scripts/shBrushPlain.js"
type="text/javascript"></script>
<script src="/ext/syntaxhighlighter/scripts/shBrushJava.js"
type="text/javascript"></script>
<script src="/ext/syntaxhighlighter/scripts/shBrushScala.js"
type="text/javascript"></script>
+ <script src="/ext/syntaxhighlighter/scripts/shBrushIdl.js"
type="text/javascript"></script>
<script src="/ext/syntaxhighlighter/scripts/shBrushPython.js"
type="text/javascript"></script>
<script src="/ext/syntaxhighlighter/scripts/shBrushJScript.js"
type="text/javascript"></script>
<script async defer src="https://buttons.github.io/buttons.js";></script>
diff --git a/blogs/quick_intro_apache_nlpcraft.html
b/blogs/quick_intro_apache_nlpcraft.html
index c615044..c65a017 100644
--- a/blogs/quick_intro_apache_nlpcraft.html
+++ b/blogs/quick_intro_apache_nlpcraft.html
@@ -318,7 +318,7 @@ publish_date: November 16, 2020
<p>
Below is a full implementation of the data model in Scala (the same
implementation in Java or Kotlin is practically identical):
</p>
- <pre class="brush: java">
+ <pre class="brush: scala">
package org.apache.nlpcraft.examples.lightswitch
import org.apache.nlpcraft.model.{NCIntentTerm, _}
diff --git a/data-model.html b/data-model.html
index 0380010..8576a56 100644
--- a/data-model.html
+++ b/data-model.html
@@ -57,7 +57,7 @@ id: data_model
</nav>
<div class="tab-content">
<div class="tab-pane fade show active" id="scala-model-ex"
role="tabpanel">
- <pre class="brush: java">
+ <pre class="brush: scala">
package org.apache.nlpcraft.examples.lightswitch
import org.apache.nlpcraft.model.{NCIntentTerm, _}
diff --git a/examples/light_switch.html b/examples/light_switch.html
index 5a7b513..4c1bab7 100644
--- a/examples/light_switch.html
+++ b/examples/light_switch.html
@@ -153,7 +153,7 @@ intents:
<p>
Open <code>src/main/scala/demo/<b>LightSwitch.scala</b></code>
file and replace its content with the following code:
</p>
- <pre class="brush: java, highlight: [5, 6, 7, 21, 22, 34]">
+ <pre class="brush: scala, highlight: [5, 6, 7, 21, 22, 34]">
package demo
import org.apache.nlpcraft.model.{NCIntentTerm, _}
diff --git a/ext/syntaxhighlighter/scripts/shBrushIdl.js
b/ext/syntaxhighlighter/scripts/shBrushIdl.js
new file mode 100644
index 0000000..46f7c96
--- /dev/null
+++ b/ext/syntaxhighlighter/scripts/shBrushIdl.js
@@ -0,0 +1,36 @@
+;(function()
+{
+ // CommonJS
+ typeof(require) != 'undefined' ? SyntaxHighlighter =
require('shCore').SyntaxHighlighter : null;
+
+ function Brush()
+ {
+ // Contributed by Aaron Radzinski.
+
+ const keywords = 'flow fragment import intent meta ordered term';
+ const literals = 'false null true';
+ const symbols = '[\\[\\]{}*+?~=]+';
+ const fns = 'abs acos asin atan atn2 cbrt ceil comp_addr comp_city
comp_country comp_id comp_name comp_postcode comp_region comp_website cos cosh
count day_of_month day_of_week day_of_year degrees euler exp expm1 first floor
get has has_all has_any hour hypot if is_alpha is_alphanum is_alphanumspace
is_alphaspace is_empty is_num is_numspace is_whitespace json keys last length
list log log10 log1p lowercase max meta_company meta_conv meta_frag meta_intent
meta_model meta_part meta [...]
+
+ this.regexList = [
+ { regex: SyntaxHighlighter.regexLib.singleLineCComments, css:
'comments' }, // One line comments.
+ { regex: SyntaxHighlighter.regexLib.multiLineCComments, css:
'comments' }, // Multiline comments.
+ { regex: SyntaxHighlighter.regexLib.doubleQuotedString, css:
'string' }, // String.
+ { regex: SyntaxHighlighter.regexLib.singleQuotedString, css:
'string' }, // String.
+ { regex: /0x[a-f0-9]+|\d+(\.\d+)?/gi, css: 'value' }, // Numbers.
+ { regex: new RegExp(this.getKeywords(keywords), 'gm'), css:
'keyword' }, // Keywords.
+ { regex: new RegExp(this.getKeywords(literals), 'gm'), css:
'color1' }, // Literals.
+ { regex: /<|>|<=|>=|==|!=|&&|\|\|/g, css: 'color2' }, // Operators.
+ { regex: new RegExp(this.getKeywords(fns), 'gm'), css: 'functions'
}, // Functions.
+ { regex: new RegExp(symbols, 'gm'), css: 'color3' } // Symbols.
+ ];
+ }
+
+ Brush.prototype = new SyntaxHighlighter.Highlighter();
+ Brush.aliases = ['idl'];
+
+ SyntaxHighlighter.brushes.Idl = Brush;
+
+ // CommonJS.
+ typeof(exports) != 'undefined' ? exports.Brush = Brush : null;
+})();
diff --git a/first-example.html b/first-example.html
index 4b6a023..b7dc0c4 100644
--- a/first-example.html
+++ b/first-example.html
@@ -160,7 +160,7 @@ id: first_example
</nav>
<div class="tab-content">
<div class="tab-pane fade show active" id="nav-scala"
role="tabpanel">
- <pre class="brush: java, highlight: [5, 6, 7, 22, 23]">
+ <pre class="brush: scala, highlight: [5, 6, 7, 22, 23]">
package demo
import org.apache.nlpcraft.model.{NCIntentTerm, _}
@@ -251,7 +251,7 @@ public class LightSwitchJavaModel extends
NCModelFileAdapter {
</pre>
</div>
<div class="tab-pane fade show" id="nav-kotlin" role="tabpanel">
- <pre class="brush: java">
+ <pre class="brush: scala">
package demo
import org.apache.nlpcraft.model.*
diff --git a/intent-matching.html b/intent-matching.html
index 4feba5f..c1fd28b 100644
--- a/intent-matching.html
+++ b/intent-matching.html
@@ -37,9 +37,10 @@ id: intent_matching
provides this match between the input utterance and the
user-defined code is called an <em>intent</em>.
</p>
<p>
- The intent is a <em>declarative template</em> written in <a
href="#idl">Intent Definition Language</a> that describes
+ The intent refers to the goal that the end-user had in mind when
speaking or typing the input utterance.
+ The intent has a <em>declarative part or template</em> written in
<a href="#idl">Intent Definition Language</a> that describes
a particular form or type of the input utterance.
- Intent is also <a href="#annotations">bound</a> to a callback
method that will be called when that intent is detected as the best match
+ Intent is also <a href="#annotations">bound</a> to a callback
method that will be executed when that intent, i.e. its template, is detected
as the best match
for a given input utterance. A typical data model will have
multiple intents defined for each form of the expected user input
that model wants to react differently to.
</p>
@@ -61,16 +62,71 @@ id: intent_matching
</p>
<ul>
<li>
- <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCIntent.html">@NCIntent</a>
annotation
- takes a string as its parameter that should be a valid IDL
declaration.
+ <p>
+ <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCIntent.html">@NCIntent</a>
annotation
+ takes a string as its parameter that should be a valid IDL
declaration. For example, Scala snippet:
+ </p>
+ <pre class="brush: scala, highlight: [1, 2]">
+ @NCIntent("import('/opt/myproj/global_fragments.idl')")
+ @NCIntent("intent=act term(act)={has(tok_groups(), 'act')}
fragment(f1)")
+ def onMatch(
+ @NCIntentTerm("act") actTok: NCToken,
+ @NCIntentTerm("loc") locToks: List[NCToken]
+ ): NCResult = {
+ ...
+ }
+ </pre>
+
</li>
<li>
- External JSON/YAML <a href="/data-model.html#config">data
model configuration</a> can provide one or more
- IDL declarations.
+ <p>
+ External JSON/YAML <a href="/data-model.html#config">data
model configuration</a> can provide one or more
+ IDL declarations in <code>intents</code> field. For
example:
+ </p>
+ <pre class="brush: js, highlight: [7]">
+ {
+ "id": "nlpcraft.alarm.ex",
+ "name": "Alarm Example Model",
+ .
+ .
+ .
+ "intents": [
+ "import('/opt/myproj/global_fragments.idl')",
+ "import('/opt/myproj/my_intents.idl')",
+ "intent=alarm term~{tok_id()=='x:alarm'}"
+ ]
+ }
+ </pre>
</li>
<li>
External <code>*.idl</code> files have IDL declarations and
can be imported in any other places where
- IDL declarations are allowed.
+ IDL declarations are allowed. See <code>import()</code>
expression below. For example:
+ <pre class="brush: idl">
+ /*
+ * File 'my_intents.idl'.
+ * ======================
+ */
+
+ import('/opt/globals.idl') // Import global intents and
fragments.
+
+ // Fragments.
+ // ----------
+ fragment=buzz term~{tok_id() == 'x:alarm'}
+ fragment=when
+ term(nums)~{
+ // Term variables.
+ @type = meta_tok('nlpcraft:num:unittype')
+ @iseq = meta_tok('nlpcraft:num:isequalcondition')
+
+ tok_id() == 'nlpcraft:num' && @type != 'datetime'
&& @iseq == true
+ }[0,7]
+
+ // Intents.
+ // --------
+ intent=alarm
+ fragment(buzz)
+ fragment(when)
+ </pre>
</li>
</ul>
<h2 class="section-sub-title">IDL Grammar</h2>
@@ -94,6 +150,7 @@ id: intent_matching
<td><a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCIntent.html">@NCIntent</a></td>
<td>Callback method or model class</td>
<td>
+ <p>
When applied to a method this annotation allows to
defines IDL intent in-place on the method
serving as its callback.
This annotation can also be applied to a model's class
in which case it will just declare the intent
@@ -101,6 +158,14 @@ id: intent_matching
callback method will need to use <a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCIntentRef.html">@NCIntentRef</a>
annotation to actually bind it to the
declared intent above. Note that multiple intents can
be bound to the same callback method, but only
one callback method can be bound with a given intent.
+ </p>
+ <p>
+ This method is ideal for simple intents and quick
declaration right in the source code and has
+ all the benefits of having IDL be part of the
source code. However, multi-line IDL declaration can be awkward
+ to add and maintain depending on JVM language,
i.e. multi-line string literal support. In such
+ cases it is advisable to move IDL declarations
into separate <code>*.idl</code> file or files
+ and import them either in the JSON/YAML model or
at the model class level.
+ </p>
</td>
</tr>
<tr>
@@ -140,7 +205,7 @@ id: intent_matching
An intent from
<a href="examples/light_switch.html">Light Switch</a> Scala
example:
</p>
- <pre class="brush: java">
+ <pre class="brush: scala">
@NCIntent("intent=act term(act)={groups @@ 'act'}
term(loc)={trim(id) == 'ls:loc'}*")
@NCIntentSample(Array(
"Turn the lights off in the entire house.",
