/*
 * 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;

/**
 * User-defined semantic data model.
 * <p>
 * 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: {@link 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.
 * <p>
 * Generally, a data model defines:
 * <ul>
 *     <li>Set of model {@link NCElement elements} (a.k.a. named entities) to be detected in the user input.</li>
 *     <li>Zero or more <a target=_ href="https://nlpcraft.apache.org/intent-matching.html">intent</a> callbacks.</li>
 *     <li>Common model configuration and life-cycle callbacks.</li>
 * </ul>
 * 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.
 * <p>
 * Read full documentation in <a target=_ href="https://nlpcraft.apache.org/data-model.html">Data Model</a> section and review
 * <a target=_ href="https://github.com/apache/incubator-nlpcraft/tree/master/src/main/scala/org/apache/nlpcraft/examples/">examples</a>.
 *
 * @see NCModelAdapter
 * @see NCModelFileAdapter
 */
public interface NCModel extends NCModelView, NCLifecycle {
    /**
     * 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.
     * <p>
     * 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.
     * <p>
     * By default, this method accepts all variants (returns {@code true}).
     *
     * @param var A variant (list of tokens) to accept or reject.
     * @return {@code True} to accept variant for further processing, {@code false} otherwise.
     */
    default boolean onParsedVariant(NCVariant var) {
        return true;
    }

    /**
     * A callback that is called when a fully assembled query context is ready. This callback is called after
     * all {@link #onParsedVariant(NCVariant)} callbacks are called but before any {@link #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.
     * <p>
     * Default implementation returns {@code null}.
     *
     * @param ctx Query context.
     * @return Optional query result to return interrupting the default workflow. Specifically, if this method returns
     *      a non-{@code null} result, it will be returned to the caller immediately overriding default behavior. If
     *      the method returns {@code null} - the default processing flow will continue.
     * @throws NCRejection This callback can throw this rejection exception to abort user request processing.
     */
    default NCResult onContext(NCContext ctx) throws NCRejection {
        return null;
    }

    /**
     * A callback that is called when intent was successfully matched but right before its callback is called.
     * This callback is called after {@link #onContext(NCContext)} is called and may be called multiple times
     * depending on its return value. If {@code true} is returned than the default workflow will continue and
     * the matched intent's callback will be called. However, if {@code false} is returned than the entire
     * existing set of parsing variants will be matched against all declared intents again. Returning {@code 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.
     * <p>
     * Note that this callback may not be called at all based on the return value
     * of {@link #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.
     * <p>
     * By default, this method returns {@code true}.
     *
     * @param ctx Intent match context - the same instance that's passed to the matched intent callback.
     * @return If {@code true} is returned than the default workflow will continue and the matched intent's callback
     *      will be called. However, if {@code false} is returned than the entire existing set of parsing variants will
     *      be matched against all declared intents again. Returning {@code 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 {@link #onRejection(NCIntentMatch, NCRejection)} callback will be called next.
     */
    default boolean onMatchedIntent(NCIntentMatch ctx) throws NCRejection {
        return true;
    }

    /**
     * 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 {@link #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.
     * <p>
     * Default implementation is a no-op returning {@code null}.
     *
     * @param ctx Intent match context - the same instance that's passed to the matched intent callback that
     *      produced this result.
     * @param res Existing result.
     * @return Optional query result to return interrupting the default workflow. Specifically, if this method returns
     *      a non-{@code 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 {@code null} - the default
     *      processing flow will continue.
     */
    default NCResult onResult(NCIntentMatch ctx, NCResult res) {
        return null;
    }

    /**
     * A callback that is called when intent callback threw {@link NCRejection} exception.
     * This callback is called after {@link #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.
     * <p>
     * Default implementation is a no-op returning {@code null}.
     *
     * @param ctx Optional intent match context - the same instance that's passed to the matched intent callback that
     *      produced this rejection. It is {@code null} if rejection was triggered outside of the intent callback.
     * @param e Rejection exception.
     * @return Optional query result to return interrupting the default workflow. Specifically, if this method returns
     *      a non-{@code 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 {@code null} - the default
     *      processing flow will continue.
     */
    default NCResult onRejection(NCIntentMatch ctx, NCRejection e) {
        return null;
    }

    /**
     * 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.
     * <p>
     * Default implementation is a no-op returning {@code null}.
     *
     * @param ctx Intent match context - the same instance that's passed to the matched intent that
     *      produced this error.
     * @param e Failure exception.
     * @return Optional query result to return interrupting the default workflow. Specifically, if this method returns
     *      a non-{@code 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 {@code null} - the default
     *      processing flow will continue.
     */
    default NCResult onError(NCContext ctx, Throwable e) {
        return null;
    }
}