#ifndef INCLUDED_C_NLPLANGUAGEMODEL_H
#define INCLUDED_C_NLPLANGUAGEMODEL_H

#ifndef INCLUDED_C_NLPNGRAMGRAPH_H
#include <c_NlpNgramGraph.h>
#endif /*INCLUDED_C_NLPNGRAMGRAPH_H*/


typedef struct {
    c_NlpNgramGraph_t* levels;      /* Array of N-gram graphs sorted from highest order down to 2-gram */
    c_size_t           max_n;       /* The maximum configuration order N of the model (e.g., 3 for Trigram) */
    double             backoff_alpha; /* Proportional smoothing decay factor (typically 0.4) used per back-off step */
} c_NlpLanguageModel_t;

/**
 * @brief Initializes a multi-tier cascaded Language Model environment supporting back-off smoothing.
 * @param self           Pointer to the uninitialized language model structure.
 * @param max_n          Maximum model order threshold (e.g., 3 creates a Trigram + Bigram cascading mesh).
 * @param bucket_count   Main hash allocation array size mapped down to sub-graphs.
 * @return c_err_t       C_ERR_OK on successful initialization, or dynamic memory OOM codes.
 */
c_err_t c_NlpLanguageModel_Init(c_NlpLanguageModel_t* self, c_size_t max_n, c_size_t bucket_count);

/**
 * @brief Core Prediction: Evaluates histories and executes automated back-off smoothing cascades.
 */
c_err_t c_NlpLanguageModel_PredictSmooth(c_NlpLanguageModel_t* self, const c_ucs4_t* history_context, c_size_t history_len,
                                         c_ucs4_t* out_next_char, double* out_confidence);

/**
 * @brief Destroys and flushes all cascaded hierarchy sub-graphs completely.
 */
void c_NlpLanguageModel_Destroy(c_NlpLanguageModel_t* self);


c_err_t c_NlpLanguageModel_Train(c_NlpLanguageModel_t* self, const c_ucs4_t* unicode_array, c_size_t length);

#endif /*INCLUDED_C_NLPLANGUAGEMODEL_H*/