maskforge-core 0.1.0

Bounded JSON Schema constrained-decoding 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

//! Binds vocabularies to automata for allowed-token mask generation.

mod artifact;
mod build;
mod cache;
mod slice;
mod trie;

pub use artifact::CompiledIndex;
pub use build::{build_delta, DeltaRow};
pub(crate) use build::{
    fill_packed_rows, packed_scratch_fixed_bytes, packed_stack_bytes, walk_state_mask_into,
};
pub use cache::{BoundByteTrie, TrieCache, VocabFingerprint, VocabularyHandle};
pub(crate) use slice::{BoundedMask, TokenSliceCatalog};
pub use trie::VocabTrie;

use crate::error::CompileError;

#[must_use]
pub fn packed_ingestion_peak_bytes(
    token_bytes_len: usize,
    byte_offsets_len: usize,
    token_ids_len: usize,
    id_offsets_len: usize,
) -> Option<usize> {
    let decoded = token_bytes_len
        .checked_add(byte_offsets_len)?
        .checked_add(token_ids_len)?
        .checked_add(id_offsets_len)?;
    let token_count = (byte_offsets_len / 4).saturating_sub(1);
    let ids_count = token_ids_len / 4;
    let core_peak = crate::vocab::projected_peak_bytes(token_bytes_len, ids_count, token_count);
    decoded.checked_add(core_peak)
}

#[must_use]
pub fn direct_csr_ingestion_peak_bytes(
    total_bytes: usize,
    total_ids: usize,
    token_count: usize,
) -> Option<usize> {
    let offsets_len = token_count.checked_add(1)?.checked_mul(4)?;
    let buffers = total_bytes
        .checked_add(total_ids.checked_mul(4)?)?
        .checked_add(offsets_len)?
        .checked_add(offsets_len)?;
    let core_peak = crate::vocab::projected_peak_bytes(total_bytes, total_ids, token_count);
    buffers.checked_add(core_peak)
}

#[must_use]
pub fn dense_id_ordered_ingestion_peak_bytes(
    total_bytes: usize,
    present_count: usize,
    token_count: usize,
) -> Option<usize> {
    let offsets_len = token_count.checked_add(1)?.checked_mul(4)?;
    let present_len = token_count;
    let buffers = total_bytes
        .checked_add(offsets_len)?
        .checked_add(present_len)?;
    let core_peak = crate::vocab::projected_peak_bytes(total_bytes, present_count, present_count);
    buffers.checked_add(core_peak)
}

pub use crate::mem_gate::PermitGuard as VocabBuildPermit;

pub fn acquire_vocab_build_permit(
    estimated_bytes: usize,
) -> Result<VocabBuildPermit<'static>, CompileError> {
    crate::mem_gate::acquire_vocab_build_bytes(estimated_bytes)
}

#[must_use]
pub fn vocab_build_gate_stats() -> (usize, usize, usize, u64) {
    crate::mem_gate::vocab_build_gate_stats()
}

#[must_use]
pub fn vocab_serving_gate_stats() -> (usize, usize, usize, u64) {
    crate::mem_gate::vocab_serving_gate_stats()
}

#[must_use]
pub fn automaton_build_gate_stats() -> (usize, usize, usize, u64) {
    crate::mem_gate::automaton_build_gate_stats()
}

pub use crate::mem_gate::GateConfigError;

pub fn configure_vocab_build_gate(
    max_concurrent: usize,
    byte_budget: usize,
) -> Result<(), GateConfigError> {
    crate::mem_gate::configure_vocab_build_gate(max_concurrent, byte_budget)
}

pub fn configure_vocab_serving_gate(
    max_concurrent: usize,
    byte_budget: usize,
) -> Result<(), GateConfigError> {
    crate::mem_gate::configure_vocab_serving_gate(max_concurrent, byte_budget)
}

pub fn configure_automaton_build_gate(
    max_concurrent: usize,
    byte_budget: usize,
) -> Result<(), GateConfigError> {
    crate::mem_gate::configure_automaton_build_gate(max_concurrent, byte_budget)
}

#[non_exhaustive]
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
/// Selects the strategy used to build allowed-token masks.
pub enum BindMode {
    /// Rewalks every token from each automaton state.
    Naive,
    /// Eagerly builds state rows with a shared byte trie.
    TrieJointByte,
    /// Builds byte-trie rows lazily on first use.
    TrieJointByteLazy,
    /// Precomputes packed mask rows for all states.
    TrieJointBytePacked,
    /// Uses a byte-class trie for per-compile binding.
    TrieJointClass,
}