[izhuhaoran]

Kimi-K3 can emit structural control markers inside a tool argument's string value. The schema grammar accepts them as text, while the tool-call parser treats them as structure.

This is the original detokenized badcase with prose redacted, the tool renamed to reply, and line breaks added for readability. The control-marker order, argument names, and repeated index="1" are preserved:

<|open|>think<|sep|>[reasoning redacted]<|close|>think<|sep|>
<|open|>response<|sep|>[intro redacted]<|close|>response<|sep|>
<|open|>tools<|sep|>
<|open|>call tool="reply" index="1"<|sep|>
<|open|>argument key="response" type="string"<|sep|>[answer redacted]
<|close|>response<|sep|>
<|open|>tools<|sep|>
<|open|>call tool="reply" index="1"<|sep|>
<|open|>argument key="response" type="string"<|sep|>[follow-up redacted]<|close|>argument<|sep|>
<|open|>argument key="task_progress" type="string"<|sep|>[progress redacted]<|close|>argument<|sep|>
<|close|>call<|sep|>
<|close|>tools<|sep|>
<|close|>message<|sep|>[EOS]

Immediately after [answer redacted], the first response argument is still open. The model emits <|close|>response<|sep|> where it should complete <|close|>argument<|sep|>, then starts another tools/call block before closing the original one. This is not a missing JSON quote: K3 string arguments are raw text. Without exclusions, the grammar can swallow the unexpected markers and repeated call/argument opening as part of the first string, until the later <|close|>argument<|sep|>.

Add optional JSONSchemaFormat.excludes to reserve substrings within string values and property names, including nested JSON:

JSONSchemaFormat(
    json_schema={
        "type": "object",
        "properties": {"message": {"type": "string"}},
        "required": ["message"],
        "additionalProperties": False,
    },
    style="kimi_k3_xml",
    excludes=["<|open|>", "<|close|>", "<|sep|>"],
)

This is a structural-tag format option, not a JSON Schema keyword. It matches emitted text before JSON/XML unescaping, including matches split across tokens. It does not filter token IDs or join separate strings. An omitted or empty list applies no substring filter.

Existing string constraints remain in effect. JSON delimiter quotes and XML wrappers are outside the exclusion scope: <|close|> can still begin a valid <|close|>argument<|sep|> terminator, but cannot continue with response as string content. Tokens spanning a value's end and its enclosing suffix remain valid.

The Kimi-K3 builtin now supplies these three exclusions for every tool-argument schema in auto, required, and forced tool modes. The existing exclude_special_tokens=False option disables this filter. Free-text reasoning/response exclusions retain their current scope.

Compiler changes preserve existing string constraints and fix Unicode range/empty-language handling needed to prevent excluded branches from accepting multibyte or overlong UTF-8 input.

Non-empty exclusions currently reject cohere_xml and minimax_m3_xml; XML styles also reject exclusions starting or ending with formatting whitespace (space, tab, CR, LF). Compilation fails explicitly if constraints cannot be lowered safely or exceed construction budgets.

Validation:

• JSON-schema, structural-tag, Unicode, serialization, and native regression tests; repository formatting/lint checks and TypeScript type checking.
• K3 builtin tests cover default exclusions and opt-out, all three tool-choice modes, raw and nested JSON strings, and complete valid argument/call endings.
• Token-mask replay rejects the original bad output at response, while accepting both the repaired output and the subsequent valid model response. A synthetic vocabulary also verifies split markers and tokens crossing valid end boundaries; mask and accept_token results agree.

[Seven-Streams]

@izhuhaoran Thanks for your contributions! I'll split the pr for further review.

[izhuhaoran]

@izhuhaoran Thanks for your contributions! I'll split the pr for further review.

@Seven-Streams Thanks for helping split this up! Let me know if any changes are needed on my side.

[stu-cao]

We hit the same exclusion/constraint problem while validating DeepSeek V4.1 tool calls; coordinating here rather than opening a duplicate constraint-preservation PR. The downstream frontend consumer is now proposed separately in ai-dynamo/frontend-crates#531 (draft, blocked on constraint-preserving backend support).

A fresh CPU replay with public xgrammar==0.2.8 confirms that JSONSchemaFormat(style="deepseek_v4_1_xml", excludes=["</｜"]) accepts a one-character string despite minLength: 2, maxLength: 3; it emits the warning about ignoring length constraints. The V4.1 guard correctly rejects malformed </｜DSML｜ parameter> text while accepting valid structural endings, so removing the frontend guard is not the desired resolution.

