oxibonsai_runtime/constrained_decoding/mod.rs
1//! Grammar-constrained decoding for token-by-token generation.
2//!
3//! This module provides the [`TokenConstraint`] trait and concrete implementations
4//! that restrict which tokens the model can emit at each decoding step:
5//!
6//! - [`NoConstraint`] — passthrough, all tokens allowed
7//! - [`RegexConstraint`] — restricts output to strings matching a regex pattern
8//! - [`JsonConstraint`] — restricts output to syntactically valid JSON
9//! - [`AllowListConstraint`] — restricts output to one of a finite set of token sequences
10//! - [`SequenceConstraint`] — forces output to reproduce a specific token sequence
11//! - [`LengthConstraint`] — enforces hard minimum and maximum generation lengths
12//!
13//! The [`ConstrainedSampler`] wraps a [`crate::sampling_advanced::SamplerChain`] and
14//! applies a mask to logits before sampling so that only valid continuations are drawn.
15//!
16//! ## Example
17//! ```rust
18//! use oxibonsai_runtime::constrained_decoding::{ConstrainedSamplerBuilder, TokenConstraint};
19//!
20//! let mut sampler = ConstrainedSamplerBuilder::new(128, 42)
21//! .with_json_constraint();
22//! assert!(!sampler.is_complete());
23//! ```
24//!
25//! # Module structure
26//!
27//! Phase 30B split the monolithic `constrained_decoding.rs` (1966 lines) into
28//! focused sub-modules; all external `crate::constrained_decoding::*` access
29//! paths are preserved through the re-exports below.
30//!
31//! - [`error_trait`][] — [`ConstraintError`], the [`TokenConstraint`] trait,
32//! and the passthrough [`NoConstraint`].
33//! - [`regex`][] — NFA-based [`RegexConstraint`].
34//! - [`json`][] — JSON-grammar [`JsonConstraint`] and its [`JsonParseState`].
35//! - [`sampler`][] — [`ConstrainedSampler`] and [`ConstrainedSamplerBuilder`].
36//! - [`allow_list`][] — [`AllowListConstraint`].
37//! - [`sequence`][] — [`SequenceConstraint`].
38//! - [`length`][] — [`LengthConstraint`].
39
40mod allow_list;
41mod error_trait;
42mod json;
43mod length;
44mod regex;
45mod sampler;
46mod sequence;
47
48pub use allow_list::AllowListConstraint;
49pub use error_trait::{ConstraintError, NoConstraint, TokenConstraint};
50pub use json::{JsonConstraint, JsonParseState};
51pub use length::LengthConstraint;
52pub use regex::RegexConstraint;
53pub use sampler::{ConstrainedSampler, ConstrainedSamplerBuilder};
54pub use sequence::SequenceConstraint;