nbxgrammar 0.1.0__tar.gz

nbxgrammar-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to nbxgrammar are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - unreleased
+
+### Added
+- **The grammar engine**: a JSON Schema subset and grammar descriptions (literals, schemas, sequences, choices,
+  repetitions, free text up to a terminator or a special token, token ids) compiled into a matcher; per-step token
+  masks over a tokenizer's byte vocabulary, string-safe and free-text tokens cached once per vocabulary; any constraint
+  it cannot enforce refused by name.
+- **The Python package**: `Grammar.json_schema`, `Grammar.description`, `Vocab`, `Matcher.mask / advance / accepting`,
+  through the library's C ABI with `ctypes`; one wheel per platform (`py3-none-<platform>`) for Linux x86_64 and
+  aarch64, macOS arm64 and x86_64, Windows x86_64.

nbxgrammar-0.1.0/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "nbxgrammar"
+version = "0.1.0"

nbxgrammar-0.1.0/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "nbxgrammar"
+version = "0.1.0"
+edition = "2021"
+description = "NeuroBrix's grammar engine for constrained decoding: JSON Schema and tool-call envelopes to per-step token masks (std only)"
+license = "Apache-2.0"
+publish = false
+repository = "https://github.com/NeuroBrix/nbxgrammar"
+homepage = "https://neurobrix.org"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+panic = "abort"

nbxgrammar-0.1.0/LICENSE

@@ -0,0 +1,189 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Neural Networks Holding LTD
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

nbxgrammar-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include Cargo.toml Cargo.lock rust-toolchain.toml LICENSE NOTICE README.md CHANGELOG.md
+recursive-include src *.rs
+recursive-include tests *.rs
+recursive-include examples *.rs
+recursive-include tests_py *.py
+prune target

nbxgrammar-0.1.0/NOTICE

