Package org.apache.nlpcraft.model

Interface NCModel

  • All Superinterfaces:
    NCLifecycle, NCMetadata, NCModelView
    All Known Implementing Classes:
    NCModelAdapter, NCModelFileAdapter
    public interface NCModel
extends NCModelView, NCLifecycle
    User-defined semantic data model.

    Data model is a central concept in NLPCraft defining an interface to your data sources like a database or a SaaS application. NLPCraft employs model-as-a-code approach where entire data model is an implementation of this interface which can be developed using any JVM programming language like Java, Scala, Kotlin, or Groovy. Data model definition is split into two interfaces: NCModelView that defines the declarative, configuration, part of the model that is usually defined in an external JSON or YAML file, and this interface that provides various life-cycle callbacks.

    Generally, a data model defines:

    • Set of model elements (a.k.a. named entities) to be detected in the user input.
    • Zero or more intent callbacks.
    • Common model configuration and life-cycle callbacks.
    Note that 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 have to resort to additional web-based 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.

    Read full documentation in Data Model section and review examples.

    See Also:
    NCModelAdapter, NCModelFileAdapter

    • Method Detail

      • onParsedVariant

        default boolean onParsedVariant​(NCVariant var)
        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.

        Note that a given user input can have one or more possible different parsing variants. Depending on model configuration a user input 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 tokens, presence of a particular token in the variant, etc.

        By default, this method accepts all variants (returns true).

        Parameters:
        var - A variant (list of tokens) to accept or reject.
        Returns:
        True to accept variant for further processing, false otherwise.

      • onContext

        default NCResult onContext​(NCContext ctx)
                    throws NCRejection
        A callback that is called when a fully assembled query context is ready. This callback is called after all onParsedVariant(NCVariant) callbacks are called but before any onMatchedIntent(NCIntentMatch) are called, i.e. right before the intent matching is performed. It's called always once per user request 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.

        Default implementation returns null.

        Parameters:
        ctx - Query context.
        Returns:
        Optional query result to return interrupting the default workflow. Specifically, if this method returns a non-null result, it will be returned to the caller immediately overriding default behavior. If the method returns null - the default processing flow will continue.
        Throws:
        NCRejection - This callback can throw this rejection exception to abort user request processing.

      • onMatchedIntent

        default boolean onMatchedIntent​(NCIntentMatch ctx)
                         throws NCRejection
        A callback that is called when intent was successfully matched but right before its callback is called. This callback is called after onContext(NCContext) is called and may be called multiple times depending on its return value. If true is returned than the default workflow will continue and the matched intent's callback will be called. However, if false is returned than the entire existing set of 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. 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 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.

        By default, this method returns true.

        Parameters:
        ctx - Intent match context - the same instance that's passed to the matched intent callback.
        Returns:
        If true is returned than the default workflow will continue and the matched intent's callback will be called. However, if false is returned than the entire existing set of 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 re-evaluation of the parsing variants against all declared intents. Note that user logic should be careful not to induce infinite loop in this behavior.
        Throws:
        NCRejection - This callback can throw the rejection exception to abort user request processing. In this case the onRejection(NCIntentMatch, NCRejection) callback will be called next.

      • onResult

        default NCResult onResult​(NCIntentMatch ctx,
                          NCResult res)
        A callback that is called when successful result is obtained from the intent callback and right before sending it back to the caller. This callback is called after onMatchedIntent(NCIntentMatch) is called. 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.

        Default implementation is a no-op returning null.

        Parameters:
        ctx - Intent match context - the same instance that's passed to the matched intent callback that produced this result.
        res - Existing result.
        Returns:
        Optional query result to return interrupting the default workflow. Specifically, if this method returns a non-null result, it will be returned to the caller immediately overriding default behavior and existing query result or error processing, if any. If the method returns null - the default processing flow will continue.

      • onRejection

        default NCResult onRejection​(NCIntentMatch ctx,
                             NCRejection e)
        A callback that is called when intent callback threw NCRejection exception. This callback is called after onMatchedIntent(NCIntentMatch) is called. 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.

        Default implementation is a no-op returning null.

        Parameters:
        ctx - Optional intent match context - the same instance that's passed to the matched intent callback that produced this rejection. It is null if rejection was triggered outside of the intent callback.
        e - Rejection exception.
        Returns:
        Optional query result to return interrupting the default workflow. Specifically, if this method returns a non-null result, it will be returned to the caller immediately overriding default behavior and existing query result or error processing, if any. If the method returns null - the default processing flow will continue.

      • onError

        default NCResult onError​(NCContext ctx,
                         Throwable e)
        A callback that is called when intent callback failed with unexpected exception. 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.

        Default implementation is a no-op returning null.

        Parameters:
        ctx - Intent match context - the same instance that's passed to the matched intent that produced this error.
        e - Failure exception.
        Returns:
        Optional query result to return interrupting the default workflow. Specifically, if this method returns a non-null result, it will be returned to the caller immediately overriding default behavior and existing query result or error processing, if any. If the method returns null - the default processing flow will continue.