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 1347200 WIP.
1347200 is described below
commit 1347200c3c334488522383dcdc8e3cf72efabc66
Author: Aaron Radzinski <[email protected]>
AuthorDate: Mon Apr 5 15:06:04 2021 -0700
WIP.
---
data-model.html | 4 +--
intent-matching.html | 94 +++++++++++++++++++++++++++++++++++++++++++++++++---
2 files changed, 91 insertions(+), 7 deletions(-)
diff --git a/data-model.html b/data-model.html
index c1a6f3b..130424b 100644
--- a/data-model.html
+++ b/data-model.html
@@ -276,7 +276,7 @@ public class AlarmModel extends NCModelFileAdapter {
own data model in the most uses cases.
</p>
</div>
- <h3 class="section-title">Deployment</h3>
+ <h3 id="deployment" class="section-title">Deployment</h3>
<p>
Data models get <a href="/server-and-probe.html">deployed</a> to
and hosted by the data probes - a lightweight
container whose job is to host data models and securely transfer
requests between REST server and the data
@@ -288,7 +288,7 @@ public class AlarmModel extends NCModelFileAdapter {
the data probe. Note also that data probe can be started in
embedded mode, i.e. it can be started
from within an existing JVM process like user application.
</p>
- <h3 class="section-title">Callbacks</h3>
+ <h3 id="callbacks" class="section-title">Callbacks</h3>
<p>
There are two lifecycle callbacks on
<a target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCModel.html">NCModel</a> interface
diff --git a/intent-matching.html b/intent-matching.html
index 296d8a7..2a44013 100644
--- a/intent-matching.html
+++ b/intent-matching.html
@@ -157,7 +157,7 @@ id: intent_matching
intent=xa
flow="^(?:xx)(^:zz)*$"
meta={'a': 42, 'b': {'Москва': [1, 2, 3]}}
- term(a)={month() >= 6 && !(tok_id()) != "z`" &&
meta_model('a') == 100_500}[1,3]
+ term(a)={month() >= 6 && !(tok_id()) != "z" &&
meta_model('a') == 100_500}[1,3]
term(b)~{
@a = meta_model('a')
@list = list(1, 2, 3, 4)
@@ -255,7 +255,7 @@ id: intent_matching
</p>
</dd>
<dt>
- <code>term(a)={month() >= 6 && !(tok_id()) != "z`" &&
meta_model('a') == 100_500}[1,3]</code> <sup><small>line 4</small></sup><br>
+ <code>term(a)={month() >= 6 && !(tok_id()) != "z" &&
meta_model('a') == 100_500}[1,3]</code> <sup><small>line 4</small></sup><br>
<code>term(b)~{</code> <sup><small>line
5</small></sup><br>
<code style="padding-left: 20px">@a =
meta_model('a')</code><br>
<code style="padding-left: 20px">@list = list(1, 2, 3,
4)</code><br>
@@ -272,14 +272,14 @@ id: intent_matching
term - only tokens from the current request will
be considered.
</p>
<p>
- A term is matched if its token predicate return
true result.
+ A term is matched if its token predicate returns
true result.
The matched term represents one or more tokens,
sequential or not, that were detected in the user input. Intent has a list of
terms
(always at least one) that all have to be matched
in the user input for the intent to match. Note that term
can be optional if its min quantifier is zero.
Whether or not the order of the terms is important
for matching is governed by intent's
<code>ordered</code> parameter.
</p>
<p>
- Term ID (<code>a</code> and <code>b</code>) is
optional, and when provided, is required by
+ Term ID (<code>a</code> and <code>b</code>) is
optional. It is only required by
<a href="#binding"><code>@NCIntentTerm</code></a>
annotation to link term's tokens to a formal
parameter of the callback method. Note that term ID follows
the same lexical rules as intent ID.
@@ -301,9 +301,67 @@ id: intent_matching
grammar including precedence rules,
brackets and logical combinators. Most of the functionality
expressed in these expressions is provided
by <a href="#idl_functions">IDL functions</a>.
</p>
+ <p>
+ IDL expression is mostly defined by the
following ANTLR4 grammar productions that closely
+ matches Java-like expression style:
+ </p>
+ <pre class="brush: java">
+ expr
+ // NOTE: order of productions defines
precedence.
+ : op=(MINUS | NOT) expr # unaryExpr
+ | LPAR expr RPAR # parExpr
+ | expr op=(MULT | DIV | MOD) expr #
multDivModExpr
+ | expr op=(PLUS | MINUS) expr #
plusMinusExpr
+ | expr op=(LTEQ | GTEQ | LT | GT) expr
# compExpr
+ | expr op=(EQ | NEQ) expr # eqNeqExpr
+ | expr op=(AND | OR) expr # andOrExpr
+ | atom # atomExpr
+ | FUN_NAME LPAR paramList? RPAR #
callExpr
+ | AT id # varRef
+ ;
+ vars
+ : varDecl
+ | vars varDecl
+ ;
+ varDecl: AT id ASSIGN expr;
+ paramList
+ : expr
+ | paramList COMMA expr
+ ;
+ atom
+ : NULL // 'null'.
+ | INT REAL? EXP? // Numeric (int and
real).
+ | BOOL // 'true' or 'false'
+ | qstring // Single or double quoted
string.
+ ;
+ </pre>
+ <div class="bq info">
+ <p>
+ <b>NOTE:</b> while term variable
initialization expressions can have any type - but the
+ term's expression itself, i.e. the
last expression in the term's body, <em>must evaluate to a boolean result
only.</em>
+ Failure to do so will result in a
runtime exception during intent evaluation. Note also
+ that such errors cannot be detected
during intent compilation phase.
+ </p>
+ </div>
</li>
<li>
<p><b>User-Defined Callback</b></p>
+ <p>
+ In this case the term's body is defined as
a callback in a form <code>/x.y.z.Cass#method/</code>,
+ where <code>x.y.z.Class</code> should be a
fully qualified name of the class where callback is defined, and
+ <code>method</code> must be the name of
the callback method. This method should take one
+ parameter of type <code><a
target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCTokenPredicateContext.html">NCTokenPredicateContext</a></code>
+ and return an instance of <code><a
target="javadoc"
href="/apis/latest/org/apache/nlpcraft/model/NCTokenPredicateResult.html">NCTokenPredicateResult</a></code>
+ as its result.
+ </p>
+ <p>
+ Class name is optional in which case the
model class will be used by default. Note that if the custom class
+ is in fact specified, the instance of this
class will be created for each term evaluation.
+ This class must have a no-arg constructor
to instantiate via standard Java reflection
+ and its creation must be as light as
possible to avoid performance degradation during its
+ instantiation. For this reasons it is
recommended to have user-defined term callback
+ on the model class itself which will avoid
instantiating the class on each term evaluation.
+ </p>
</li>
</ul>
<p>
@@ -317,6 +375,11 @@ id: intent_matching
<li>No quantifier defaults to
<code>[1,1]</code></li>
</ul>
</dd>
+ <dt>
+ <code>fragment(frag1)</code> <sup><small>line 16
</small></sup><br>
+ </dt>
+ <dd>
+ </dd>
</dl>
</li>
<li>
@@ -399,12 +462,33 @@ id: intent_matching
</pre>
</li>
</ul>
+ <h2 class="section-sub-title">Intent Lifecycle</h2>
+ <p>
+ During NLPCraft data probe start it scans the models provided in
its configuration for the intents. The
+ scanning process goes through JSON/YAML external configurations as
well as model classes when looking
+ for IDL intents. All found intents are compiled into an internal
representation before the data probe
+ completes its start up sequence.
+ </p>
+ <p>
+ Note that not all intents problems can be detected at the
compilation phase, and probe can start with intents
+ not being completely validated. For example, each term in the
intent must evaluate to a boolean result. This can
+ only be checked at runtime. Another example is the number and the
types of parameters passed into IDL function
+ which can only be checked at runtime as well.
+ </p>
+ <p>
+ Intents are compiled only once during the data probe start up
sequence and cannot be re-compiled
+ without data probe restart. Model logic, however, can affect the
intent behavior through <a href="/data-model.html#callbacks">model
callbacks</a>,
+ <a target=_
href="/apis/latest/org/apache/nlpcraft/model/NCModelView.html#getMetadata()">model
metadata</a>,
+ user and company metadata, as well as request data all of which
can change at runtime and
+ are accessible through IDL functions.
+ </p>
<h2 id="idl_syntax_highlight" class="section-sub-title">IDL Syntax
Highlighting</h2>
</section>
<section>
<h2 id="binding" class="section-title">Binding Intent</h2>
<p>
- Intents are bound to their callback methods using the following
Java annotations:
+ IDL defined intents must be bound to their callback methods. This
binding is accomplished using the
+ following Java annotations:
</p>
<table class="gradient-table">
<thead>
