Skip to content

LarkSerializer.normalize_name does not sanitize rule names: name="first name" serializes an unparseable grammar and crashes local-model runs with a cryptic ValueError #1528

Open

Description

@BlueX888

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]+")                      # ValueError

Actual 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 the capture="OriginalName" feature of our Lark grammar" (issue Preserve case of provided name for 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 change lm["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

System info (please complete the following information):

  • OS: macOS 15.6 (arm64)
  • Guidance Version: 0.3.2 (dev install at commit 21b1d90dfbebff4b141df70c714c8af15aa5f4af), Python 3.12.14

Activity

  1. BlueX888 commented on Sep 25, 2026

    @BlueX888
    Author

    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:

    import guidance
    from guidance.library import gen, select
    
    g = gen(name="first name", regex=r"[a-z]+")
    g.match("alice")                                  # ValueError
    s = select(["a", "b"], name="the number")
    s.match("a")                                      # ValueError
    lm = guidance.models.Mock(byte_patterns=["alice", "bob"])
    lm + gen(name="first name", regex=r"[a-z]+")      # same crash at generation time
    

    Observed output:

    serialized rule: start: first name
    match('alice') raised: ValueError - 4(7): Expected token ':', found 'rule_name' (at "name" ('rule_name'))
    control match('alice'): {'first_name': 'alice'}
    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'))
    

    Fix is ready on BlueX888:fix/prep-lark-rule-name-unsanitized (commit 0f5bde5d). 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions