| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package org.apache.nlpcraft.model; |
| |
| import java.util.List; |
| import java.util.function.Predicate; |
| |
| /** |
| * Conversation container for unique 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 was |
| * successfully answered is added to the conversation STM as a list of {@link NCToken tokens}. Existing STM tokens belonging to |
| * the same {@link NCElement#getGroups() 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. |
| * <p> |
| * You can also maintain user state 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). |
| * <p> |
| * You can also access dialog flow history as a chronologically ordered list of previously matched intents sorted |
| * from oldest to newest for the current user and data model. |
| * |
| * @see NCContext#getConversation() |
| * @see NCModelView#getConversationDepth() |
| * @see NCModelView#getConversationTimeout() |
| */ |
| public interface NCConversation extends NCMetadata { |
| /** |
| * 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. |
| * <p> |
| * 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). |
| * |
| * @return List of tokens for this conversation's STM. The list can be empty which indicates that |
| * conversation is brand new (or timed out). |
| */ |
| List<NCToken> getTokens(); |
| |
| /** |
| * Gets the chronologically ordered list of previously matched intents sorted from oldest to newest for the current |
| * user and data model. |
| * |
| * @return List of chronologically ordered previously matched intents. |
| */ |
| List<NCDialogFlowItem> getDialogFlow(); |
| |
| /** |
| * Removes all tokens satisfying given token predicate from the conversation STM. |
| * <p> |
| * 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 geolocation and therefore all existing <code>nlpcraft:geo</code> tokens should be removed from the |
| * conversation STM to maintain correct context. |
| * |
| * @param filter Token remove filter. |
| */ |
| void clearStm(Predicate<NCToken> filter); |
| |
| /** |
| * Removes all previously matched intents using given intent predicate. |
| * <p> |
| * 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. |
| * |
| * @param filter Dialog flow filter based on IDs of previously matched intents. |
| */ |
| void clearDialog(Predicate<String/* Intent ID. */> filter); |
| } |