Repository navigation
Description
The bug
gen/select/json/subgrammar accept an arbitrary string as name= (the README documents gen(name="lm_response", ...) and lm['lm_response'] access), but LarkSerializer.normalize_name (guidance/_ast.py:815-823) only rewrites -→_ and camelCase→snake_case (plus case normalization). Any other character that is not valid in a Lark rule name — a space, a dot, a leading digit, a non-ASCII letter, | — is emitted verbatim as the serialized rule name, producing a grammar that cannot be parsed.
ll_grammar() happily returns e.g. start: first name, and every consumer that compiles the grammar then fails with ValueError: Expected token ':', found 'rule_name' — an error message nowhere near the actual cause (the name= argument). This hits every engine-backed (local) model run, since EngineInterpreter.grammar() calls node.ll_grammar() (guidance/models/_engine/_interpreter.py:65). Remote/API models never compile the grammar, which is why the repo's own tests/need_credentials tests that use select([...], name="the number") (test_anthropic.py:36, test_lite_llm.py:39) pass today.
To Reproduce
No model is needed to see the invalid grammar and the crash; a Mock engine model is included to show the generation-time failure:
import guidance
from guidance.library import gen, select
# 1) No model: the serialized grammar is already invalid
g = gen(name="first name", regex=r"[a-z]+")
print([l for l in g.ll_grammar().splitlines() if l.strip()][1]) # -> start: first name
g.match("alice") # ValueError
control = gen(name="first_name", regex=r"[a-z]+") # valid identifier
control.match("alice") # works
s = select(["a", "b"], name="the number")
s.match("a") # ValueError
# 2) Engine-backed (local) model: same crash at generation time
lm = guidance.models.Mock(byte_patterns=["alice", "bob"])
lm + gen(name="first name", regex=r"[a-z]+") # ValueErrorActual output (verbatim):
serialized rule: start: first name
match('alice') raised: ValueError - 4(7): Expected token ':', found 'rule_name' (at "name" ('rule_name'))
control match('alice'): True
select match('a') raised: ValueError - 4(5): Expected token ':', found 'rule_name' (at "number" ('rule_name'))
engine-backed gen raised: ValueError - 4(7): Expected token ':', found 'rule_name' (at "name" ('rule_name'))
(the control line shows the same gen with a valid identifier name works fine)
Expected behaviour
A capture name= that is not a valid Lark identifier should still serialize to a parseable grammar. Basis:
normalize_name's own purpose is to produce parseable rule names — PR [Bug] Normalised capture names not preserved #1334 (commit 869a636), which introduced it, states: "If a capture name is also a valid Lark rule name, then it can be left in place. Otherwise (e.g. if it mixes upper and lower case), we have to normalise it, and use thecapture="OriginalName"feature of our Lark grammar" (issue Preserve case of providednamefor generated text #1172: "setting and looking up the names for generated text should work like it does with a normal Python dictionary").serialize()already treats rule names as identifiers that must be valid and unique — it defends against collisions by suffixing_1(guidance/_ast.py:689-694).- Capture names are serialized separately as JSON-quoted attribute values (
capture={json.dumps(capture_name)},guidance/_ast.py:703), so sanitizing the rule name does not changelm["first name"]access.
Root cause
guidance/_ast.py:815-823 — normalize_name handles only -, camelCase and letter case; it leaves characters that cannot appear in a Lark rule name (space, dot, leading digit, non-ASCII, |, …) verbatim in the emitted rule name.
A small fix would be, after the existing rewrites in normalize_name, to replace any character outside [A-Za-z0-9_] with _ and prefix _ when the result starts with a digit or is empty, so the rule name is always a single valid Lark identifier. I'm happy to open a PR with that approach (including tests for names like my gen, a.b, 123, héllo).
Related
- [Bug] Normalised capture names not preserved #1334 — introduced
normalize_nameand thecapture="OriginalName"mechanism (originally for camelCase names, Preserve case of providednamefor generated text #1172); the same mechanism covers this case, the sanitization is just incomplete. - Preserve case of provided
namefor generated text #1172 — the underlying requirement that arbitrary capture names keep working.
System info (please complete the following information):
- OS: macOS 15.6 (arm64)
- Guidance Version:
0.3.2(dev install at commit21b1d90dfbebff4b141df70c714c8af15aa5f4af), Python 3.12.14
Activity
BlueX888 commentedon Sep 25, 2026
Reproduced this. Root cause: guidance/_ast.py:815-823 — normalize_name only rewrites '-' and camelCase, so characters that cannot appear in a Lark rule name (space, dot, leading digit, non-ASCII, '|', ...) are emitted verbatim as the serialized rule name, and every consumer that compiles the grammar then dies on the unparseable rule.
Minimal reproduction:
Observed output:
Fix is ready on
BlueX888:fix/prep-lark-rule-name-unsanitized(commit0f5bde5d). Rule names are now restricted to [A-Za-z0-9_] (anything else becomes '') and prefixed with 'n' when they would not start with a letter, so every capture name serializes to a valid Lark rule; the capture= attribute keeps the original name, so lm["first name"] access is unchanged.Verified with:
python -m pytest ./tests/unit (1645 passed, 1 skipped, 220 xfailed; new cases in tests/unit/test_ast.py and tests/unit/test_grammar.py)Happy to open the PR once you confirm the approach or assign this to me.