Installation

Python quickstart

import glrmask

vocab = glrmask.Vocab.from_id_to_bytes({0: b"hello", 1: b" ", 2: b"world"})
grammar = glrmask.Grammar.from_ebnf('start ::= "hello" " " "world"')
constraint = grammar.compile(vocab)
state = constraint.start()
for token_id, expected in [(0, [True, False, False]),
                           (1, [False, True, False]),
                           (2, [False, False, True])]:
    assert state.mask().tolist() == expected
    state.commit_token(token_id)
assert state.is_accepting()

Python masks are NumPy Boolean arrays indexed by original model token ID.

Rust quickstart

use glrmask::{Grammar, Vocab};

fn main() -> glrmask::Result<()> {
    let vocab = Vocab::new(vec![
        (0, b"hello".to_vec()), (1, b" ".to_vec()), (2, b"world".to_vec()),
    ]);
    let grammar = Grammar::from_ebnf(r#"start ::= "hello" " " "world""#);
    let constraint = grammar.compile(&vocab)?;
    let mut state = constraint.start();
    for (token_id, expected) in [(0, 1), (1, 2), (2, 4)] {
        assert_eq!(state.mask()[0] & 7, expected);
        state.commit_token(token_id)?;
    }
    assert!(state.is_accepting());
    Ok(())
}

Rust masks are packed u32 bitsets. Bit token_id % 32 of word token_id / 32 indicates whether that token is allowed.

Core concepts

GLRMask has four core types:

• Grammar: source grammar semantics and bindings.
• PreparedGrammar: reusable vocabulary-specific compiled machinery, which can still have unresolved bindings.
• Constraint: a closed, runnable grammar compiled against a vocabulary.
• ConstraintState: the mutable state for one generated sequence.

Compile a Grammar directly, or use prepare() and link() for reusable components. Create a state with start(), then compute the next-token mask, sample an allowed token, and commit it.

Grammar and PreparedGrammar keep reusable definitions with mutable bindings. bind() fills one declared slot on the handle. Clones and previously attached children retain independent binding snapshots; a failed bind leaves the handle unchanged.

Full guide · Python API reference · Rust API reference