Crate xgrammar 

Safe, idiomatic Rust bindings for the xgrammar C++ library for constrained decoding of large language models.

This crate wraps xgrammar’s grammar compilation and token-level matching so you can drive constrained generation (JSON schema, regex, BNF, structural tags) from Rust while retaining the performance of the upstream C++ implementation.

Highlights

• Grammar, GrammarCompiler, CompiledGrammar, TokenizerInfo — compile grammars (BNF, JSON schema, regex, structural tags) against a tokenizer.
• GrammarMatcher — token-by-token constrained decoding, including GrammarMatcher::is_completed (root-rule match without stop token), GrammarMatcher::fork for speculative / branching decoding, and GrammarMatcher::traverse_draft_tree for filling per-node token bitmasks over a speculative-decoding draft tree.
• BatchGrammarMatcher — batched helpers over a slice of matchers: BatchGrammarMatcher::batch_fill_next_token_bitmask is parallel and thread-pool-backed; batch_accept_token / batch_accept_string / batch_rollback are sequential static helpers.
• Serialization — serialize_json / deserialize_json on Grammar, CompiledGrammar, and TokenizerInfo for persisting compilation results (version-locked to the vendored xgrammar’s serialization format).
• Typed errors — XGrammarErr variants mirror the upstream xgrammar exception types via XGrammarError::GetType() (XGrammarErr::InvalidJson, XGrammarErr::InvalidStructuralTag, XGrammarErr::DeserializeVersion, XGrammarErr::DeserializeFormat, …), with the coarse-grained variants kept as fallbacks for untyped C++ errors.

See each item’s documentation for usage details, including when a BatchGrammarMatcher instance is required vs when associated functions can be called directly.

Re-exports

pub use tokenizers;

Modules

huggingface_hub

Structs

BatchGrammarMatcher

CompiledGrammar

Grammar

GrammarCompiler

GrammarMatcher

MetadataFromHF

TokenizerInfo

Enums

VocabType

XGrammarErr

Statics

EOS_TOKEN_ID_KEY

GENERATION_CONFIG_FILE

HF_CONFIG_FILE

TOKENIZER_ALLOW_PATTERN

TOKENIZER_CONFIG_FILE

TOKENIZER_FILE

TOKENIZER_MODEL_KEY

TOKENIZER_VOCAB_KEY

Functions

get_bitmask_size

Return the number of i32 elements required per token-bitmask row for a vocabulary of vocab_size tokens, i.e. ceil(vocab_size / 32).

Type Aliases

Result

Alias for std::result::Result<T, XGrammarErr>.

TokenId

VocabMap