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 f879be5 WIP Javadoc.
f879be5 is described below
commit f879be564d9f9d560256d72251b5d3db1a4e30f4
Author: Aaron Radzinski <[email protected]>
AuthorDate: Mon Mar 28 13:51:39 2022 -0700
WIP Javadoc.
---
.../scala/org/apache/nlpcraft/NCConversation.java | 49 +++++++++++++++++++---
.../nlpcraft/internal/impl/NCModelClientImpl.scala | 2 +-
.../intent/matcher/NCIntentSolverManager.scala | 2 +-
3 files changed, 45 insertions(+), 8 deletions(-)
diff --git a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCConversation.java
b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCConversation.java
index f997aea..ab0fbb3 100644
--- a/nlpcraft/src/main/scala/org/apache/nlpcraft/NCConversation.java
+++ b/nlpcraft/src/main/scala/org/apache/nlpcraft/NCConversation.java
@@ -21,7 +21,15 @@ import java.util.List;
import java.util.function.Predicate;
/**
- * Conversation container. This container is unique for user and data model
pair.
+ * Conversation container. Conversation is essentially a container for
everything that should be implicitly remembered
+ * during the active, ongoing conversation and forgotten once the conversation
stops. Conversation contains the
+ * following elements:
+ * <ul>
+ * <li>List of entities defining a "short-term-memory (STM)" of this
conversation.</li>
+ * <li>Chronological list of previously matched intents.</li>
+ * <li>Auto-expiring user data.</li>
+ * </ul>
+ * Note that the conversation is unique for given combination of user and data
model.
* <p>
* Conversation management is based on idea of a short-term-memory (STM). STM
can be viewed as a condensed
* short-term history of the input for a given user and data model. Every
submitted user request that wasn't
@@ -30,19 +38,40 @@ import java.util.function.Predicate;
* expire (i.e. context is "forgotten") after a certain period of time and/or
based on the depth of the
* conversation since the last mention.
* <p>
- * You can also maintain user state-machine between requests using
converasation's session. Conversation's session is
+ * You can also maintain user state-machine between requests using
conversation's session. Conversation's {@link #getData() data} is
* a mutable thread-safe container that can hold any arbitrary user data while
supporting the same expiration logic as
* the rest of the conversation elements (i.e. tokens and previously matched
intent IDs).
+ * <p>
+ * Conversation expiration policy is configured by two configuration
properties:
+ * <ul>
+ * <li>{@link NCModelConfig#getConversationDepth()}</li>
+ * <li>{@link NCModelConfig#getConversationTimeout()}</li>
+ * </ul>
+ *
+ * @see NCContext#getConversation()
+ * @see NCModelConfig#getConversationDepth()
+ * @see NCModelConfig#getConversationTimeout()
*/
public interface NCConversation {
/**
+ * Gets user-defined as a mutable thread-safe property container. Note tha
this container has the same expiration
+ * policy as the conversation it belongs to. Specifically, this returned
container will be cleared when the
+ * conversation gets cleared automatically (by timeout or depth) or
manually.
*
- * @return
+ * @return User-defined conversation data container. Can be empty but
never {@code null}.
*/
- NCPropertyMap getSession();
+ NCPropertyMap getData();
/**
- *
+ * Gets an ordered list of entities stored in the conversation STM for the
current user and data model. Entities in
+ * the returned list are ordered by their conversational depth, i.e. the
entities from more recent requests appear
+ * before entities from older requests.
+ * <p>
+ * Note that specific rules by which STM operates are undefined for the
purpose of this function (i.e. callers
+ * should not rely on any observed behavior of how STM stores and evicts
its content).
+ *
+ * @return List of entities for this conversation's STM. The list can be
empty which indicates that conversation
+ * is brand new or expired - but never {@code null}.
*/
List<NCEntity> getStm();
@@ -55,7 +84,15 @@ public interface NCConversation {
List<NCDialogFlowItem> getDialogFlow();
/**
- *
+ * Removes all entities satisfying given predicate from the conversation
STM. This is particularly useful when the
+ * logic processing the user input makes an implicit assumption not
present in the user input itself. Such
+ * assumption may alter the conversation (without having an explicit
entities responsible for it) and therefore
+ * this method can be used to remove "stale" entities from conversation
STM.
+ * <p>
+ * For example, in some cases the intent logic can assume the user current
location as an implicit geographical
+ * location and therefore all existing geographical-related entities
should be removed from the conversation
+ * STM to maintain correct context.
+ *
* @param filter Entity remove filter.
*/
void clearStm(Predicate<NCEntity> filter);
diff --git
a/nlpcraft/src/main/scala/org/apache/nlpcraft/internal/impl/NCModelClientImpl.scala
b/nlpcraft/src/main/scala/org/apache/nlpcraft/internal/impl/NCModelClientImpl.scala
index 87b8983..30913c0 100644
---
a/nlpcraft/src/main/scala/org/apache/nlpcraft/internal/impl/NCModelClientImpl.scala
+++
b/nlpcraft/src/main/scala/org/apache/nlpcraft/internal/impl/NCModelClientImpl.scala
@@ -90,7 +90,7 @@ class NCModelClientImpl(mdl: NCModel) extends LazyLogging:
val conv: NCConversation =
new NCConversation:
- override val getSession: NCPropertyMap = convHldr.getUserData
+ override val getData: NCPropertyMap = convHldr.getUserData
override val getStm: JList[NCEntity] =
convHldr.getEntities.asJava
override val getDialogFlow: JList[NCDialogFlowItem] =
dlgMgr.getDialogFlow(userId).asJava
override def clearStm(filter: Predicate[NCEntity]): Unit =
convHldr.clear(filter)
diff --git
a/nlpcraft/src/main/scala/org/apache/nlpcraft/internal/intent/matcher/NCIntentSolverManager.scala
b/nlpcraft/src/main/scala/org/apache/nlpcraft/internal/intent/matcher/NCIntentSolverManager.scala
index 74cacda..afe36a9 100644
---
a/nlpcraft/src/main/scala/org/apache/nlpcraft/internal/intent/matcher/NCIntentSolverManager.scala
+++
b/nlpcraft/src/main/scala/org/apache/nlpcraft/internal/intent/matcher/NCIntentSolverManager.scala
@@ -412,7 +412,7 @@ class NCIntentSolverManager(dialog: NCDialogFlowManager,
intents: Map[NCIDLInten
val intentGrps = mutable.ArrayBuffer.empty[TermEntitiesGroup]
var abort = false
var lastTermMatch: TermMatch = null
- val sess = ctx.getConversation.getSession // Conversation metadata
(shared across all terms).
+ val sess = ctx.getConversation.getData // Conversation metadata
(shared across all terms).
val convMeta = sess.keysSet().asScala.map(k => k ->
sess.get(k).asInstanceOf[Object]).toMap
val ents = senEnts.map(_.entity)
