1use std::collections::HashSet;
6
7use serde::{Deserialize, Serialize};
8
9use crate::{CoreError, Digest, TokenId};
10
11pub const MAX_DRY_SEQUENCE_BREAKERS: usize = 64;
13pub const MAX_DRY_SEQUENCE_BREAKER_BYTES: usize = 40;
15pub const MAX_LOGIT_BIASES: usize = 65_536;
17pub const MAX_GRAMMAR_SOURCE_BYTES: usize = 1024 * 1024;
19pub const MAX_GRAMMAR_ROOT_BYTES: usize = 256;
21pub const MAX_LAZY_GRAMMAR_TRIGGER_PATTERNS: usize = 64;
23pub const MAX_LAZY_GRAMMAR_TRIGGER_PATTERN_BYTES: usize = 4_096;
25pub const MAX_LAZY_GRAMMAR_TRIGGER_BYTES: usize = 64 * 1_024;
27pub const MAX_LAZY_GRAMMAR_TRIGGER_TOKENS: usize = 4_096;
29pub const MAX_STOP_SEQUENCES: usize = 64;
31pub const MAX_STOP_SEQUENCE_BYTES: usize = 4_096;
33
34#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
36pub struct RepetitionSampler {
37 pub last_n: i32,
39 pub repeat_penalty: f32,
41 pub frequency_penalty: f32,
43 pub presence_penalty: f32,
45}
46
47#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
49pub struct DrySampler {
50 pub multiplier: f32,
52 pub base: f32,
54 pub allowed_length: i32,
56 pub penalty_last_n: i32,
58 pub sequence_breakers: Vec<String>,
60}
61
62#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
64#[serde(rename_all = "snake_case")]
65pub enum MirostatVersion {
66 V1,
68 V2,
70}
71
72#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
74pub struct MirostatSampler {
75 pub version: MirostatVersion,
77 pub tau: f32,
79 pub eta: f32,
81 pub m: i32,
84}
85
86#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
88pub struct SamplingPlan {
89 pub seed: u32,
91 pub temperature: f32,
93 pub top_k: i32,
95 pub top_p: f32,
97 pub min_p: f32,
99 pub typical_p: f32,
101 #[serde(default, skip_serializing_if = "Option::is_none")]
103 pub repetition: Option<RepetitionSampler>,
104 #[serde(default, skip_serializing_if = "Option::is_none")]
106 pub dry: Option<DrySampler>,
107 #[serde(default, skip_serializing_if = "Option::is_none")]
109 pub mirostat: Option<MirostatSampler>,
110}
111
112impl Default for SamplingPlan {
113 fn default() -> Self {
114 Self {
115 seed: 0,
116 temperature: 0.0,
117 top_k: 40,
118 top_p: 0.95,
119 min_p: 0.05,
120 typical_p: 1.0,
121 repetition: None,
122 dry: None,
123 mirostat: None,
124 }
125 }
126}
127
128impl SamplingPlan {
129 pub fn validate(&self) -> Result<(), CoreError> {
135 for (field, value) in [
136 ("temperature", self.temperature),
137 ("top p", self.top_p),
138 ("min p", self.min_p),
139 ("typical p", self.typical_p),
140 ] {
141 if !value.is_finite() {
142 return Err(CoreError::NonFinite { field });
143 }
144 }
145 if self.temperature < 0.0
146 || self.top_k < 0
147 || !(0.0..=1.0).contains(&self.top_p)
148 || !(0.0..=1.0).contains(&self.min_p)
149 || !(0.0..=1.0).contains(&self.typical_p)
150 {
151 return Err(CoreError::invalid(
152 "sampling plan",
153 "temperature/top-k must be non-negative and probabilities must be in 0..=1",
154 ));
155 }
156 if let Some(repetition) = &self.repetition {
157 for (field, value) in [
158 ("repeat penalty", repetition.repeat_penalty),
159 ("frequency penalty", repetition.frequency_penalty),
160 ("presence penalty", repetition.presence_penalty),
161 ] {
162 if !value.is_finite() {
163 return Err(CoreError::NonFinite { field });
164 }
165 }
166 if repetition.last_n < -1 || repetition.repeat_penalty <= 0.0 {
167 return Err(CoreError::invalid(
168 "repetition sampler",
169 "last_n must be at least -1 and repeat_penalty must be positive",
170 ));
171 }
172 }
173 if let Some(dry) = &self.dry {
174 for (field, value) in [("DRY multiplier", dry.multiplier), ("DRY base", dry.base)] {
175 if !value.is_finite() {
176 return Err(CoreError::NonFinite { field });
177 }
178 }
179 if dry.multiplier <= 0.0
180 || dry.base < 1.0
181 || dry.allowed_length < 0
182 || dry.penalty_last_n < -1
183 || dry.penalty_last_n == 0
184 {
185 return Err(CoreError::invalid(
186 "dry sampler",
187 "multiplier must be positive, base at least one, allowed length non-negative, and lookback -1 or positive",
188 ));
189 }
190 if dry.sequence_breakers.len() > MAX_DRY_SEQUENCE_BREAKERS
191 || dry.sequence_breakers.iter().any(|value| {
192 value.is_empty()
193 || value.len() > MAX_DRY_SEQUENCE_BREAKER_BYTES
194 || value.contains('\0')
195 })
196 {
197 return Err(CoreError::invalid(
198 "dry sequence breakers",
199 format!(
200 "requires at most {MAX_DRY_SEQUENCE_BREAKERS} non-empty, NUL-free values of at most {MAX_DRY_SEQUENCE_BREAKER_BYTES} bytes"
201 ),
202 ));
203 }
204 }
205 if let Some(mirostat) = &self.mirostat {
206 for (field, value) in [
207 ("Mirostat tau", mirostat.tau),
208 ("Mirostat eta", mirostat.eta),
209 ] {
210 if !value.is_finite() {
211 return Err(CoreError::NonFinite { field });
212 }
213 }
214 let invalid_window = match mirostat.version {
215 MirostatVersion::V1 => mirostat.m <= 0,
216 MirostatVersion::V2 => mirostat.m != 0,
217 };
218 if self.temperature <= 0.0
219 || mirostat.tau <= 0.0
220 || mirostat.eta <= 0.0
221 || invalid_window
222 {
223 return Err(CoreError::invalid(
224 "mirostat sampler",
225 "temperature, tau, and eta must be positive; m must be positive for v1 and zero for v2",
226 ));
227 }
228 }
229 Ok(())
230 }
231}
232
233#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
235pub struct LogitBias {
236 pub token: TokenId,
238 pub bias: f32,
240}
241
242#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
244pub struct Grammar {
245 pub source: String,
247 pub root: String,
249}
250
251impl Grammar {
252 pub fn validate(&self) -> Result<(), CoreError> {
258 if self.source.is_empty() || self.root.is_empty() {
259 return Err(CoreError::Empty {
260 field: "grammar source/root",
261 });
262 }
263 if self.source.len() > MAX_GRAMMAR_SOURCE_BYTES || self.root.len() > MAX_GRAMMAR_ROOT_BYTES
264 {
265 return Err(CoreError::invalid(
266 "grammar",
267 format!(
268 "source must be at most {MAX_GRAMMAR_SOURCE_BYTES} bytes and root at most {MAX_GRAMMAR_ROOT_BYTES} bytes"
269 ),
270 ));
271 }
272 if self.source.contains('\0') || self.root.contains('\0') {
273 return Err(CoreError::invalid(
274 "grammar",
275 "source and root must not contain NUL bytes",
276 ));
277 }
278 Ok(())
279 }
280}
281
282#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
284#[serde(rename_all = "snake_case", tag = "kind")]
285pub enum GrammarActivationV2 {
286 Eager,
288 Lazy {
291 trigger_patterns: Vec<String>,
293 trigger_tokens: Vec<TokenId>,
295 },
296}
297
298#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
303#[serde(deny_unknown_fields)]
304pub struct GrammarPlanV2 {
305 pub grammar: Grammar,
307 pub activation: GrammarActivationV2,
309}
310
311impl GrammarPlanV2 {
312 pub fn validate(&self) -> Result<(), CoreError> {
320 self.grammar.validate()?;
321 let GrammarActivationV2::Lazy {
322 trigger_patterns,
323 trigger_tokens,
324 } = &self.activation
325 else {
326 return Ok(());
327 };
328 if trigger_patterns.is_empty() && trigger_tokens.is_empty() {
329 return Err(CoreError::invalid(
330 "lazy grammar",
331 "at least one trigger pattern or token is required",
332 ));
333 }
334 let trigger_bytes = trigger_patterns
335 .iter()
336 .try_fold(0_usize, |total, pattern| {
337 total
338 .checked_add(pattern.len())
339 .ok_or_else(|| CoreError::invalid("lazy grammar", "trigger bytes overflowed"))
340 })?;
341 if trigger_patterns.len() > MAX_LAZY_GRAMMAR_TRIGGER_PATTERNS
342 || trigger_patterns.iter().any(|pattern| {
343 pattern.is_empty()
344 || pattern.len() > MAX_LAZY_GRAMMAR_TRIGGER_PATTERN_BYTES
345 || pattern.contains('\0')
346 })
347 || trigger_bytes > MAX_LAZY_GRAMMAR_TRIGGER_BYTES
348 || trigger_tokens.len() > MAX_LAZY_GRAMMAR_TRIGGER_TOKENS
349 {
350 return Err(CoreError::invalid(
351 "lazy grammar",
352 format!(
353 "requires at most {MAX_LAZY_GRAMMAR_TRIGGER_PATTERNS} non-empty NUL-free patterns of at most {MAX_LAZY_GRAMMAR_TRIGGER_PATTERN_BYTES} bytes, {MAX_LAZY_GRAMMAR_TRIGGER_BYTES} aggregate pattern bytes, and {MAX_LAZY_GRAMMAR_TRIGGER_TOKENS} trigger tokens"
354 ),
355 ));
356 }
357 if trigger_patterns.iter().collect::<HashSet<_>>().len() != trigger_patterns.len()
358 || trigger_tokens.iter().collect::<HashSet<_>>().len() != trigger_tokens.len()
359 {
360 return Err(CoreError::invalid(
361 "lazy grammar",
362 "trigger patterns and token identifiers must each be unique",
363 ));
364 }
365 Ok(())
366 }
367
368 pub fn digest(&self) -> Result<Digest, CoreError> {
374 self.validate()?;
375 Digest::of_serializable("grammar-plan-v2", self)
376 }
377}
378
379#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
381pub struct GenerationPlan {
382 pub sampling: SamplingPlan,
384 pub max_tokens: u32,
386 #[serde(default)]
389 pub biases: Vec<LogitBias>,
390 #[serde(default, skip_serializing_if = "Option::is_none")]
392 pub grammar: Option<Grammar>,
393 #[serde(default)]
398 pub stops: Vec<Vec<u8>>,
399}
400
401impl GenerationPlan {
402 pub fn validate(&self) -> Result<(), CoreError> {
408 self.sampling.validate()?;
409 if self.max_tokens == 0 {
410 return Err(CoreError::invalid(
411 "maximum tokens",
412 "must be greater than zero",
413 ));
414 }
415 if self.biases.len() > MAX_LOGIT_BIASES
416 || self.biases.iter().any(|bias| !bias.bias.is_finite())
417 {
418 return Err(CoreError::invalid(
419 "logit biases",
420 "too many biases or a non-finite value",
421 ));
422 }
423 if self
424 .biases
425 .iter()
426 .map(|bias| bias.token)
427 .collect::<HashSet<_>>()
428 .len()
429 != self.biases.len()
430 {
431 return Err(CoreError::invalid(
432 "logit biases",
433 "token identifiers must be unique",
434 ));
435 }
436 if let Some(grammar) = &self.grammar {
437 grammar.validate()?;
438 }
439 if self.stops.len() > MAX_STOP_SEQUENCES
440 || self
441 .stops
442 .iter()
443 .any(|stop| stop.is_empty() || stop.len() > MAX_STOP_SEQUENCE_BYTES)
444 {
445 return Err(CoreError::invalid(
446 "stop sequences",
447 format!(
448 "requires at most {MAX_STOP_SEQUENCES} non-empty sequences of at most {MAX_STOP_SEQUENCE_BYTES} bytes"
449 ),
450 ));
451 }
452 Ok(())
453 }
454
455 pub fn digest(&self) -> Result<Digest, CoreError> {
461 self.validate()?;
462 Digest::of_serializable("generation-plan-v1", self)
463 }
464}
465
466#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
472#[serde(deny_unknown_fields)]
473pub struct GenerationPlanV2 {
474 pub generation: GenerationPlan,
476 #[serde(default, skip_serializing_if = "Option::is_none")]
478 pub grammar: Option<GrammarPlanV2>,
479}
480
481impl GenerationPlanV2 {
482 pub fn validate(&self) -> Result<(), CoreError> {
489 self.generation.validate()?;
490 if self.generation.grammar.is_some() {
491 return Err(CoreError::invalid(
492 "generation plan v2",
493 "the embedded generation-plan-v1 grammar must be absent",
494 ));
495 }
496 if let Some(grammar) = &self.grammar {
497 grammar.validate()?;
498 }
499 Ok(())
500 }
501
502 pub fn digest(&self) -> Result<Digest, CoreError> {
508 self.validate()?;
509 Digest::of_serializable("generation-plan-v2", self)
510 }
511}
512
513#[cfg(test)]
514mod tests {
515 use super::*;
516
517 fn plan() -> GenerationPlan {
518 GenerationPlan {
519 sampling: SamplingPlan::default(),
520 max_tokens: 8,
521 biases: Vec::new(),
522 grammar: None,
523 stops: vec![b"stop".to_vec()],
524 }
525 }
526
527 #[test]
528 fn generation_plan_roundtrip_preserves_identity() {
529 let original = plan();
530 let encoded = serde_json::to_vec(&original).unwrap();
531 let decoded: GenerationPlan = serde_json::from_slice(&encoded).unwrap();
532 assert_eq!(original.digest().unwrap(), decoded.digest().unwrap());
533 }
534
535 #[test]
536 fn generation_plan_rejects_unbounded_or_nonfinite_mechanics() {
537 let mut invalid = plan();
538 invalid.max_tokens = 0;
539 assert!(invalid.validate().is_err());
540 invalid.max_tokens = 1;
541 invalid.sampling.temperature = f32::NAN;
542 assert!(invalid.validate().is_err());
543 invalid.sampling.temperature = 0.0;
544 invalid.stops = vec![Vec::new()];
545 assert!(invalid.validate().is_err());
546 }
547
548 #[test]
549 fn stateful_sampler_bounds_are_explicit() {
550 let mut sampling = SamplingPlan {
551 temperature: 0.8,
552 dry: Some(DrySampler {
553 multiplier: 0.8,
554 base: 1.75,
555 allowed_length: 2,
556 penalty_last_n: -1,
557 sequence_breakers: vec!["\n".to_owned()],
558 }),
559 mirostat: Some(MirostatSampler {
560 version: MirostatVersion::V2,
561 tau: 5.0,
562 eta: 0.1,
563 m: 0,
564 }),
565 ..SamplingPlan::default()
566 };
567 assert!(sampling.validate().is_ok());
568
569 sampling.dry.as_mut().unwrap().sequence_breakers = vec![String::new()];
570 assert!(sampling.validate().is_err());
571 sampling.dry.as_mut().unwrap().sequence_breakers = vec!["\n".to_owned()];
572 sampling.dry.as_mut().unwrap().base = f32::NAN;
573 assert!(matches!(
574 sampling.validate(),
575 Err(CoreError::NonFinite { field: "DRY base" })
576 ));
577
578 sampling.dry = None;
579 sampling.temperature = 0.0;
580 assert!(sampling.validate().is_err());
581
582 sampling.temperature = 0.8;
583 sampling.mirostat.as_mut().unwrap().m = 1;
584 assert!(sampling.validate().is_err());
585 sampling.mirostat = Some(MirostatSampler {
586 version: MirostatVersion::V1,
587 tau: 5.0,
588 eta: 0.1,
589 m: 0,
590 });
591 assert!(sampling.validate().is_err());
592 }
593
594 #[test]
595 fn grammar_and_stop_inputs_have_explicit_byte_bounds() {
596 let oversized_source = Grammar {
597 source: "x".repeat(MAX_GRAMMAR_SOURCE_BYTES + 1),
598 root: "root".to_owned(),
599 };
600 assert!(oversized_source.validate().is_err());
601
602 let oversized_root = Grammar {
603 source: "root ::= \"x\"".to_owned(),
604 root: "x".repeat(MAX_GRAMMAR_ROOT_BYTES + 1),
605 };
606 assert!(oversized_root.validate().is_err());
607
608 let mut invalid = plan();
609 invalid.stops = vec![vec![b'x'; MAX_STOP_SEQUENCE_BYTES + 1]];
610 assert!(invalid.validate().is_err());
611 invalid.stops = vec![vec![b'x']; MAX_STOP_SEQUENCES + 1];
612 assert!(invalid.validate().is_err());
613 }
614
615 #[test]
616 fn every_logit_bias_must_be_finite() {
617 let mut invalid = plan();
618 invalid.biases.push(LogitBias {
619 token: TokenId::new(7).unwrap(),
620 bias: f32::INFINITY,
621 });
622 assert!(invalid.validate().is_err());
623 }
624
625 #[test]
626 fn generation_logit_bias_tokens_must_be_unique() {
627 let mut invalid = plan();
628 invalid.biases = vec![
629 LogitBias {
630 token: TokenId::new(7).unwrap(),
631 bias: 1.0,
632 },
633 LogitBias {
634 token: TokenId::new(7).unwrap(),
635 bias: 2.0,
636 },
637 ];
638 assert!(invalid.validate().is_err());
639 }
640
641 #[test]
642 fn version_two_generation_preserves_v1_and_binds_lazy_triggers() {
643 let grammar = GrammarPlanV2 {
644 grammar: Grammar {
645 source: "root ::= \"{}\"".to_owned(),
646 root: "root".to_owned(),
647 },
648 activation: GrammarActivationV2::Lazy {
649 trigger_patterns: vec!["<tool>.*".to_owned()],
650 trigger_tokens: vec![TokenId::new(7).unwrap()],
651 },
652 };
653 let version_two = GenerationPlanV2 {
654 generation: plan(),
655 grammar: Some(grammar.clone()),
656 };
657 assert!(version_two.validate().is_ok());
658 assert_ne!(
659 version_two.digest().unwrap(),
660 version_two.generation.digest().unwrap()
661 );
662
663 let mut duplicate = version_two.clone();
664 duplicate.grammar.as_mut().unwrap().activation = GrammarActivationV2::Lazy {
665 trigger_patterns: vec!["x".to_owned(), "x".to_owned()],
666 trigger_tokens: Vec::new(),
667 };
668 assert!(duplicate.validate().is_err());
669
670 let mut ambiguous = version_two;
671 ambiguous.generation.grammar = Some(grammar.grammar);
672 assert!(ambiguous.validate().is_err());
673 }
674}