Here is our downstream implementation for review/reuse: preserve the length bounds and represent large raw-string bounds compactly instead of unrolling a full DFA per permitted character count. It is based on public source 9778737 and may need adaptation to this PR's current implementation; I have not tested this patch against your current PR head. Tests include Unicode/code-point bounds and large bounds. This is a bounded/raw-string implementation, not a claim to solve every JSON escaped-string/pattern interaction.

The downstream combination (this backend implementation plus the frontend V4.1 guard/prefix fixes) passed the unchanged 816 official Kimi schema requests and 8 selected tool-choice behaviors with a 2,048-token budget on real DeepSeek V4.1. That is integration evidence for the downstream combination, not proof about this PR or an isolated A/B attribution to these two commits. The frontend draft includes an executable length-constraint merge gate which currently fails against the public backend.

Signed downstream patches: preserve bounds, then compact large raw-string bounds

From 0a7d67e425dedade86a348328e951e4ea8db6343 Mon Sep 17 00:00:00 2001
From: Stu Cao <stu@primeintellect.ai>
Date: Sun, 25 Oct 2026 13:46:04 -0700
Subject: [PATCH 1/2] fix(grammar): preserve string length bounds with
 exclusions

Signed-off-by: Stu Cao <stu@primeintellect.ai>
---
 cpp/json_schema_converter.cc              | 21 ++++----
 python/xgrammar/structural_tag.py         |  2 +-
 tests/python/test_json_schema_excludes.py | 58 ++++++++++++++++-------
 3 files changed, 53 insertions(+), 28 deletions(-)

diff --git a/cpp/json_schema_converter.cc b/cpp/json_schema_converter.cc
index 9261cdf..eeadb01 100644
--- a/cpp/json_schema_converter.cc
+++ b/cpp/json_schema_converter.cc
@@ -2667,14 +2667,17 @@ int32_t JSONSchemaConverter::GenerateString(const StringSpec& spec, const std::s
         {ByteString("\""), RegexExpression(*spec.pattern, /*json_string=*/true), ByteString("\"")}
     );
   }
