Motivation

This PR addresses two related issues:

1. Opaque error messages on invalid grammars: When a grammar fails to compile, the original error from the backend is only logged server-side. The user receives a generic message like "Invalid grammar request" with no indication of what actually went wrong.

2. Silent failures and missing features in llguidance backend: When an invalid schema is provided, the matcher is created in an error state but this wasn't being checked. Generation would proceed and return empty output with no error indication. Additionally, rollback() was not implemented, causing speculative decoding to fail.

Modifications

Error propagation across all grammar backends:

• Add InvalidGrammarObject(BaseGrammarObject) class in base_grammar_backend.py with an error_message field to carry the original compilation error
• Replace opaque INVALID_GRAMMAR_OBJ sentinel returns with InvalidGrammarObject in all backends
• Update grammar_manager.py to use InvalidGrammarObject and include error_message in user-facing abort messages
• Update reasoner_grammar_backend.py to use InvalidGrammarObject

Improved error message format:

• Replaced verbose debug-style messages (e.g., Invalid grammar request: req.grammar_key=('json', '{"type": "strng"}')) with a clean, user-friendly format: Failed to compile json grammar: JSON schema has unsupported type 'strng'
• The grammar input is no longer included in the error message since the user already knows what they sent; the value is in the server-side log

llguidance backend improvements:

• Add _check_err() helper method that validates matcher state and raises descriptive errors
• Check for errors immediately after matcher creation in __init__()
• Check for errors after all matcher operations (accept_token, rollback, fill_vocab_mask)
• Implement rollback() method with proper EOS token handling for speculative decoding
• Add is_terminated() method

Accuracy Tests

Benchmarking and Profiling

Checklist

• Format your code according to the Format code with pre-commit.
• Add unit tests according to the Run and add unit tests.
• Update documentation according to Write documentations.
• Provide accuracy and speed benchmark results according to Test the accuracy and Benchmark the speed.
• Follow the SGLang code style guidance.

Review Process

1. Ping Merge Oncalls to start the PR flow. See the PR Merge Process.
2. Get approvals from CODEOWNERS and other reviewers.
3. Trigger CI tests with comments or contact authorized users to do so.
   • /tag-run-ci-label, /rerun-failed-ci, /tag-and-rerun-ci
4. After green CI and required approvals, ask Merge Oncalls to merge.