Build at Sat Dec 7 12:25:30 UTC 2024

docs/docs/api/python/index.html

@@ -381,7 +381,7 @@
 <tr class="row-even"><td><p><a class="reference internal" href="#xgrammar.Grammar.from_ebnf" title="xgrammar.Grammar.from_ebnf"><code class="xref py py-obj docutils literal notranslate"><span class="pre">from_ebnf</span></code></a>(ebnf_string, *[, root_rule_name])</p></td>
 <td><p>Construct a grammar from EBNF string.</p></td>
 </tr>
-<tr class="row-odd"><td><p><a class="reference internal" href="#xgrammar.Grammar.from_json_schema" title="xgrammar.Grammar.from_json_schema"><code class="xref py py-obj docutils literal notranslate"><span class="pre">from_json_schema</span></code></a>(schema, *[, indent, ...])</p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="#xgrammar.Grammar.from_json_schema" title="xgrammar.Grammar.from_json_schema"><code class="xref py py-obj docutils literal notranslate"><span class="pre">from_json_schema</span></code></a>(schema, *[, ...])</p></td>
 <td><p>Construct a grammar from JSON schema.</p></td>
 </tr>
 </tbody>
@@ -418,24 +418,34 @@
 
 <dl class="py method">
 <dt class="sig sig-object py" id="xgrammar.Grammar.from_json_schema">
-<em class="property"><span class="pre">static</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_json_schema</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">schema</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Union</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Type</span><span class="p"><span class="pre">[</span></span><span class="pre">BaseModel</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">indent</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">separators</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">Tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_mode</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#xgrammar.Grammar" title="xgrammar.grammar.Grammar"><span class="pre">Grammar</span></a></span></span><a class="headerlink" href="#xgrammar.Grammar.from_json_schema" title="Permalink to this definition">¶</a></dt>
+<em class="property"><span class="pre">static</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_json_schema</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">schema</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Union</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Type</span><span class="p"><span class="pre">[</span></span><span class="pre">BaseModel</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">any_whitespace</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">indent</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">separators</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">Tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_mode</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#xgrammar.Grammar" title="xgrammar.grammar.Grammar"><span class="pre">Grammar</span></a></span></span><a class="headerlink" href="#xgrammar.Grammar.from_json_schema" title="Permalink to this definition">¶</a></dt>
 <dd><p>Construct a grammar from JSON schema. Pydantic model or JSON schema string can be
 used to specify the schema.</p>
-<p>The format of the JSON schema can be specified with the <cite>indent</cite> and <cite>separators</cite>
-parameters. The meaning and the default values of the parameters follows the convention in
-json.dumps().</p>
+<p>It allows any whitespace by default. If user want to specify the format of the JSON,
+set <cite>any_whitespace</cite> to False and use the <cite>indent</cite> and <cite>separators</cite> parameters. The
+meaning and the default values of the parameters follows the convention in json.dumps().</p>
 <p>It internally converts the JSON schema to a EBNF grammar.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>schema</strong> (<em>Union</em><em>[</em><em>str</em><em>, </em><em>Type</em><em>[</em><em>BaseModel</em><em>]</em><em>]</em>) – The schema string or Pydantic model.</p></li>