@@ -0,0 +1,8 @@
+nbxgrammar
+Copyright 2025–2026 Hocine Benkelaya
+Owner of the NeuroBrix project (the Owner under the Contributor Assignment Agreement): Hocine Benkelaya
+
+Supported and funded by Neural Network Holding Ltd (https://neuralnetworkholding.com).
+Commercial distribution by WizWorks OÜ (https://wizworks.io).
+
+This product is released under the Apache License 2.0 (LICENSE). It carries no third-party code: the crate uses the Rust standard library only.

nbxgrammar-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: nbxgrammar
+Version: 0.1.0
+Summary: NeuroBrix's grammar engine for constrained decoding: JSON Schema and tool-call envelopes to per-step token masks
+Author-email: The NeuroBrix project <contact@neurobrix.org>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://neurobrix.org
+Project-URL: Source, https://github.com/NeuroBrix/nbxgrammar
+Project-URL: Documentation, https://docs.neurobrix.org
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.22
+Dynamic: license-file
+
+# nbxgrammar
+
+NeuroBrix's grammar engine for constrained decoding. It compiles a JSON Schema, or a description of a tool-call
+format, into a matcher that gives at every decoding step the mask of the tokens a model may write next — so the output
+can only be what the schema or the format allows. It is the engine behind `response_format: json_schema` and forced
+`tool_choice` in [NeuroBrix](https://github.com/NeuroBrix/neurobrix)'s OpenAI-compatible server.
+
+Written in Rust with the standard library only, loaded from Python with `ctypes` (no binding library). One wheel per
+platform serves every Python 3.
+
+```bash
+pip install nbxgrammar
+```
+
+```python
+import json, numpy as np, nbxgrammar as G
+
+grammar = G.Grammar.json_schema(json.dumps({"type": "object", "properties": {"city": {"type": "string"}},
+                                            "required": ["city"]}))
+vocab = G.Vocab(token_bytes, eos_ids)        # each token id's bytes (None for a special token), the end-of-sequence ids
+matcher = G.Matcher(grammar)
+mask = matcher.mask(vocab)                    # int32 words, ceil(vocab / 32): bit v % 32 of word v // 32 = token v allowed
+matcher.advance(vocab, token_id)              # the token the sampler chose
+```
+
+## What it enforces
+
+- **JSON Schema, a subset**: objects (`properties`, `required`; no other property is generated), arrays (`items`,
+  `minItems`, `maxItems`), strings, numbers, integers, booleans, null, `enum`, `const`, `anyOf` whose alternatives start
+  differently, `$ref` into `$defs`. Any other constraining keyword is refused by name (a `ValueError`), never ignored;
+  annotations (`title`, `description`, `default`, `examples`, ...) are read as annotations.
+- **Descriptions**: literals, schemas, sequences, choices by a literal prefix, repetitions with a separator, free text up
+  to a terminator (`until`, optionally ended by a special token), and exact token ids — what a chat template's tool-call
+  format is made of.
+- **Whitespace**: at most one space where JSON allows whitespace inside a value, never a newline, and none around a
+  JSON root.
+
+Measured on Qwen3's vocabulary (151 936 tokens, Apple M4 Pro): a mask in about 15 µs median inside JSON, 73 µs in free
+text.
+
+## Building from source
+
+The crate pins its toolchain (`rust-toolchain.toml`). `pip install .` builds the library with `cargo` and places it in
+the package; `cargo test --release` runs the oracle tests (every mask against a brute force over the vocabulary, every
+completed output against an independent validator).
+
+## License
+
+Apache License 2.0 ([LICENSE](LICENSE)); see [NOTICE](NOTICE). Contributions are made under the
+[NeuroBrix Contributor Assignment Agreement](https://github.com/NeuroBrix/neurobrix/blob/main/docs/legal/contributor-assignment-agreement.md)
+([CONTRIBUTING.md](CONTRIBUTING.md)).
+
+Project: [neurobrix.org](https://neurobrix.org) · documentation: [docs.neurobrix.org](https://docs.neurobrix.org) ·
+contact@neurobrix.org

nbxgrammar-0.1.0/README.md

@@ -0,0 +1,54 @@
+# nbxgrammar
+
+NeuroBrix's grammar engine for constrained decoding. It compiles a JSON Schema, or a description of a tool-call
+format, into a matcher that gives at every decoding step the mask of the tokens a model may write next — so the output
+can only be what the schema or the format allows. It is the engine behind `response_format: json_schema` and forced
+`tool_choice` in [NeuroBrix](https://github.com/NeuroBrix/neurobrix)'s OpenAI-compatible server.
+
+Written in Rust with the standard library only, loaded from Python with `ctypes` (no binding library). One wheel per
+platform serves every Python 3.
+
+```bash
+pip install nbxgrammar
+```
+
+```python
+import json, numpy as np, nbxgrammar as G
+
+grammar = G.Grammar.json_schema(json.dumps({"type": "object", "properties": {"city": {"type": "string"}},
+                                            "required": ["city"]}))
+vocab = G.Vocab(token_bytes, eos_ids)        # each token id's bytes (None for a special token), the end-of-sequence ids
+matcher = G.Matcher(grammar)
+mask = matcher.mask(vocab)                    # int32 words, ceil(vocab / 32): bit v % 32 of word v // 32 = token v allowed
+matcher.advance(vocab, token_id)              # the token the sampler chose
+```
+
+## What it enforces
+
+- **JSON Schema, a subset**: objects (`properties`, `required`; no other property is generated), arrays (`items`,
+  `minItems`, `maxItems`), strings, numbers, integers, booleans, null, `enum`, `const`, `anyOf` whose alternatives start
+  differently, `$ref` into `$defs`. Any other constraining keyword is refused by name (a `ValueError`), never ignored;
+  annotations (`title`, `description`, `default`, `examples`, ...) are read as annotations.
+- **Descriptions**: literals, schemas, sequences, choices by a literal prefix, repetitions with a separator, free text up
+  to a terminator (`until`, optionally ended by a special token), and exact token ids — what a chat template's tool-call
+  format is made of.
+- **Whitespace**: at most one space where JSON allows whitespace inside a value, never a newline, and none around a
+  JSON root.
+
+Measured on Qwen3's vocabulary (151 936 tokens, Apple M4 Pro): a mask in about 15 µs median inside JSON, 73 µs in free
+text.
+
+## Building from source
+
+The crate pins its toolchain (`rust-toolchain.toml`). `pip install .` builds the library with `cargo` and places it in
+the package; `cargo test --release` runs the oracle tests (every mask against a brute force over the vocabulary, every
+completed output against an independent validator).
+
+## License
+
+Apache License 2.0 ([LICENSE](LICENSE)); see [NOTICE](NOTICE). Contributions are made under the
+[NeuroBrix Contributor Assignment Agreement](https://github.com/NeuroBrix/neurobrix/blob/main/docs/legal/contributor-assignment-agreement.md)
+([CONTRIBUTING.md](CONTRIBUTING.md)).
+
+Project: [neurobrix.org](https://neurobrix.org) · documentation: [docs.neurobrix.org](https://docs.neurobrix.org) ·
+contact@neurobrix.org

nbxgrammar-0.1.0/examples/bench.rs

@@ -0,0 +1,60 @@
+//! Mask cost per step on a real vocabulary (the owner's gate: < 1 ms CPU on ~150 k tokens): random walks over the
+//! oracle's schemas; median / p99 / max per step, and the schema compile time. Usage: bench <vocab file>
+use nbxgrammar::{json::parse, matcher::Matcher, schema::compile, vocab::Vocab};
+use std::time::Instant;
+
+fn read_vocab(p: &str) -> Vocab {
+    let b = std::fs::read(p).unwrap();
+    let u = |i: &mut usize| { let v = u32::from_le_bytes(b[*i..*i + 4].try_into().unwrap()); *i += 4; v };
+    let mut i = 0;
+    let n = u(&mut i) as usize;
+    let mut toks = Vec::with_capacity(n);
+    for _ in 0..n {
+        let l = u(&mut i);
+        if l == u32::MAX { toks.push(None) } else { toks.push(Some(b[i..i + l as usize].to_vec())); i += l as usize; }
+    }
+    let ne = u(&mut i) as usize;
+    let eos = (0..ne).map(|_| u(&mut i)).collect();
+    Vocab::new(toks, eos)
+}
+
+const SCHEMAS: &[&str] = &[
+    r#"{"type":"object","properties":{"name":{"type":"string"},"n":{"type":"integer"},"ok":{"type":"boolean"}},"required":["name","n"]}"#,
+    r#"{"type":"array","items":{"enum":["alpha","beta",12,1,null]},"minItems":1,"maxItems":8}"#,
+    r#"{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"x":{"type":["number","null"]},"o":{"type":"object","properties":{"a":{"const":true}},"required":["a"]}},"required":["tags"]}"#,
+    r#"{"type":"object","properties":{"location":{"type":"string"},"unit":{"enum":["celsius","fahrenheit"]},"days":{"type":"integer"}},"required":["location","unit"],"additionalProperties":false}"#,
+];
+
+fn main() {
+    let path = std::env::args().nth(1).expect("vocab file");
+    let t0 = Instant::now();
+    let v = read_vocab(&path);
+    println!("vocabulary {} tokens, built (trie + string cache) in {:.0} ms", v.tokens.len(), t0.elapsed().as_secs_f64() * 1e3);
+    let mut rng = 0x2545F4914F6CDD1Du64;
+    let mut next = || { rng ^= rng << 13; rng ^= rng >> 7; rng ^= rng << 17; rng };
+    let mut times: Vec<f64> = Vec::new();
+    let mut compiles: Vec<f64> = Vec::new();
+    for src in SCHEMAS {
+        let t = Instant::now();
+        let schema = compile(&parse(src).unwrap()).unwrap();
+        compiles.push(t.elapsed().as_secs_f64() * 1e6);
+        for _ in 0..30 {
+            let mut m = Matcher::new(&schema);
+            let mut mask = vec![0u32; v.words()];
+            for _ in 0..80 {
+                let t = Instant::now();
+                v.mask(&m, &mut mask);
+                times.push(t.elapsed().as_secs_f64() * 1e6);
+                let allowed: Vec<u32> = (0..v.tokens.len() as u32).filter(|&t| mask[(t >> 5) as usize] >> (t & 31) & 1 == 1).collect();
+                let pick = allowed[(next() % allowed.len() as u64) as usize];
+                if v.eos.contains(&pick) { break; }
+                v.advance(&mut m, pick).unwrap();
+            }
+        }
+    }
+    times.sort_by(|a, b| a.partial_cmp(b).unwrap());
+    let q = |p: f64| times[((times.len() as f64 - 1.0) * p) as usize];
+    println!("mask per step over {} steps: median {:.1} us, p99 {:.1} us, max {:.1} us", times.len(), q(0.5), q(0.99), times[times.len() - 1]);
+    compiles.sort_by(|a, b| a.partial_cmp(b).unwrap());
+    println!("schema compile: median {:.1} us, max {:.1} us", compiles[compiles.len() / 2], compiles[compiles.len() - 1]);
+}

nbxgrammar-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=69", "wheel>=0.42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nbxgrammar"
+version = "0.1.0"
+description = "NeuroBrix's grammar engine for constrained decoding: JSON Schema and tool-call envelopes to per-step token masks"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.9"
+dependencies = ["numpy>=1.22"]
+authors = [{ name = "The NeuroBrix project", email = "contact@neurobrix.org" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Rust",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://neurobrix.org"
+Source = "https://github.com/NeuroBrix/nbxgrammar"
+Documentation = "https://docs.neurobrix.org"
+
+[tool.setuptools]
+package-dir = { "" = "python" }
+packages = ["nbxgrammar"]

nbxgrammar-0.1.0/python/nbxgrammar/__init__.py

@@ -0,0 +1,112 @@
+"""nbxgrammar: NeuroBrix's grammar engine (this repository's Rust crate, std only) through its C ABI, loaded with ctypes - no
+binding library. The shared library lives beside this file (built by the package's build from the crate and placed
+here). Masks are int32 words, ceil(vocab / 32), bit v % 32 of word v // 32 = token v allowed."""
+from __future__ import annotations
+
+import ctypes
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+import numpy as np
+
+_NAME = {"darwin": "libnbxgrammar.dylib", "win32": "nbxgrammar.dll"}.get(sys.platform, "libnbxgrammar.so")
+_PATH = Path(__file__).with_name(_NAME)
+if not _PATH.is_file():
+    raise ImportError(f"nbxgrammar: its library {_PATH} is not in the package (install a wheel: pip install nbxgrammar; from a checkout: pip install .)")
+_lib = ctypes.CDLL(str(_PATH))
+_P, _U32, _SZ = ctypes.c_void_p, ctypes.c_uint32, ctypes.c_size_t
+_lib.ng_vocab_new.restype = _P
+_lib.ng_vocab_new.argtypes = [ctypes.c_char_p, ctypes.POINTER(_U32), _U32, ctypes.POINTER(_U32), _U32]
+_lib.ng_vocab_free.argtypes = [_P]
+_lib.ng_grammar_json_schema.restype = _P
+_lib.ng_grammar_json_schema.argtypes = [ctypes.c_char_p, _SZ, ctypes.c_char_p, _SZ]
+_lib.ng_grammar_description.restype = _P
+_lib.ng_grammar_description.argtypes = [ctypes.c_char_p, _SZ, ctypes.c_char_p, _SZ]
+_lib.ng_grammar_free.argtypes = [_P]
+_lib.ng_matcher_new.restype = _P
+_lib.ng_matcher_new.argtypes = [_P]
+_lib.ng_matcher_free.argtypes = [_P]
+_lib.ng_mask.restype = ctypes.c_int32
+_lib.ng_mask.argtypes = [_P, _P, ctypes.POINTER(_U32), _SZ]
+_lib.ng_advance.restype = ctypes.c_int32
+_lib.ng_advance.argtypes = [_P, _P, _U32]
+_lib.ng_accepting.restype = ctypes.c_int32
+_lib.ng_accepting.argtypes = [_P]
+
+
+class Vocab:
+    """A tokenizer's tokens as bytes (None: a token no grammar emits) and its end-of-sequence ids; built once."""
+
+    def __init__(self, token_bytes: Sequence[Optional[bytes]], eos: Sequence[int]):
+        lens = np.array([0xFFFFFFFF if b is None else len(b) for b in token_bytes], dtype=np.uint32)
+        data = b"".join(b for b in token_bytes if b is not None)
+        e = np.array(list(eos), dtype=np.uint32)
+        self.size = len(lens)
+        self.words = (self.size + 31) // 32
+        self._h = _lib.ng_vocab_new(data, lens.ctypes.data_as(ctypes.POINTER(_U32)), self.size,
+                                    e.ctypes.data_as(ctypes.POINTER(_U32)), len(e))
+        if not self._h:
+            raise ValueError(f"nbxgrammar: an end-of-sequence id of {list(eos)} lies past the {self.size} tokens")
+
+    def __del__(self):
+        if getattr(self, "_h", None):
+            _lib.ng_vocab_free(self._h)
+            self._h = None
+
+
+class Grammar:
+    def __init__(self, handle):
+        self._h = handle
+
+    @classmethod
+    def json_schema(cls, text: str) -> "Grammar":
+        """A JSON schema compiled; ValueError naming the construct when it cannot be enforced."""
+        raw = text.encode("utf-8")
+        err = ctypes.create_string_buffer(512)
+        h = _lib.ng_grammar_json_schema(raw, len(raw), err, len(err))
+        if not h:
+            raise ValueError(err.value.decode("utf-8", "replace"))
+        return cls(h)
+
+    @classmethod
+    def description(cls, text: str) -> "Grammar":
+        """A grammar description (JSON: lit / schema / seq / choice / repeat / until / token) compiled; ValueError
+        naming what cannot be enforced."""
+        raw = text.encode("utf-8")
+        err = ctypes.create_string_buffer(512)
+        h = _lib.ng_grammar_description(raw, len(raw), err, len(err))
+        if not h:
+            raise ValueError(err.value.decode("utf-8", "replace"))
+        return cls(h)
+
+    def __del__(self):
+        if getattr(self, "_h", None):
+            _lib.ng_grammar_free(self._h)
+            self._h = None
+
+
+class Matcher:
+    """One request's position in its grammar (keeps its grammar alive)."""
+
+    def __init__(self, grammar: Grammar):
+        self._grammar = grammar
+        self._h = _lib.ng_matcher_new(grammar._h)
+
+    def mask(self, vocab: Vocab) -> np.ndarray:
+        out = np.zeros(vocab.words, dtype=np.uint32)
+        if _lib.ng_mask(vocab._h, self._h, out.ctypes.data_as(ctypes.POINTER(_U32)), vocab.words) != 0:
+            raise ValueError("nbxgrammar: a mask of the wrong size")
+        return out.view(np.int32)
+
+    def advance(self, vocab: Vocab, token: int) -> None:
+        if _lib.ng_advance(vocab._h, self._h, int(token)) != 0:
+            raise ValueError(f"nbxgrammar: token {token} is not allowed here")
+
+    def accepting(self) -> bool:
+        return bool(_lib.ng_accepting(self._h))
+
+    def __del__(self):
+        if getattr(self, "_h", None):
+            _lib.ng_matcher_free(self._h)
+            self._h = None