obadh_engine 0.8.0

A linguistically accurate Roman to Bengali transliteration engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

/*
 * obadh.h — stable C ABI for the Obadh transliteration engine.
 *
 * Built when the crate is compiled with the `cabi` feature (native targets only).
 * Link the resulting cdylib/staticlib and include this header.
 *
 * Conventions
 * -----------
 * Sizing (snprintf-style): every function that writes bytes takes an output
 *   pointer and capacity and returns the number of bytes the result needs. It
 *   copies only when the buffer is large enough. Pass a small stack scratch;
 *   reallocate and call again only if the return exceeds the capacity.
 *
 * String lists (count + length-prefixed records, no delimiter): a list is packed
 *   into one buffer as little-endian [uint32 count] followed by `count` records
 *   of [uint32 byte_len][utf8 bytes]. No in-band separator — a candidate may
 *   contain any bytes, and an empty string is faithful.
 *
 * Handles: opaque pointers from *_open / *_new, released by the matching *_free.
 *   Do not use a handle after freeing it, and do not use one handle from multiple
 *   threads at once (no internal locking; the caller owns synchronization).
 *
 * UTF-8: inputs are (ptr, len) UTF-8 spans. Invalid UTF-8 makes the call a no-op
 *   (returns 0 / false / null). A zero length is the empty string.
 *
 * The ABI version (obadh_abi_version) is independent of the crate's semver:
 * additive symbols do not bump it.
 */
#ifndef OBADH_H
#define OBADH_H

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

#define OBADH_ABI_VERSION 1

/* Opaque handles. */
typedef struct ObadhEngine ObadhEngine;
typedef struct ObadhAutocorrect ObadhAutocorrect;
typedef struct ObadhAutosuggest ObadhAutosuggest;

/* Commit strength codes for obadh_autosuggest_commit. */
#define OBADH_COMMIT_ORDINARY            0u
#define OBADH_COMMIT_CORRECTION_REJECTED 1u
#define OBADH_COMMIT_MANUALLY_ADDED      2u

/* ----------------------------------------------------------------- version */

uint32_t obadh_abi_version(void);
size_t   obadh_engine_version(uint8_t *out, size_t cap);

/* ------------------------------------------------------ deterministic engine */

ObadhEngine *obadh_engine_new(void);
void         obadh_engine_free(ObadhEngine *engine);

size_t obadh_transliterate(const ObadhEngine *engine,
                           const uint8_t *input, size_t input_len,
                           uint8_t *out, size_t cap);
size_t obadh_transliterate_lenient(const ObadhEngine *engine,
                                   const uint8_t *input, size_t input_len,
                                   uint8_t *out, size_t cap);

/* ----------------------------------------------------------------- autocorrect */

/* Open from a bn.fst path and an optional loanword FST path (length 0 to omit).
 * Returns NULL on failure. */
ObadhAutocorrect *obadh_autocorrect_open(const uint8_t *fst_path, size_t fst_path_len,
                                         const uint8_t *loanword_path, size_t loanword_path_len);
void              obadh_autocorrect_free(ObadhAutocorrect *autocorrect);

/* Content fingerprint of the loaded lexicon FST (crate <-> artifact check). */
uint64_t obadh_autocorrect_fingerprint(const ObadhAutocorrect *autocorrect);

/* 1 if `word` is an exact lexicon entry, else 0. A real word is never corrected. */
int32_t obadh_autocorrect_is_lexicon_word(const ObadhAutocorrect *autocorrect,
                                          const uint8_t *word, size_t word_len);

/* Ranked correction candidates for `roman` as a packed string list (see header
 * notes). `limit` caps the count. snprintf-style. */
size_t obadh_autocorrect_suggest(const ObadhAutocorrect *autocorrect,
                                 const uint8_t *roman, size_t roman_len,
                                 size_t limit, uint8_t *out, size_t cap);

/* Auto-insert gate. Returns 1 if a correction is confident enough to apply
 * without asking, else 0. When 1, the replacement text is written snprintf-style
 * to out/cap and its needed length to *needed_len; when 0, *needed_len is 0. */
int32_t obadh_autocorrect_should_replace(const ObadhAutocorrect *autocorrect,
                                         const uint8_t *roman, size_t roman_len,
                                         uint8_t *out, size_t cap, size_t *needed_len);

/* ----------------------------------------------------------------- autosuggest */

/* Open from an n-gram artifact path. Returns NULL on failure. */
ObadhAutosuggest *obadh_autosuggest_open(const uint8_t *path, size_t path_len);
void              obadh_autosuggest_free(ObadhAutosuggest *autosuggest);

/* Content fingerprint of the loaded n-gram artifact. */
uint64_t obadh_autosuggest_fingerprint(const ObadhAutosuggest *autosuggest);

/* Commit a token, learning it into the personal overlay. `strength` is one of the
 * OBADH_COMMIT_* codes. Returns 1 if learned, else 0. */
int32_t obadh_autosuggest_commit(ObadhAutosuggest *autosuggest,
                                 const uint8_t *token, size_t token_len, uint32_t strength);

/* Post-decay evidence that the user established `word` (0 if never committed). */
uint32_t obadh_autosuggest_established_weight(const ObadhAutosuggest *autosuggest,
                                              const uint8_t *word, size_t word_len);

/* 1 if the user established `word` with at least `min_weight` post-decay evidence,
 * else 0. Gate for protecting learned words from auto-correction. */
int32_t obadh_autosuggest_is_word_established(const ObadhAutosuggest *autosuggest,
                                              const uint8_t *word, size_t word_len,
                                              uint32_t min_weight);

/* Next-word suggestions for the current context as a packed string list. */
size_t obadh_autosuggest_suggest(ObadhAutosuggest *autosuggest, size_t limit,
                                 uint8_t *out, size_t cap);

void obadh_autosuggest_clear_session(ObadhAutosuggest *autosuggest);
void obadh_autosuggest_clear_personal(ObadhAutosuggest *autosuggest);

/* Export/import the personal overlay snapshot. Export is snprintf-style; import
 * returns 1 on success, else 0. */
size_t  obadh_autosuggest_export_personal(const ObadhAutosuggest *autosuggest,
                                          uint8_t *out, size_t cap);
int32_t obadh_autosuggest_import_personal(ObadhAutosuggest *autosuggest,
                                          const uint8_t *input, size_t input_len);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* OBADH_H */