You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nlpcraft.apache.org by ar...@apache.org on 2022/09/19 20:32:25 UTC
[incubator-nlpcraft] branch master updated: WIP on scaladoc.
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 8e05cd05 WIP on scaladoc.
8e05cd05 is described below
commit 8e05cd0592aa4cb5022dddbe7b64e77f2187e7ab
Author: Aaron Radzinski <ar...@datalingvo.com>
AuthorDate: Mon Sep 19 13:32:18 2022 -0700
WIP on scaladoc.
---
.../examples/lightswitch/LightSwitchFrModel.scala | 2 +-
.../lightswitch/LightSwitchScalaModel.scala | 2 +-
.../main/scala/org/apache/nlpcraft/NCModel.scala | 67 ++++++++--------------
.../scala/org/apache/nlpcraft/NCModelAdapter.scala | 5 +-
.../scala/org/apache/nlpcraft/NCModelClient.scala | 28 +++++----
.../scala/org/apache/nlpcraft/NCPipeline.scala | 4 +-
.../scala/org/apache/nlpcraft/NCRejection.scala | 12 ++--
7 files changed, 54 insertions(+), 66 deletions(-)
diff --git a/nlpcraft-examples/lightswitch-fr/src/main/scala/org/apache/nlpcraft/examples/lightswitch/LightSwitchFrModel.scala b/nlpcraft-examples/lightswitch-fr/src/main/scala/org/apache/nlpcraft/examples/lightswitch/LightSwitchFrModel.scala
index 5f8c0e32..a80a2ec3 100644
--- a/nlpcraft-examples/lightswitch-fr/src/main/scala/org/apache/nlpcraft/examples/lightswitch/LightSwitchFrModel.scala
+++ b/nlpcraft-examples/lightswitch-fr/src/main/scala/org/apache/nlpcraft/examples/lightswitch/LightSwitchFrModel.scala
@@ -37,7 +37,7 @@ import java.util
* </ul>
* You can easily modify intent callbacks to perform the actual light switching using
* HomeKit or Arduino-based controllers.
- * <p>
+ *
* See 'README.md' file in the same folder for running and testing instructions.
*/
class LightSwitchFrModel extends NCModelAdapter(
diff --git a/nlpcraft-examples/lightswitch/src/main/scala/org/apache/nlpcraft/examples/lightswitch/LightSwitchScalaModel.scala b/nlpcraft-examples/lightswitch/src/main/scala/org/apache/nlpcraft/examples/lightswitch/LightSwitchScalaModel.scala
index df159909..801a4621 100644
--- a/nlpcraft-examples/lightswitch/src/main/scala/org/apache/nlpcraft/examples/lightswitch/LightSwitchScalaModel.scala
+++ b/nlpcraft-examples/lightswitch/src/main/scala/org/apache/nlpcraft/examples/lightswitch/LightSwitchScalaModel.scala
@@ -33,7 +33,7 @@ import org.apache.nlpcraft.nlp.parsers.{NCOpenNLPTokenParser, NCSemanticEntityPa
* </ul>
* You can easily modify intent callbacks to perform the actual light switching using
* HomeKit or Arduino-based controllers.
- * <p>
+ *
* See 'README.md' file in the same folder for running and testing instructions.
*/
class LightSwitchScalaModel extends NCModelAdapter(
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModel.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModel.scala
index 8e5a1de1..28c108fb 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModel.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModel.scala
@@ -18,51 +18,26 @@
package org.apache.nlpcraft
/**
- * User data model.
+ * Data model.
*
- * Data model is a holder for user-defined NLP processing logic. NLPCraft employs model-as-a-code approach where
- * entire data model is an implementation of this interface which can be simply developed using any JVM programming
- * language like Java, Scala, Kotlin, or Groovy.
- *
- * The instance of this interface is passed to [[NCModelClient]] class and contains:
+ * Data model is a key entity in NLPCraft and contains:
* - Model [[NCModel.getConfig configuration]].
* - Model [[NCModel.getPipeline processing pipeline]].
* - Life-cycle callbacks.
*
- * Note that this model-as-a-code approach natively supports any software life cycle tools and frameworks like various
+ * NLPCraft employs model-as-a-code approach where entire data model is an implementation of just this interface.
+ * The instance of this interface is passed to [[NCModelClient]] class.
+ * Note that the model-as-a-code approach natively supports any software life cycle tools and frameworks like various
* build tools, CI/SCM tools, IDEs, etc. You don't need any additional tools to manage
- * some aspects of your data models - your entire model and all of its components are part of your project's source code.
- *
- * In most cases, one would use a convenient [[NCModelAdapter]] adapter to implement this interface. Here's a snippet
- * of the user data model from LightSwitch example:
- * {{{
- * public class LightSwitchJavaModel extends NCModelAdapter {
- * public LightSwitchJavaModel() {
- * super(
- * new NCModelConfig("nlpcraft.lightswitch.java.ex", "LightSwitch Example Model", "1.0"),
- * new NCPipelineBuilder().withSemantic("en", "lightswitch_model.yaml").build()
- * );
- * }
- *
- * @NCIntent("intent=ls term(act)={has(ent_groups, 'act')} term(loc)={# == 'ls:loc'}*")
- * NCResult onMatch(
- * @NCIntentTerm("act") NCEntity actEnt,
- * @NCIntentTerm("loc") List<NCEntity> locEnts
- * ) {
- * String status=actEnt.getId().equals("ls:on")?"on":"off";
- * String locations=locEnts.isEmpty() ? "entire house":
- * locEnts.stream().map(NCEntity::mkText).collect(Collectors.joining(", "));
+ * some aspects of your data models - your entire model and all of its components are part of your project's
+ * source code.
*
- * return new NCResult(
- * "Lights are [" + status + "] in [" + locations.toLowerCase() + "].",
- * NCResultType.ASK_RESULT
- * );
- * }
- * }
- * }}}
+ * Note that in most cases, one would use a convenient [[NCModelAdapter]] adapter to implement this interface.
*
* @see [[NCModelClient]]
* @see [[NCModelAdapter]]
+ * @see [[NCModelConfig]]
+ * @see [[NCPipeline]]
*/
trait NCModel:
/**
@@ -82,16 +57,20 @@ trait NCModel:
/**
* A callback to accept or reject a parsed variant. This callback is called before any other callbacks at the
* beginning of the processing pipeline, and it is called for each parsed variant.
- * <p>
+ *
* Note that a given input query can have one or more possible different parsing variants. Depending on model
* configuration an input query can produce hundreds or even thousands of parsing variants that can significantly
* slow down the overall processing. This method allows to filter out unnecessary parsing variants based on
* variety of user-defined factors like number of entities, presence of a particular entity in the variant, etc.
- * <p>
+ *
* By default, this method accepts all variants (returns `true`).
*
+ * NOTE: this the pipeline has its own mechanism to filter variants via [[NCPipeline.getVariantFilter]] method and
+ * class [[NCVariantFilter]].
+ *
* @param vrn A parsing variant to accept or reject.
- * @return {@code True} to accept variant for further processing, `false` otherwise.
+ * @return `True` to accept variant for further processing, `false` otherwise.
+ * @see [[NCVariantFilter]]
*/
def onVariant(vrn: NCVariant) = true
@@ -101,7 +80,7 @@ trait NCModel:
* called, i.e. right before the intent matching is performed. It's called always once per input query processing.
* Typical use case for this callback is to perform logging, debugging, statistic or usage collection, explicit
* update or initialization of conversation context, security audit or validation, etc.
- * <p>
+ *
* Default implementation returns `null`.
*
* @param ctx Input query context.
@@ -120,12 +99,12 @@ trait NCModel:
* parsing variants will be matched against all declared intents again. Returning `false` allows this
* method to alter the state of the model (like soft-reset conversation or change metadata) and force the
* full re-evaluation of the parsing variants against all declared intents.
- * <p>
+ *
* Note that user logic should be careful not to induce infinite loop in this behavior.
* Note that this callback may not be called at all based on the return value of {@link # onContext ( NCContext )} callback.
* Typical use case for this callback is to perform logging, debugging, statistic or usage collection, explicit
* update or initialization of conversation context, security audit or validation, etc.
- * <p>
+ *
* By default, this method returns `true`.
*
* @param im Intent match context - the same instance that's passed to the matched intent callback.
@@ -146,7 +125,7 @@ trait NCModel:
* Note that this callback may not be called at all, and if called - it's called only once. Typical use case
* for this callback is to perform logging, debugging, statistic or usage collection, explicit update or
* initialization of conversation context, security audit or validation, etc.
- * <p>
+ *
* Default implementation is a no-op returning `null`.
*
* @param im Intent match context - the same instance that's passed to the matched intent callback
@@ -165,7 +144,7 @@ trait NCModel:
* and if called - it's called only once. Typical use case for this callback is to perform logging, debugging,
* statistic or usage collection, explicit update or initialization of conversation context, security audit or
* validation, etc.
- * <p>
+ *
* Default implementation is a no-op returning `null`.
*
* @param ctx Optional intent match context - the same instance that's passed to the matched intent callback
@@ -183,7 +162,7 @@ trait NCModel:
* not be called at all, and if called - it's called only once. Typical use case for this callback is
* to perform logging, debugging, statistic or usage collection, explicit update or initialization of conversation
* context, security audit or validation, etc.
- * <p>
+ *
* Default implementation is a no-op returning `null`.
*
* @param ctx Intent match context - the same instance that's passed to the matched intent that produced this error.
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelAdapter.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelAdapter.scala
index e9f19729..933fbd43 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelAdapter.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelAdapter.scala
@@ -18,9 +18,10 @@
package org.apache.nlpcraft
/**
+ * Convenient adapter for [[NCModel]] interface.
*
- * @param cfg
- * @param pipeline
+ * @param cfg Model configuration.
+ * @param pipeline Model processing pipeline.
*/
class NCModelAdapter(cfg: NCModelConfig, pipeline: NCPipeline) extends NCModel:
override def getConfig: NCModelConfig = cfg
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelClient.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelClient.scala
index 69b129f8..540e2924 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelClient.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelClient.scala
@@ -34,8 +34,9 @@ import java.util.{Objects, UUID}
import scala.concurrent.ExecutionContext
/**
+ * Client API to issue requests again given model.
*
- * @param mdl
+ * @param mdl A data model to issue requests against.
*/
class NCModelClient(mdl: NCModel) extends LazyLogging, AutoCloseable:
verify()
@@ -47,6 +48,7 @@ class NCModelClient(mdl: NCModel) extends LazyLogging, AutoCloseable:
private val intentsMgr = NCIntentSolverManager(dlgMgr, convMgr, intents.map(p => p.intent -> p.function).toMap)
init()
+
/**
*
*/
@@ -78,6 +80,10 @@ class NCModelClient(mdl: NCModel) extends LazyLogging, AutoCloseable:
* @param typ
*/
private def ask0(txt: String, data: Map[String, Any], usrId: String, typ: NCIntentSolveType): Either[NCResult, NCMatchedCallback] =
+ require(txt != null, "Input text cannot be null.")
+ require(data != null, "Data cannot be null.")
+ require(usrId != null, "User id cannot be null.")
+
val plData = plMgr.prepare(txt, data, usrId)
val userId = plData.request.getUserId
@@ -105,15 +111,18 @@ class NCModelClient(mdl: NCModel) extends LazyLogging, AutoCloseable:
intentsMgr.solve(mdl, ctx, typ)
- /*
- * @param txt
- * @param data
- * @param usrId
+ /**
+ * Passing given input text to the model's pipeline.
+ *
+ * @param txt Text of the request.
+ * @param usrId ID of the user to associate with this request.
+ * @param data Optional data container that will be available to the intent matching IDL.
+ * @return Processing result. This method never returns `null`.
+ * @throws NCRejection An exception indicating a rejection of the user input. This exception is thrown
+ * automatically by the processing logic as well as can be thrown by the user from the intent callback.
+ * @throws NCException
*/
def ask(txt: String, usrId: String, data: Map[String, AnyRef] = Map.empty): NCResult =
- require(txt != null, "Input text cannot be null.")
- require(data != null, "Data cannot be null.")
- require(usrId != null, "User id cannot be null.")
ask0(txt, data, usrId, NCIntentSolveType.REGULAR).swap.toOption.get
/**
@@ -168,8 +177,5 @@ class NCModelClient(mdl: NCModel) extends LazyLogging, AutoCloseable:
* @param saveHist
*/
def debugAsk(txt: String, usrId: String, saveHist: Boolean, data: Map[String, AnyRef] = Map.empty): NCMatchedCallback =
- require(txt != null, "Input text cannot be null.")
- require(data != null, "Data cannot be null.")
- require(usrId != null, "User id cannot be null.")
import NCIntentSolveType.*
ask0(txt, data, usrId, if saveHist then SEARCH else SEARCH_NO_HISTORY).toOption.get
\ No newline at end of file
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCPipeline.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCPipeline.scala
index c8c1d61f..c1c24428 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCPipeline.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCPipeline.scala
@@ -19,7 +19,7 @@ package org.apache.nlpcraft
/**
* NLP processing pipeline for the input request. Pipeline is associated with the model.
- * <p>
+ *
* An NLP pipeline is a container for various processing components that take the input text at the beginning of the
* pipeline and produce the list of {@link NCEntity entities} at the end of the pipeline.
* Schematically the pipeline looks like this:
@@ -36,7 +36,7 @@ package org.apache.nlpcraft
* : List : | Validators |--+ | Enrichers |--+ | Parsers |--+
* *=========* +------------+ +-----------+ +---------+
* </pre>
- * <p>
+ *
* Pipeline has the following components:
* <ul>
* <li>
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRejection.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRejection.scala
index 6a08daff..a28e0605 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRejection.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRejection.scala
@@ -18,10 +18,12 @@
package org.apache.nlpcraft
/**
- * Exception to indicate that user input cannot be processed as is. This exception can be thrown from
- * intent callbacks.
- * <p>
+ * An exception to indicate a rejection of the user input. This exception is thrown automatically by the processing
+ * logic as well as can be thrown by the user from the intent callback.
+ *
* This exception typically indicates that user has not provided enough information in the input string
- * to have it processed automatically. In most cases this means that the user's input is either too short
- * or too simple, too long or too complex, missing required context, or unrelated to requested data model. */
+ * to have it processed automatically, without additional curation or modification. In most cases this means that
+ * the user's input is either too short or too simple, too long or too complex, missing required context, or unrelated
+ * to the requested data model.
+ */
class NCRejection(msg: String, cause: Throwable = null) extends RuntimeException(msg, cause)
\ No newline at end of file