{"id":28409,"library":"transformers-cfg","title":"transformers-cfg","description":"Extension of the Hugging Face Transformers library for context-free grammar constrained decoding using EBNF grammars. Current version is 0.2.7, released in 2025. Active development with frequent releases.","status":"active","version":"0.2.7","language":"python","source_language":"en","source_url":"https://github.com/epfl-dlab/transformers-CFG","tags":["transformers","constrained-decoding","context-free-grammar","ebnf","llm"],"install":[{"cmd":"pip install transformers-cfg","lang":"bash","label":"Basic install from PyPI"}],"dependencies":[{"reason":"Required; provides the Hugging Face model interface.","package":"transformers","optional":false},{"reason":"Required for tensor operations and GPU support.","package":"torch","optional":false},{"reason":"Used for tokenization.","package":"tokenizers","optional":false},{"reason":"Used for CLI flag parsing.","package":"absl-py","optional":true}],"imports":[{"note":"GrammarConstraint is not a top-level export; must be imported from grammar_utils.","wrong":"from transformers_cfg import GrammarConstraint","symbol":"GrammarConstraint","correct":"from transformers_cfg.grammar_utils import GrammarConstraint"},{"note":"","wrong":"","symbol":"IncrementalGrammarConstraint","correct":"from transformers_cfg.grammar_utils import IncrementalGrammarConstraint"},{"note":"Logits processor is in the generation submodule.","wrong":"from transformers_cfg import GrammarLogitsProcessor","symbol":"GrammarLogitsProcessor","correct":"from transformers_cfg.generation.logits_process import GrammarLogitsProcessor"}],"quickstart":{"code":"from transformers import AutoModelForCausalLM, AutoTokenizer\nfrom transformers_cfg.grammar_utils import GrammarConstraint\nfrom transformers_cfg.generation.logits_process import GrammarLogitsProcessor\n\nmodel_id = \"gpt2\"\ntokenizer = AutoTokenizer.from_pretrained(model_id)\nmodel = AutoModelForCausalLM.from_pretrained(model_id)\n\n# Load a grammar (e.g., from a string)\nimport os\ngrammar_str = open(os.path.join(os.path.dirname(__file__), \"grammars\", \"json.ebnf\"), \"r\").read()\n\ngrammar = GrammarConstraint(grammar_str, tokenizer=tokenizer)\nlogits_processor = GrammarLogitsProcessor(grammar)\n\ninputs = tokenizer([\"Here is a JSON: \"], return_tensors=\"pt\")\noutput = model.generate(\n    **inputs,\n    max_new_tokens=100,\n    logits_processor=[logits_processor],\n    pad_token_id=tokenizer.eos_token_id\n)\nprint(tokenizer.decode(output[0], skip_special_tokens=True))","lang":"python","description":"Basic constrained generation with a JSON grammar."},"warnings":[{"fix":"Update imports to from transformers_cfg.grammar_utils import GrammarConstraint","message":"In v0.2.0, the API was restructured: GrammarConstraint moved from top-level to grammar_utils module and IncrementalGrammarConstraint was added. Older imports will break.","severity":"breaking","affected_versions":"<0.2.0"},{"fix":"Always use the same tokenizer that corresponds to the model you are generating with.","message":"GrammarConstraint requires the tokenizer object at initialization; if you pass a tokenizer that is not from the same model, parsing may silently fail or produce incorrect masks.","severity":"gotcha","affected_versions":"all"},{"fix":"Design grammars without referencing internal special tokens.","message":"The package reserves special tokens like <|endoftext|> for internal use. If your grammar expects those tokens, use escape sequences or avoid them.","severity":"gotcha","affected_versions":"all"},{"fix":"Convert .gbnf files to .ebnf or use the string-based API.","message":"The old grammar file format using .gbnf is deprecated; use .ebnf instead. The CLI still supports .gbnf but may be removed in a future version.","severity":"deprecated","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use: from transformers_cfg.grammar_utils import GrammarConstraint","cause":"GrammarConstraint is not exported at package level.","error":"cannot import name 'GrammarConstraint' from 'transformers_cfg'"},{"fix":"Upgrade to latest version: pip install --upgrade transformers-cfg","cause":"Old version of transformers-cfg (<0.2.0) did not have grammar_utils module.","error":"AttributeError: module 'transformers_cfg' has no attribute 'grammar_utils'"},{"fix":"Move tokenizer to model device: tokenizer.model.to(model.device) or pass device_map to model.","cause":"Tokenizer and model are on different devices (e.g., tokenizer on CPU, model on GPU). GrammarConstraint uses tokenizer to create tensors that must match model's device.","error":"Expected all tensors to be on the same device, but found at least two devices"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}