-  // Check for length constraints. They are dropped when there are exclusions: intersecting the
-  // unrolled bound with the exclusion automaton emits one rule per position and automaton state
-  // (about 18 rules per character for three markers), so the string keeps only the exclusions.
-  // Exclusions apply only to the strings without pattern and format above: those constraints
-  // are the schema's own contract for the string.
+  // Enforce length and exclusions together. Each regex atom is one decoded character,
+  // including JSON escapes and a paired UTF-16 surrogate escape.
   if (spec.min_length != 0 || spec.max_length != -1) {
     if (!excludes_.empty()) {
-      WarnDroppedLengthConstraints(spec, rule_name);
+      const std::string atom =
+          R"(([^"\\\x00-\x1f]|\\(["\\/bfnrt]|u([dD][89aAbB][0-9a-fA-F]{2}\\u[dD][c-fC-F][0-9a-fA-F]{2}|[0-9a-cA-Ce-fE-F][0-9a-fA-F]{3}|[dD][0-7c-fC-F][0-9a-fA-F]{2}))))";
+      const std::string bounds = "{" + std::to_string(spec.min_length) + "," +
+                                 (spec.max_length < 0 ? "" : std::to_string(spec.max_length)) + "}";
+      return Sequence(
+          {ByteString("\""), ExcludingString(atom + bounds, rule_name, false), ByteString("\"")}
+      );
     } else {
       int32_t character =
           builder_.AddCharacterClass({{'"', '"'}, {'\\', '\\'}, {'\r', '\r'}, {'\n', '\n'}}, true);
@@ -3876,10 +3879,10 @@ int32_t XMLToolCallingConverter::GenerateString(
           spec.max_length
       );
     }
-    // With exclusions the raw string keeps only the exclusions: length constraints are dropped
-    // (see JSONSchemaConverter::GenerateString) and an unrecognized format is unconstrained.
     if (bounded) {
-      WarnDroppedLengthConstraints(spec, rule_name);
+      const std::string bounds = "{" + std::to_string(spec.min_length) + "," +
+                                 (spec.max_length < 0 ? "" : std::to_string(spec.max_length)) + "}";
+      return ExcludingString("[\\s\\S]" + bounds, rule_name, false);
     }
     return RuleRef(kXMLString);
   }
diff --git a/python/xgrammar/structural_tag.py b/python/xgrammar/structural_tag.py
index 8003d66..5efcd79 100644
--- a/python/xgrammar/structural_tag.py
+++ b/python/xgrammar/structural_tag.py
@@ -69,7 +69,7 @@ class JSONSchemaFormat(BaseModel):
     property names, nested JSON strings included. Matches the emitted text before JSON/XML
     unescaping; quotes, punctuation and XML parameter wrappers are never part of a match. A string
     with ``pattern`` or ``format`` is matched by that constraint alone and is not filtered;
-    ``minLength``/``maxLength`` are dropped with a warning and the string is filtered;
+    ``minLength``/``maxLength`` are enforced together with the exclusions;
     ``const``/``enum`` alternatives containing an excluded substring are removed. XML styles reject
     exclusions that start or end with whitespace; ``cohere_xml`` and ``minimax_m3_xml`` reject
     non-empty lists."""
diff --git a/tests/python/test_json_schema_excludes.py b/tests/python/test_json_schema_excludes.py
index 613efb9..fbfc9ed 100644
--- a/tests/python/test_json_schema_excludes.py
+++ b/tests/python/test_json_schema_excludes.py
@@ -81,27 +81,16 @@ def test_pattern_and_format_strings_are_not_filtered(style, schema, accepted, re
         {"type": "string", "minLength": 2, "maxLength": 3},
     ],
 )
-def test_excludes_drop_length_constraints(style, schema, capfd):
-    # Bounding the length of a filtered string multiplies the grammar by the bound, so the
-    # length constraints are dropped when exclusions are present; the exclusions still apply.
-    bounded = leaf_grammar(schema, style, excludes=[])
+def test_excludes_preserve_length_constraints(style, schema, capfd):
+    grammar = leaf_grammar(schema, style, excludes=["bc", "cb"])
     assert "Ignoring" not in capfd.readouterr().err
-    unbounded = leaf_grammar(schema, style, excludes=["bc", "cb"])
-    warning = capfd.readouterr().err
-    assert "Ignoring" in warning and "JSONSchemaFormat.excludes" in warning
-    assert f"minLength={schema.get('minLength', 0)}" in warning
-    assert f"maxLength={schema.get('maxLength', -1)}" in warning
-    plain = leaf_grammar({"type": "string"}, style, excludes=["bc", "cb"])
-    # Same rules as the unbounded string (up to the reference to the shared string rule), not
-    # one rule per position and exclusion state.
-    assert str(unbounded).count("::=") <= str(plain).count("::=") + 1
-    for value in ("a", "abde", "ax" * 10):
-        assert _is_grammar_accept_string(unbounded, string_instance(value, style))
-        assert _is_grammar_accept_string(bounded, string_instance(value, style)) == (
+    for value in ("", "a", "ab", "abc", "你好", "你好🦋", "abde", "ax" * 10):
+        expected = (
             schema.get("minLength", 0) <= len(value) <= schema.get("maxLength", 10**9)
+            and "bc" not in value
+            and "cb" not in value
         )
-    for value in ("bc", "acbz", "a" * 20 + "bc"):
-        assert not _is_grammar_accept_string(unbounded, string_instance(value, style))
+        assert _is_grammar_accept_string(grammar, string_instance(value, style)) == expected
 
 
 @pytest.mark.parametrize("style", ["json", "kimi_k3_xml"])
@@ -664,3 +653,36 @@ def test_deepseek_v41_excludes_preserve_value_type_and_parameter_end():
     for body in ('true">BAD', 'false">{"text":"BAD"}', 'false">"safe"'):
         assert not _is_grammar_accept_string(grammar, prefix + body + end)
     assert not _is_grammar_accept_string(grammar, prefix + 'false">{"text":"' + end + '"}' + end)
+
+
+@pytest.mark.parametrize("style", ["deepseek_v4_1_xml", "json"])
+@pytest.mark.parametrize("minimum,maximum", [(5, None), (0, 5), (2, 5)])
+def test_v41_length_and_closing_marker_exclusion(style, minimum, maximum):
+    leaf = {"type": "string", "minLength": minimum}
+    if maximum is not None:
+        leaf["maxLength"] = maximum
+    schema = {
+        "type": "object",
+        "properties": {"value": leaf},
+        "required": ["value"],
+        "additionalProperties": False,
+    }
+    grammar = xgr.Grammar.from_structural_tag(schema_tag(schema, style, ["</｜DSML｜"]))
+    for value in ["a", "abcde", "abcdef", "你好🦋ab", "</｜DSML｜  parameter>"]:
+        wire = (
+            f'<｜DSML｜ parameter name="value" string="true">{value}</｜DSML｜ parameter>'
+            if style != "json"
+            else json.dumps({"value": value}, ensure_ascii=False)
+        )
+        expected = (
+            minimum <= len(value)
+            and (maximum is None or len(value) <= maximum)
+            and "</｜DSML｜" not in value
+        )
+        assert _is_grammar_accept_string(grammar, wire) == expected
+
+
+def test_excluded_bounded_json_counts_escaped_characters():
+    grammar = leaf_grammar({"type": "string", "minLength": 2, "maxLength": 2}, "json", ["BAD"])
+    for value in [chr(10) + chr(34), "🦋a", "你好", "a", "abc"]:
+        assert _is_grammar_accept_string(grammar, json.dumps(value)) == (len(value) == 2)
-- 
2.50.1 (Apple Git-155)


From 3aa1314fc8f0fa94dec3ff6fbceb38ae7ca5b712 Mon Sep 17 00:00:00 2001
From: Stu Cao <stu@primeintellect.ai>
Date: Sun, 25 Oct 2026 14:19:03 -0700
Subject: [PATCH 2/2] fix(grammar): encode large raw-string bounds compactly

Signed-off-by: Stu Cao <stu@primeintellect.ai>
---
 cpp/json_schema_converter.cc              | 78 +++++++++++++++++++++--
 cpp/json_schema_converter.h               |  4 +-
 tests/python/test_json_schema_excludes.py | 20 ++++++
 3 files changed, 97 insertions(+), 5 deletions(-)

diff --git a/cpp/json_schema_converter.cc b/cpp/json_schema_converter.cc
index eeadb01..8f736b8 100644
--- a/cpp/json_schema_converter.cc
+++ b/cpp/json_schema_converter.cc
@@ -2339,7 +2339,9 @@ int32_t JSONSchemaConverter::ExcludingString(
     const std::string& regex,
     const std::string& rule_name,
     bool close_json_string,
-    const std::vector<std::string>& excluded_keys
+    const std::vector<std::string>& excluded_keys,
+    int min_length,
+    int max_length
 ) {
   auto parsed = GrammarFSMBuilder::Regex(regex, false);
   XGRAMMAR_CHECK(parsed.IsOk()) << "Cannot build the FSM of " << regex << ": "
@@ -2440,6 +2442,7 @@ int32_t JSONSchemaConverter::ExcludingString(
     return it->second;
   };
 
+  std::map<std::pair<int, int>, int32_t> one_character;
   std::vector<int32_t> rules(fsm.NumStates(), -1);
   std::vector<int> pending{fsm.GetStart()};
   // Share complete fallback branches across key prefixes to reuse their token masks.
@@ -2490,6 +2493,9 @@ int32_t JSONSchemaConverter::ExcludingString(
       choices.push_back(close_json_string ? ByteString("\"") : Empty());
     }
     for (const auto& [target, codepoints] : transitions) {
+      if (min_length >= 0) {
+        one_character[{state, target}] = builder_.AddCharacterClass(codepoints);
+      }
       if (rules[target] == -1) {
         rules[target] = builder_.AddEmptyRuleWithHint(rule_name + "_exclude");
         pending.push_back(target);
@@ -2522,6 +2528,72 @@ int32_t JSONSchemaConverter::ExcludingString(
     }
     builder_.UpdateRuleBody(rules[state], Choice(choices));
   }
+  if (min_length >= 0) {
+    // Count raw Unicode codepoints without unrolling a potentially multi-million-character
+    // bound into an FSM. Nonterminals describe paths between exclusion-DFA states. Splitting
+    // exact lengths and ranges in half shares O(log(bound)) length levels.
+    XGRAMMAR_CHECK(!close_json_string);
+    using Key = std::tuple<int64_t, int, int>;
+    std::map<Key, int32_t> exact_cache, range_cache;
+    auto make_rule = [&](const std::vector<int32_t>& choices) -> int32_t {
+      if (choices.empty()) return -1;
+      return RuleRef(builder_.AddRuleWithHint(rule_name + "_bounded", Choice(choices)));
+    };
+    std::function<int32_t(int64_t, int, int)> exact = [&](int64_t n, int from, int to) -> int32_t {
+      Key key{n, from, to};
+      if (auto it = exact_cache.find(key); it != exact_cache.end()) return it->second;
+      int32_t result = -1;
+      if (n == 0) {
+        result = from == to ? Empty() : -1;
+      } else if (n == 1) {
+        auto it = one_character.find({from, to});
+        if (it != one_character.end()) result = it->second;
+      } else {
+        std::vector<int32_t> choices;
+        for (int mid : pending) {
+          auto left = exact(n / 2, from, mid);
+          if (left < 0) continue;
+          auto right = exact(n - n / 2, mid, to);
+          if (right >= 0) choices.push_back(Sequence({left, right}));
+        }
+        result = make_rule(choices);
+      }
+      exact_cache[key] = result;
+      return result;
+    };
+    std::function<int32_t(int64_t, int, int)> upto = [&](int64_t n, int from, int to) -> int32_t {
+      Key key{n, from, to};
+      if (auto it = range_cache.find(key); it != range_cache.end()) return it->second;
+      if (n == 0) return from == to ? Empty() : -1;
+      std::vector<int32_t> choices;
+      auto shorter = upto(n / 2, from, to);
+      if (shorter >= 0) choices.push_back(shorter);
+      for (int mid : pending) {
+        auto left = exact(n / 2 + 1, from, mid);
+        if (left < 0) continue;
+        auto right = upto(n - n / 2 - 1, mid, to);
+        if (right >= 0) choices.push_back(Sequence({left, right}));
+      }
+      auto result = make_rule(choices);
+      range_cache[key] = result;
+      return result;
+    };
+    std::vector<int32_t> choices;
+    for (int mid : pending) {
+      auto prefix = exact(min_length, fsm.GetStart(), mid);
+      if (prefix < 0) continue;
+      if (max_length < 0) {
+        choices.push_back(Sequence({prefix, RuleRef(rules[mid])}));
+      } else {
+        for (int end : pending) {
+          if (!fsm.IsEndState(end)) continue;
+          auto suffix = upto(static_cast<int64_t>(max_length) - min_length, mid, end);
+          if (suffix >= 0) choices.push_back(Sequence({prefix, suffix}));
+        }
+      }
+    }
+    return choices.empty() ? Unsatisfiable() : Choice(choices);
+  }
   return RuleRef(rules[fsm.GetStart()]);
 }
 
@@ -3880,9 +3952,7 @@ int32_t XMLToolCallingConverter::GenerateString(
       );
     }
     if (bounded) {
-      const std::string bounds = "{" + std::to_string(spec.min_length) + "," +
-                                 (spec.max_length < 0 ? "" : std::to_string(spec.max_length)) + "}";
-      return ExcludingString("[\\s\\S]" + bounds, rule_name, false);
+      return ExcludingString("[\\s\\S]*", rule_name, false, {}, spec.min_length, spec.max_length);
     }
     return RuleRef(kXMLString);
   }
diff --git a/cpp/json_schema_converter.h b/cpp/json_schema_converter.h
index 8ca4896..0ce55bb 100644
--- a/cpp/json_schema_converter.h
+++ b/cpp/json_schema_converter.h
@@ -431,7 +431,9 @@ class JSONSchemaConverter {
       const std::string& regex,
       const std::string& rule_name,
       bool close_json_string,
-      const std::vector<std::string>& excluded_keys = {}
+      const std::vector<std::string>& excluded_keys = {},
+      int min_length = -1,
+      int max_length = -1
   );
   bool IsAllowedString(const std::string& text) const;
   bool IsAllowedLiteral(const picojson::value& value, bool raw_string = false) const;
diff --git a/tests/python/test_json_schema_excludes.py b/tests/python/test_json_schema_excludes.py
index fbfc9ed..257ebdc 100644
--- a/tests/python/test_json_schema_excludes.py
+++ b/tests/python/test_json_schema_excludes.py
@@ -686,3 +686,23 @@ def test_excluded_bounded_json_counts_escaped_characters():
     grammar = leaf_grammar({"type": "string", "minLength": 2, "maxLength": 2}, "json", ["BAD"])
     for value in [chr(10) + chr(34), "🦋a", "你好", "a", "abc"]:
         assert _is_grammar_accept_string(grammar, json.dumps(value)) == (len(value) == 2)
+
+
+@pytest.mark.parametrize("minimum,maximum", [(0, 5_000_000), (5, 5_000_000), (0, 0), (2, 7)])
+def test_v41_compact_large_length_bound(minimum, maximum):
+    schema = {
+        "type": "object",
+        "properties": {"value": {"type": "string", "minLength": minimum, "maxLength": maximum}},
+        "required": ["value"],
+        "additionalProperties": False,
+    }
+    grammar = xgr.Grammar.from_structural_tag(schema_tag(schema, "deepseek_v4_1_xml", ["</｜"]))
+    assert len(str(grammar)) < 2_000_000
+    for length in range(11):
+        value = "a" * length
+        wire = f'<｜DSML｜ parameter name="value" string="true">{value}</｜DSML｜ parameter>'
+        assert _is_grammar_accept_string(grammar, wire) == (minimum <= length <= maximum)
+    assert not _is_grammar_accept_string(
+        grammar,
+        '<｜DSML｜ parameter name="value" string="true">aaaaa</｜DSML parameter></｜DSML｜ parameter>',
+    )
-- 
2.50.1 (Apple Git-155)