[feat] support whitespace control for structural tag

[izhuhaoran]

Some models, in bad-case generations, emit unbounded runs of whitespace, which inflates the Earley parser's state set and can blow up grammar compilation/matching.

Adds two whitespace controls — any_whitespace and max_whitespace_cnt — as parameters of the structural-tag compile interface (GrammarCompiler.compile_structural_tag / Grammar.from_structural_tag), mirroring compile_json_schema.

[gemini-code-assist]

Code Review

This pull request introduces whitespace control parameters (any_whitespace and max_whitespace_cnt) to the structural tag compilation and grammar generation interfaces to prevent state explosion. Feedback suggests optimizing the C++ style_to_grammar_converter map by replacing std::function with raw function pointers to avoid dynamic allocation overhead. Additionally, it is recommended to validate max_whitespace_cnt in Python to ensure it is a positive integer before passing it to the C++ backend.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Using std::function in a const static map introduces unnecessary overhead due to dynamic allocation and virtual dispatch. Since the lambdas do not capture any variables, they can be implicitly converted to raw function pointers, which are more efficient.

  const static std::unordered_map<\n      std::string,\n      std::string (*)(const std::string&, bool, std::optional<int>)>\n      style_to_grammar_converter = {

[gemini-code-assist]

Validate max_whitespace_cnt in Python to ensure it is a positive integer before passing it to the C++ backend. This prevents potential C++ fatal log crashes and provides a clearer Python ValueError to the user.

        any_whitespace = kwargs.pop(\"any_whitespace\", True)\n        max_whitespace_cnt = kwargs.pop(\"max_whitespace_cnt\", None)\n        if max_whitespace_cnt is not None and (not isinstance(max_whitespace_cnt, int) or isinstance(max_whitespace_cnt, bool) or max_whitespace_cnt <= 0):\n            raise ValueError(\"max_whitespace_cnt must be a positive integer\")

[gemini-code-assist]

Validate max_whitespace_cnt in Python to ensure it is a positive integer before passing it to the C++ backend. This prevents potential C++ fatal log crashes and provides a clearer Python ValueError to the user.

        any_whitespace = kwargs.pop(\"any_whitespace\", True)\n        max_whitespace_cnt = kwargs.pop(\"max_whitespace_cnt\", None)\n        if max_whitespace_cnt is not None and (not isinstance(max_whitespace_cnt, int) or isinstance(max_whitespace_cnt, bool) or max_whitespace_cnt <= 0):\n            raise ValueError(\"max_whitespace_cnt must be a positive integer\")

[izhuhaoran]

@Ubospica @Seven-Streams Could you please review this PR when you have time?

[Seven-Streams]

We may need to mention it in the doc.

[izhuhaoran]

Done. Added a short note to docs/structural_tag/tool_calling_and_reasoning.md.

[izhuhaoran]

@Seven-Streams I've addressed all the comments. Could you please take another look when you have a chance?

[Seven-Streams]

@Ubospica cc

[izhuhaoran]

@Ubospica cc

@Seven-Streams @Ubospica Could you please help merge this PR manually?

[Seven-Streams]

Hello @izhuhaoran. I discussed the function with @Ubospica today, and I'll make some modifications tomorrow, and then the PR will be merged. Thanks for your contribution!

[izhuhaoran]

@Seven-Streams Thank you for taking the time to further improve this PR. I really appreciate it.

I noticed it hasn’t been merged yet, so I just wanted to check whether there are any remaining concerns or anything else needed from my side.

[Ubospica]

LGTM! @Seven-Streams if you have time plz cross check