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/12/04 19:52:54 UTC
[incubator-nlpcraft] branch master updated: 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 f2b59f7c Scaladoc.
f2b59f7c is described below
commit f2b59f7c39514a35996ff59b1f9501a069359d59
Author: Aaron Radzinski <ar...@datalingvo.com>
AuthorDate: Sun Dec 4 11:52:47 2022 -0800
Scaladoc.
---
.../scala/org/apache/nlpcraft/NCModelConfig.scala | 7 ++++
.../org/apache/nlpcraft/NCPropertyMapAdapter.scala | 12 ++----
.../scala/org/apache/nlpcraft/NCRejection.scala | 4 +-
.../main/scala/org/apache/nlpcraft/NCResult.scala | 37 +++++++++++------
.../scala/org/apache/nlpcraft/NCResultType.scala | 11 +++++-
.../main/scala/org/apache/nlpcraft/NCToken.scala | 46 ++++++++++++----------
.../org/apache/nlpcraft/NCTokenEnricher.scala | 28 +++++++------
.../scala/org/apache/nlpcraft/NCTokenParser.scala | 3 +-
.../org/apache/nlpcraft/NCTokenValidator.scala | 2 +-
.../main/scala/org/apache/nlpcraft/NCVariant.scala | 2 +-
.../org/apache/nlpcraft/NCVariantFilter.scala | 1 +
11 files changed, 93 insertions(+), 60 deletions(-)
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelConfig.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelConfig.scala
index 55ec4d7e..bfab503b 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelConfig.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCModelConfig.scala
@@ -23,7 +23,14 @@ import java.time.Duration
* Model configuration factory.
*/
object NCModelConfig:
+ /**
+ * Default conversation timeout is 60 mins.
+ */
val DFLT_CONV_TIMEOUT: Long = Duration.ofMinutes(60).toMillis
+
+ /**
+ * Default conversation depth is 3.
+ */
val DFLT_CONV_DEPTH = 3
/**
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCPropertyMapAdapter.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCPropertyMapAdapter.scala
index 2a56c952..b64da299 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCPropertyMapAdapter.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCPropertyMapAdapter.scala
@@ -21,27 +21,21 @@ import scala.jdk.CollectionConverters.*
import java.util.concurrent.ConcurrentHashMap
/**
- * Convenient adapter for {@link NCPropertyMap} interface. */
+ * Convenient adapter for [[NCPropertyMap]] interface. Note that this class uses
+ * [[ConcurrentHashMap]] for its implementation making its access thread-safe.
+ */
class NCPropertyMapAdapter extends NCPropertyMap:
private val map = new ConcurrentHashMap[String, Any]
override def apply[T](key: String): T = get(key).getOrElse(throw new NoSuchElementException(s"Key not found: $key"))
-
override def get[T](key: String): Option[T] =
map.get(key) match
case null => None
case x => Some(x.asInstanceOf[T])
-
override def put[T](key: String, obj: Any): T = map.put(key, obj).asInstanceOf[T]
-
override def putIfAbsent[T](key: String, obj: T): T = map.putIfAbsent(key, obj).asInstanceOf[T]
-
override def contains(key: String): Boolean = map.containsKey(key)
-
override def remove[T](key: String): T = map.remove(key).asInstanceOf[T]
-
override def remove(key: String, obj: Any): Boolean = map.remove(key, obj)
-
override def keysSet: Set[String] = map.keys().asScala.toSet
-
override def clear(): Unit = map.clear()
\ No newline at end of file
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRejection.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRejection.scala
index a28e0605..fc419afc 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRejection.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCRejection.scala
@@ -18,8 +18,8 @@
package org.apache.nlpcraft
/**
- * 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.
+ * An exception to indicate a rejection of the user input. This exception is either thrown automatically by the
+ * processing logic or 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, without additional curation or modification. In most cases this means that
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCResult.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCResult.scala
index 614060ce..1cac24f5 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCResult.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCResult.scala
@@ -18,14 +18,15 @@
package org.apache.nlpcraft
/**
- *
+ * Convenient factory for creating [[NCResult]] instances.
*/
object NCResult:
/**
- *
- * @param body
- * @param resultType
- * @param intentId
+ * Creates new result instance with given parameters.
+ *
+ * @param body Result body.
+ * @param resultType Result type.
+ * @param intentId Intent ID that produced the result.
*/
def apply(body: Any, resultType: NCResultType, intentId: String): NCResult =
new NCResult():
@@ -34,9 +35,10 @@ object NCResult:
def getIntentId: Option[String] = intentId.?
/**
- *
- * @param body
- * @param resultType
+ * Creates new result instance with given parameters. Note that intent ID will be set to `None`.
+ *
+ * @param body Result body.
+ * @param resultType Result type.
*/
def apply(body: Any, resultType: NCResultType): NCResult =
new NCResult():
@@ -45,8 +47,10 @@ object NCResult:
def getIntentId: Option[String] = None
/**
- *
- * @param body
+ * Creates new result instance with given parameters. Note that intent ID will be set to `None` and
+ * result type will be set to [[NCResultType.ASK_RESULT]].
+ *
+ * @param body Result body.
*/
def apply(body: Any): NCResult =
new NCResult() :
@@ -55,9 +59,20 @@ object NCResult:
def getIntentId: Option[String] = None
/**
- *
+ * Intent callback result.
*/
trait NCResult:
+ /**
+ * Body of the result.
+ */
def getBody: Any
+
+ /**
+ * Type of the result.
+ */
def getType: NCResultType
+
+ /**
+ * Optional ID of the intent, if any, that produced that result.
+ */
def getIntentId: Option[String]
\ No newline at end of file
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCResultType.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCResultType.scala
index 903b746e..fe936aae 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCResultType.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCResultType.scala
@@ -18,10 +18,17 @@
package org.apache.nlpcraft
/**
+ * Result types.
*
+ * @see [[NCResult.getType]]
*/
enum NCResultType:
/**
- * Final result is ready and Ask user back engaging in dialog.
+ * Result type indicating that the final result is ready.
*/
- case ASK_RESULT, ASK_DIALOG
\ No newline at end of file
+ case ASK_RESULT
+
+ /**
+ * Result type indicating that further information from the user is required.
+ */
+ case ASK_DIALOG
\ No newline at end of file
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCToken.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCToken.scala
index 9b140bc8..679307c8 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCToken.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCToken.scala
@@ -18,48 +18,52 @@
package org.apache.nlpcraft
/**
- * Represents a contiguous substring of the original input text produced by {@link NCTokenParser}.
- * A token is the result of {@link NCTokenParser tokenization} - the process of demarcating and classifying sections of a string of
- * input characters. See {@link NCPipeline} for documentation on the tokens place in the overall processing pipeline.
+ * Represents a contiguous substring of the original input text produced by [[NCTokenParser]].
+ * A token is the result of [[NCTokenParser tokenization]] - the process of demarcating and classifying
+ * sections of a string of input characters. See [[NCPipeline]] for documentation on the tokens place in the
+ * overall processing pipeline.
*
- * <span class="hdr">Metadata</span>
- * Note that both {@link NCToken} and {@link NCEntity} interfaces extend {@link NCPropertyMap} interface
+ * Note that both [[NCToken]] and [[NCEntity]] interfaces extend [[NCPropertyMap]] interface
* that allows them to store custom metadata properties. Parser, enrichers and validators for tokens
* and entities use this capability to store and check their properties in tokens and entities.
*
- * @see [[NCEntity
- * @see [[NCToken
- * @see [[NCTokenParser
- * @see [[NCTokenEnricher
- * @see [[NCTokenValidator
- * @see [[NCEntityParser
- * @see [[NCEntityEnricher
- * @see [[NCEntityValidator
- * @see [[NCEntityMapper */
+ * @see [[NCEntity]]
+ * @see [[NCToken]]
+ * @see [[NCTokenParser]]
+ * @see [[NCTokenEnricher]]
+ * @see [[NCTokenValidator]]
+ * @see [[NCEntityParser]]
+ * @see [[NCEntityEnricher]]
+ * @see [[NCEntityValidator]]
+ * @see [[NCEntityMapper]]
+ */
trait NCToken extends NCPropertyMap:
/**
* Gets the text of this token.
*
- * @return Text of this token. */
+ * @return Text of this token.
+ */
def getText: String
/**
- * Gets the index of this token in the list returned bu {@link NCTokenParser# tokenize ( String )} method.
+ * Gets the index of this token in the list returned by [[NCTokenParser.tokenize()]] method.
*
- * @return Zero-based index of this token in the list returned bu {@link NCTokenParser# tokenize ( String )} method. */
+ * @return Zero-based index of this token in the list returned by [[NCTokenParser.tokenize()]] method
+ */
def getIndex: Int
/**
* Gets the inclusive start position of this token's text in the original input text supplied to
- * {@link NCTokenParser# tokenize ( String )} method.
+ * [[NCTokenParser.tokenize()]] method.
*
- * @return Start position (inclusive) of this token's text in the original input text. */
+ * @return Start position (inclusive) of this token's text in the original input text.
+ */
def getStartCharIndex: Int
/**
* Gets the inclusive end position of this token's text in the original input text supplied to
- * {@link NCTokenParser# tokenize ( String )} method.
+ * [[NCTokenParser.tokenize()]] method.
*
* @return End position (inclusive) of this token's text in the original input text.
- * @return */
+ */
def getEndCharIndex: Int
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenEnricher.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenEnricher.scala
index d021343e..334796bf 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenEnricher.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenEnricher.scala
@@ -18,21 +18,25 @@
package org.apache.nlpcraft
/**
+ * Optional pipeline component that can enrich previously parsed [[NCToken tokens]].
+ * See [[NCPipeline]] for documentation on the token enricher place in the overall processing pipeline.
*
- * @see [[NCEntity
- * @see [[NCToken
- * @see [[NCTokenParser
- * @see [[NCTokenEnricher
- * @see [[NCTokenValidator
- * @see [[NCEntityParser
- * @see [[NCEntityEnricher
- * @see [[NCEntityValidator
- * @see [[NCEntityMapper */
+ * @see [[NCPipeline.getTokenEnrichers]]
+ * @see [[NCEntity]]
+ * @see [[NCToken]]
+ * @see [[NCTokenParser]]
+ * @see [[NCTokenValidator]]
+ * @see [[NCEntityParser]]
+ * @see [[NCEntityEnricher]]
+ * @see [[NCEntityValidator]]
+ * @see [[NCEntityMapper]]
+ */
trait NCTokenEnricher extends NCLifecycle:
/**
+ * Enriches, or otherwise modifies, previously parsed [[NCToken tokens]].
*
- * @param req
- * @param cfg
- * @param toks
+ * @param req Original request.
+ * @param cfg Model configuration.
+ * @param toks Previously parsed tokens to enrich.
*/
def enrich(req: NCRequest, cfg: NCModelConfig, toks: List[NCToken]): Unit
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenParser.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenParser.scala
index 4157181f..f251c890 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenParser.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenParser.scala
@@ -22,6 +22,7 @@ package org.apache.nlpcraft
* components of the processing [[NCPipeline pipeline]]. See [[NCPipeline]] for documentation on the token
* parser place in the overall processing pipeline.
*
+ * @see [[NCPipeline.getTokenParser]]
* @see [[NCEntity]]
* @see [[NCToken]]
* @see [[NCTokenParser]]
@@ -34,7 +35,7 @@ package org.apache.nlpcraft
*/
trait NCTokenParser:
/**
- * Splits given text into list of [[NCToken]] objects.
+ * Splits given text into list of [[NCToken tokens]].
*
* @param text Input text to split.
* @return List of split token. Can be empty but should never be `null`.
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenValidator.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenValidator.scala
index 546f9b73..f29ced61 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenValidator.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCTokenValidator.scala
@@ -23,11 +23,11 @@ package org.apache.nlpcraft
* components of the processing [[NCPipeline pipeline]]. See [[NCPipeline]] for documentation on the token
* parser place in the overall processing pipeline.
*
+ * @see [[NCPipeline.getTokenValidators]]
* @see [[NCEntity]]
* @see [[NCToken]]
* @see [[NCTokenParser]]
* @see [[NCTokenEnricher]]
- * @see [[NCTokenValidator]]
* @see [[NCEntityParser]]
* @see [[NCEntityEnricher]]
* @see [[NCEntityValidator]]
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCVariant.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCVariant.scala
index a77c3770..53a4fc09 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCVariant.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCVariant.scala
@@ -19,7 +19,7 @@ package org.apache.nlpcraft
/**
* A parsing variant is a list of entities defining one possible parsing of the input query. Note that a given user
- * input almost always has one or more possible different parsing variants. Furthermore, depending on the model
+ * input almost always has one or more possible parsing variants. Furthermore, depending on the model
* configuration a user input can produce hundreds and even thousands of parsing variants.
*
* Pipeline provides user-defined variant filter component [[NCVariantFilter]] to allow a programmatic filtration of
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCVariantFilter.scala b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCVariantFilter.scala
index 2cbe5f96..baf39bb2 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCVariantFilter.scala
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCVariantFilter.scala
@@ -24,6 +24,7 @@ package org.apache.nlpcraft
* components of the processing [[NCPipeline pipeline]]. See [[NCPipeline]] for documentation on the token
* parser place in the overall processing pipeline.
*
+ * @see [[NCPipeline.getVariantFilters]]
* @see [[NCEntity]]
* @see [[NCToken]]
* @see [[NCTokenParser]]