cAI/cNLP/Library/c_NlpCharGraph.h

#ifndef INCLUDED_C_NLPCHARGRAPH_H
#define INCLUDED_C_NLPCHARGRAPH_H


#ifndef INCLUDED_C_BASE_H
#include <c_Base.h>
#endif /*INCLUDED_C_BASE_H*/

#ifndef INCLUDED_C_UTF8_H
#include <c_utf8.h>
#endif /*INCLUDED_C_UTF8_H*/

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

typedef enum {
    C_PREDICT_MODE_GREEDY   = 0,  /* 贪婪模式：总是选择频次最高的最优解 */
    C_PREDICT_MODE_SAMPLING = 1   /* 抽样模式：根据概率分布进行随机选择（更具多样性） */
} c_NlpPredictMode_t;

/* --- 1. 动态位置数组（记录某个字在文章中出现的所有索引位置） --- */
typedef struct {
    c_size_t*  offsets;     // 存储绝对位置的数组（如：第0, 15, 234个字）
    c_size_t   count;       // 出现频次 (次数)
    c_size_t   capacity;    // 动态数组容量
} c_NlpOffsetList_t;

/* --- 2. 邻接边结构体（记录当前字与前后字的关系及共现次数） --- */
typedef struct c_NlpCharEdge_t {
    c_ucs4_t                target_cp;  // 关联字的 Unicode 码点
    c_size_t                co_count;   // 在邻接上下文中共同出现的次数
    struct c_NlpCharEdge_t* next;       // 冲突链表指针（使用哈希拉链法或链表）
} c_NlpCharEdge_t;

/* --- 3. 核心：Unicode 字符语义拓扑节点 --- */
typedef struct c_NlpCharNode_t{
    c_ucs4_t           codepoint;
    c_size_t           frequency;
    c_NlpOffsetList_t  offset_list;

    // Refactored pointers managing arbitrarily sized hash bucket tables
    c_NlpCharEdge_t**  next_chars;       // Forward Bigram Hash Buckets array
    c_NlpCharEdge_t**  prev_chars;       // Backward Bigram Hash Buckets array
    c_size_t           relation_capacity; // Current allocated size for next_chars and prev_chars

    struct c_NlpCharNode_t* next;
} c_NlpCharNode_t;

typedef struct {
    c_NlpCharNode_t** buckets;      // 主哈希表：存储文章中所有出现过的唯一字节点
    c_size_t          bucket_count; // 主哈希桶大小（如 1024 或 4096，取决于去重后的字数）
    c_size_t          relation_default_capacity; // The default bucket capacity configured for sub-nodes
    c_size_t          total_unique; // 文章中不重复的汉字总量
    c_size_t          total_words;  // 整篇文章的总字数（包括标点）
} c_NlpCharGraph_t;

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

c_err_t c_NlpCharGraph_Init(c_NlpCharGraph_t* self, c_size_t bucket_count, c_size_t relation_default_capacity);
c_NlpCharNode_t* c_NlpCharGraph_GetNode(c_NlpCharGraph_t* self, c_ucs4_t cp);
c_err_t c_NlpCharGraph_Process(c_NlpCharGraph_t* self, const c_ucs4_t* unicode_array, c_size_t length);
void c_NlpCharGraph_Destroy(c_NlpCharGraph_t* self);

/**
 * @brief Analyzes structural proximity metrics between two tokens within a sliding context window.
 * @param self              Pointer to the active initialized graph context block.
 * @param cp1               The reference source Unicode character point.
 * @param cp2               The target matching Unicode character point to measure.
 * @param window_size       Maximum token span distance threshold allowed (e.g., 5 tokens).
 * @param out_min_dist      Destination tracking pointer for the absolute minimum token distance.
 * @param out_avg_dist      Destination tracking pointer for the calculated average token distance.
 * @param out_co_occurrences Destination tracking pointer counting total window crossing events.
 * @param out_cp1_precedes_count Tracks how many times cp1 appeared BEFORE cp2 within the window.
 * @param out_cp2_precedes_count Tracks how many times cp2 appeared BEFORE cp1 within the window.
 * @return c_err_t          C_ERR_OK on successful analytical completion, or C_ERR_PARAM if arguments are invalid.
 */
c_err_t c_NlpCharGraph_AnalyzeDistanceWindow(c_NlpCharGraph_t* self, c_ucs4_t cp1, c_ucs4_t cp2, c_size_t window_size,
                                             c_size_t* out_min_dist, double* out_avg_dist, c_size_t* out_co_occurrences,
                                             c_size_t* out_cp1_precedes_count, c_size_t* out_cp2_precedes_count);

/**
 * @brief Exports the entire Unicode semantics graph structure to a file in valid JSON format.
 *        Automatically translates 32-bit codepoints back to human-readable UTF-8 strings.
 * @param self     Pointer to the active processed graph context block.
 * @param filepath Destination path on disk where the JSON file will be saved.
 * @return c_err_t C_ERR_OK on complete success, C_ERR_PARAM on invalid parameters, or C_ERR_FAIL on file access errors.
 */
c_err_t c_NlpCharGraph_ExportJSON(c_NlpCharGraph_t* self, const char* filepath);

/**
 * @brief Parses an exported JSON text file and reconstructs the full Unicode graph structure in memory.
 * @param self          Pointer to an uninitialized or empty c_NlpCharGraph_t instance.
 * @param filepath      Path to the source JSON file on disk.
 * @param bucket_count  Main hash bucket size to use for the new graph context.
 * @return c_err_t      C_ERR_OK on complete success, C_ERR_PARAM on invalid inputs, or C_ERR_FAIL on structural parsing failures.
 */
c_err_t c_NlpCharGraph_ImportJSON(c_NlpCharGraph_t* self, const char* filepath, c_size_t bucket_count);

/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

/**
 * @brief 根据当前已出现的字，预测并确定后续最应该输出什么字
 * @param self             指向已完成语料分析的拓扑图实例指针
 * @param current_char     当前最新出现的字（Unicode 码点）
 * @param mode             选择的预测模式（贪婪 或 抽样）
 * @param out_next_char    接收预测出的下一个字的指针
 * @param out_confidence   接收该预测字的置信度（概率值，0.0 ~ 1.0）
 * @return c_err_t         C_ERR_OK 表示成功预测，C_ERR_PARAM 表示参数错误，C_ERR_FAIL 表示该字是生僻词/无后续关联
 */
c_err_t c_NlpCharGraph_PredictNext(c_NlpCharGraph_t* self, c_ucs4_t current_char, c_NlpPredictMode_t mode,
                                   c_ucs4_t* out_next_char, double* out_confidence);


#endif /*INCLUDED_C_NLPCHARGRAPH_H*/