inferencelayer/grammar/mod.rs
1//! General structured-output grammar: a schema → flat-table → byte-FSM pipeline for GPU-resident
2//! constrained decoding (Workstream G).
3//!
4//! G1 (this module) is CPU-only and the REFERENCE for everything downstream: the same compiled
5//! tables the CPU FSM here interprets are the buffers the WGSL interpreter (G2) will upload and read,
6//! and the serving layer (G3) drives this FSM at the per-column pick-override seam. Keeping one
7//! table-interpreter — rather than compiling a shader per schema — is the design's core bet, and it
8//! is de-risked HERE: any JSON-Schema construct that cannot be encoded in the tables surfaces as a
9//! pure-Rust compile error before a single byte is generated.
10//!
11//! Three pieces:
12//! - [`json_schema`] — [`JsonSchemaTables::compile`] turns a `serde_json::Value` schema into flat
13//! `u32`/`u8` tables (or refuses, naming the construct). See its docs for the exact array layout.
14//! - [`json_fsm`] — [`JsonFsm`] walks those tables byte-by-byte over a fixed [`json_fsm::STATE_WORDS`]
15//! -word [`FsmState`]: `step_byte`, `allowed_bytes` (the constrained-decode mask), `is_complete`,
16//! and `step_token`.
17//! - [`token_bytes`] — [`TokenByteTable`] maps a tokenizer's token ids to raw output bytes (byte-level
18//! BPE via the engine's `vocab::build_vocab_blob`, with an SPM/Unigram fallback), so the FSM can be
19//! advanced one whole token at a time.
20//!
21//! ## Supported subset (OpenAI strict mode)
22//!
23//! `object`/`array`/`string`/`number`/`integer`/`boolean`/`null`; `properties` + `required` with
24//! every property required and matched in the `required` array's order (that array is the canonical
25//! key order — a parsed `properties` object cannot preserve declaration order without serde_json's
26//! `preserve_order`, which this workspace does not enable); mandatory `additionalProperties:false`;
27//! `enum`/`const` over scalars; bounded arrays and strings; nesting depth ≤ 10; canonical output with
28//! no whitespace. `pattern`/`anyOf`/`oneOf`/`allOf`/`$ref`/`format`/`minimum`/… are refused loudly,
29//! with reserved node-kind discriminants ([`NodeKind::RESERVED_PATTERN`] et al.) held for the future
30//! regex-DFA extension.
31
32mod flat_ref;
33pub mod gpu;
34pub mod harness;
35pub mod json_fsm;
36pub mod json_schema;
37pub mod token_bytes;
38
39pub use gpu::{GpuGrammar, GrammarKernels, GrammarVocab};
40pub use harness::{GpuSchema, GpuVocab, SchemaMeta};
41pub use json_fsm::{FsmState, JsonFsm};
42pub use json_schema::{JsonSchemaTables, NodeKind};
43pub use token_bytes::TokenByteTable;