-<li><p><strong>indent</strong> (<em>Optional</em><em>[</em><em>int</em><em>]</em><em>, </em><em>default: None</em>) – The number of spaces for indentation. If None, the output will be in one line.</p></li>
+<li><p><strong>any_whitespace</strong> (<em>bool</em><em>, </em><em>default: True</em>) – Whether to use any whitespace. If True, the generated grammar will ignore the
+indent and separators parameters, and allow any whitespace.</p></li>
+<li><p><strong>indent</strong> (<em>Optional</em><em>[</em><em>int</em><em>]</em><em>, </em><em>default: None</em>) – <p>The number of spaces for indentation. If None, the output will be in one line.</p>
+<p>Note that specifying the indentation means forcing the LLM to generate JSON strings
+strictly formatted. However, some models may tend to generate JSON strings that
+are not strictly formatted. In this case, forcing the LLM to generate strictly
+formatted JSON strings may degrade the generation quality. See
+&lt;<a class="reference external" href="https://github.com/sgl-project/sglang/issues/2216#issuecomment-2516192009">https://github.com/sgl-project/sglang/issues/2216#issuecomment-2516192009</a>&gt; for more
+details.</p>
+</p></li>
 <li><p><strong>separators</strong> (<em>Optional</em><em>[</em><em>Tuple</em><em>[</em><em>str</em><em>, </em><em>str</em><em>]</em><em>]</em><em>, </em><em>default: None</em>) – Two separators used in the schema: comma and colon. Examples: (“,”, “:”), (”, “, “: “).
 If None, the default separators will be used: (“,”, “: “) when the indent is not None,
 and (”, “, “: “) otherwise.</p></li>
 <li><p><strong>strict_mode</strong> (<em>bool</em><em>, </em><em>default: True</em>) – <p>Whether to use strict mode. In strict mode, the generated grammar will not allow
 properties and items that is not specified in the schema. This is equivalent to
-setting unevaluatedProperties and unevaluatedItems to false.</p>
+setting unevaluatedProperties and unevaluatedItems to false. It also disallows empty
+JSON objects and arrays.</p>
 <p>This helps LLM to generate accurate output in the grammar-guided generation with JSON
 schema.</p>
 </p></li>
@@ -477,7 +487,7 @@
 <tr class="row-even"><td><p><a class="reference internal" href="#xgrammar.GrammarCompiler.compile_builtin_json_grammar" title="xgrammar.GrammarCompiler.compile_builtin_json_grammar"><code class="xref py py-obj docutils literal notranslate"><span class="pre">compile_builtin_json_grammar</span></code></a>()</p></td>
 <td><p>Get CompiledGrammar from the standard JSON.</p></td>
 </tr>
-<tr class="row-odd"><td><p><a class="reference internal" href="#xgrammar.GrammarCompiler.compile_json_schema" title="xgrammar.GrammarCompiler.compile_json_schema"><code class="xref py py-obj docutils literal notranslate"><span class="pre">compile_json_schema</span></code></a>(schema, *[, indent, ...])</p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="#xgrammar.GrammarCompiler.compile_json_schema" title="xgrammar.GrammarCompiler.compile_json_schema"><code class="xref py py-obj docutils literal notranslate"><span class="pre">compile_json_schema</span></code></a>(schema, *[, ...])</p></td>
 <td><p>Get CompiledGrammar from the specified JSON schema and format.</p></td>
 </tr>
 </tbody>
@@ -504,7 +514,7 @@
 
 <dl class="py method">
 <dt class="sig sig-object py" id="xgrammar.GrammarCompiler.compile_json_schema">
-<span class="sig-name descname"><span class="pre">compile_json_schema</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">schema</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Union</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Type</span><span class="p"><span class="pre">[</span></span><span class="pre">BaseModel</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">indent</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">separators</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">Tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_mode</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#xgrammar.CompiledGrammar" title="xgrammar.compiler.CompiledGrammar"><span class="pre">CompiledGrammar</span></a></span></span><a class="headerlink" href="#xgrammar.GrammarCompiler.compile_json_schema" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">compile_json_schema</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">schema</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Union</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Type</span><span class="p"><span class="pre">[</span></span><span class="pre">BaseModel</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">any_whitespace</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">indent</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">separators</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">Tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_mode</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#xgrammar.CompiledGrammar" title="xgrammar.compiler.CompiledGrammar"><span class="pre">CompiledGrammar</span></a></span></span><a class="headerlink" href="#xgrammar.GrammarCompiler.compile_json_schema" title="Permalink to this definition">¶</a></dt>
 <dd><p>Get CompiledGrammar from the specified JSON schema and format. The indent
 and separators parameters follow the same convention as in json.dumps().</p>
 <dl class="field-list simple">