Package org.apache.nlpcraft.model

Interface NCConversation

  • All Superinterfaces:
    NCMetadata
    public interface NCConversation
extends NCMetadata
    Conversation container for specific user and data model.

    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 rejected is added to the conversation STM as a list of tokens. Existing STM tokens belonging to the same group will be overridden by the more recent tokens from the same group. Note also that tokens in STM automatically 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.

    You can also maintain user state-machine between requests using metadata. Conversation's metadata 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).

    See Also:
    NCContext.getConversation(), NCModelView.getConversationDepth(), NCModelView.getConversationTimeout()

    • Method Detail

      • getTokens

        List<NCToken> getTokens()
        Gets an ordered list of tokens stored in the conversation STM for the current user and data model. Tokens in the returned list are ordered by their conversational depth, i.e. the tokens from more recent requests appear before tokens from older requests.

        Note that this list excludes free words and stopwords. Note also 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).

        Returns:
        List of tokens for this conversation's STM. The list can be empty which indicates that conversation is brand new (or timed out).

      • getDialogFlow

        List<NCDialogFlowItem> getDialogFlow()
        Gets the chronologically ordered list of previously matched intents sorted from oldest to newest for the current user and data model.
        Returns:
        List of chronologically ordered previously matched intents.

      • clearStm

        void clearStm​(Predicate<NCToken> filter)
        Removes all tokens 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 token responsible for it) and therefore this method can be used to remove "stale" tokens from conversation STM.

        For example, in some cases the intent logic can assume the user current location as an implicit geo location and therefore all existing geo tokens should be removed from the conversation STM to maintain correct context.

        Parameters:
        filter - Token remove filter.

      • clearDialog

        void clearDialog​(Predicate<String> filter)
        Clears history of matched intents using given intent predicate.

        History of matched intents (i.e. the dialog flow) can be used in intent definition as part of its matching template. NLPCraft maintains the window of previously matched intents based on time, i.e. after certain period of time the oldest previously matched intents are forgotten and removed from dialog flow. This method allows explicitly clear previously matched intents from the dialog flow based on user logic other than time window.

        Parameters:
        filter - Dialog flow filter based on IDs of previously matched intents.