use std::collections::HashSet;
use serde::{Deserialize, Serialize};
use crate::{CoreError, Digest, TokenId};
pub const MAX_DRY_SEQUENCE_BREAKERS: usize = 64;
pub const MAX_DRY_SEQUENCE_BREAKER_BYTES: usize = 40;
pub const MAX_LOGIT_BIASES: usize = 65_536;
pub const MAX_GRAMMAR_SOURCE_BYTES: usize = 1024 * 1024;
pub const MAX_GRAMMAR_ROOT_BYTES: usize = 256;
pub const MAX_LAZY_GRAMMAR_TRIGGER_PATTERNS: usize = 64;
pub const MAX_LAZY_GRAMMAR_TRIGGER_PATTERN_BYTES: usize = 4_096;
pub const MAX_LAZY_GRAMMAR_TRIGGER_BYTES: usize = 64 * 1_024;
pub const MAX_LAZY_GRAMMAR_TRIGGER_TOKENS: usize = 4_096;
pub const MAX_STOP_SEQUENCES: usize = 64;
pub const MAX_STOP_SEQUENCE_BYTES: usize = 4_096;
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct RepetitionSampler {
pub last_n: i32,
pub repeat_penalty: f32,
pub frequency_penalty: f32,
pub presence_penalty: f32,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct DrySampler {
pub multiplier: f32,
pub base: f32,
pub allowed_length: i32,
pub penalty_last_n: i32,
pub sequence_breakers: Vec<String>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MirostatVersion {
V1,
V2,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct MirostatSampler {
pub version: MirostatVersion,
pub tau: f32,
pub eta: f32,
pub m: i32,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct SamplingPlan {
pub seed: u32,
pub temperature: f32,
pub top_k: i32,
pub top_p: f32,
pub min_p: f32,
pub typical_p: f32,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub repetition: Option<RepetitionSampler>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub dry: Option<DrySampler>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub mirostat: Option<MirostatSampler>,
}
impl Default for SamplingPlan {
fn default() -> Self {
Self {
seed: 0,
temperature: 0.0,
top_k: 40,
top_p: 0.95,
min_p: 0.05,
typical_p: 1.0,
repetition: None,
dry: None,
mirostat: None,
}
}
}
impl SamplingPlan {
pub fn validate(&self) -> Result<(), CoreError> {
for (field, value) in [
("temperature", self.temperature),
("top p", self.top_p),
("min p", self.min_p),
("typical p", self.typical_p),
] {
if !value.is_finite() {
return Err(CoreError::NonFinite { field });
}
}
if self.temperature < 0.0
|| self.top_k < 0
|| !(0.0..=1.0).contains(&self.top_p)
|| !(0.0..=1.0).contains(&self.min_p)
|| !(0.0..=1.0).contains(&self.typical_p)
{
return Err(CoreError::invalid(
"sampling plan",
"temperature/top-k must be non-negative and probabilities must be in 0..=1",
));
}
if let Some(repetition) = &self.repetition {
for (field, value) in [
("repeat penalty", repetition.repeat_penalty),
("frequency penalty", repetition.frequency_penalty),
("presence penalty", repetition.presence_penalty),
] {
if !value.is_finite() {
return Err(CoreError::NonFinite { field });
}
}
if repetition.last_n < -1 || repetition.repeat_penalty <= 0.0 {
return Err(CoreError::invalid(
"repetition sampler",
"last_n must be at least -1 and repeat_penalty must be positive",
));
}
}
if let Some(dry) = &self.dry {
for (field, value) in [("DRY multiplier", dry.multiplier), ("DRY base", dry.base)] {
if !value.is_finite() {
return Err(CoreError::NonFinite { field });
}
}
if dry.multiplier <= 0.0
|| dry.base < 1.0
|| dry.allowed_length < 0
|| dry.penalty_last_n < -1
|| dry.penalty_last_n == 0
{
return Err(CoreError::invalid(
"dry sampler",
"multiplier must be positive, base at least one, allowed length non-negative, and lookback -1 or positive",
));
}
if dry.sequence_breakers.len() > MAX_DRY_SEQUENCE_BREAKERS
|| dry.sequence_breakers.iter().any(|value| {
value.is_empty()
|| value.len() > MAX_DRY_SEQUENCE_BREAKER_BYTES
|| value.contains('\0')
})
{
return Err(CoreError::invalid(
"dry sequence breakers",
format!(
"requires at most {MAX_DRY_SEQUENCE_BREAKERS} non-empty, NUL-free values of at most {MAX_DRY_SEQUENCE_BREAKER_BYTES} bytes"
),
));
}
}
if let Some(mirostat) = &self.mirostat {
for (field, value) in [
("Mirostat tau", mirostat.tau),
("Mirostat eta", mirostat.eta),
] {
if !value.is_finite() {
return Err(CoreError::NonFinite { field });
}
}
let invalid_window = match mirostat.version {
MirostatVersion::V1 => mirostat.m <= 0,
MirostatVersion::V2 => mirostat.m != 0,
};
if self.temperature <= 0.0
|| mirostat.tau <= 0.0
|| mirostat.eta <= 0.0
|| invalid_window
{
return Err(CoreError::invalid(
"mirostat sampler",
"temperature, tau, and eta must be positive; m must be positive for v1 and zero for v2",
));
}
}
Ok(())
}
}
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct LogitBias {
pub token: TokenId,
pub bias: f32,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Grammar {
pub source: String,
pub root: String,
}
impl Grammar {
pub fn validate(&self) -> Result<(), CoreError> {
if self.source.is_empty() || self.root.is_empty() {
return Err(CoreError::Empty {
field: "grammar source/root",
});
}
if self.source.len() > MAX_GRAMMAR_SOURCE_BYTES || self.root.len() > MAX_GRAMMAR_ROOT_BYTES
{
return Err(CoreError::invalid(
"grammar",
format!(
"source must be at most {MAX_GRAMMAR_SOURCE_BYTES} bytes and root at most {MAX_GRAMMAR_ROOT_BYTES} bytes"
),
));
}
if self.source.contains('\0') || self.root.contains('\0') {
return Err(CoreError::invalid(
"grammar",
"source and root must not contain NUL bytes",
));
}
Ok(())
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case", tag = "kind")]
pub enum GrammarActivationV2 {
Eager,
Lazy {
trigger_patterns: Vec<String>,
trigger_tokens: Vec<TokenId>,
},
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GrammarPlanV2 {
pub grammar: Grammar,
pub activation: GrammarActivationV2,
}
impl GrammarPlanV2 {
pub fn validate(&self) -> Result<(), CoreError> {
self.grammar.validate()?;
let GrammarActivationV2::Lazy {
trigger_patterns,
trigger_tokens,
} = &self.activation
else {
return Ok(());
};
if trigger_patterns.is_empty() && trigger_tokens.is_empty() {
return Err(CoreError::invalid(
"lazy grammar",
"at least one trigger pattern or token is required",
));
}
let trigger_bytes = trigger_patterns
.iter()
.try_fold(0_usize, |total, pattern| {
total
.checked_add(pattern.len())
.ok_or_else(|| CoreError::invalid("lazy grammar", "trigger bytes overflowed"))
})?;
if trigger_patterns.len() > MAX_LAZY_GRAMMAR_TRIGGER_PATTERNS
|| trigger_patterns.iter().any(|pattern| {
pattern.is_empty()
|| pattern.len() > MAX_LAZY_GRAMMAR_TRIGGER_PATTERN_BYTES
|| pattern.contains('\0')
})
|| trigger_bytes > MAX_LAZY_GRAMMAR_TRIGGER_BYTES
|| trigger_tokens.len() > MAX_LAZY_GRAMMAR_TRIGGER_TOKENS
{
return Err(CoreError::invalid(
"lazy grammar",
format!(
"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"
),
));
}
if trigger_patterns.iter().collect::<HashSet<_>>().len() != trigger_patterns.len()
|| trigger_tokens.iter().collect::<HashSet<_>>().len() != trigger_tokens.len()
{
return Err(CoreError::invalid(
"lazy grammar",
"trigger patterns and token identifiers must each be unique",
));
}
Ok(())
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("grammar-plan-v2", self)
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct GenerationPlan {
pub sampling: SamplingPlan,
pub max_tokens: u32,
#[serde(default)]
pub biases: Vec<LogitBias>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub grammar: Option<Grammar>,
#[serde(default)]
pub stops: Vec<Vec<u8>>,
}
impl GenerationPlan {
pub fn validate(&self) -> Result<(), CoreError> {
self.sampling.validate()?;
if self.max_tokens == 0 {
return Err(CoreError::invalid(
"maximum tokens",
"must be greater than zero",
));
}
if self.biases.len() > MAX_LOGIT_BIASES
|| self.biases.iter().any(|bias| !bias.bias.is_finite())
{
return Err(CoreError::invalid(
"logit biases",
"too many biases or a non-finite value",
));
}
if self
.biases
.iter()
.map(|bias| bias.token)
.collect::<HashSet<_>>()
.len()
!= self.biases.len()
{
return Err(CoreError::invalid(
"logit biases",
"token identifiers must be unique",
));
}
if let Some(grammar) = &self.grammar {
grammar.validate()?;
}
if self.stops.len() > MAX_STOP_SEQUENCES
|| self
.stops
.iter()
.any(|stop| stop.is_empty() || stop.len() > MAX_STOP_SEQUENCE_BYTES)
{
return Err(CoreError::invalid(
"stop sequences",
format!(
"requires at most {MAX_STOP_SEQUENCES} non-empty sequences of at most {MAX_STOP_SEQUENCE_BYTES} bytes"
),
));
}
Ok(())
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("generation-plan-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GenerationPlanV2 {
pub generation: GenerationPlan,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub grammar: Option<GrammarPlanV2>,
}
impl GenerationPlanV2 {
pub fn validate(&self) -> Result<(), CoreError> {
self.generation.validate()?;
if self.generation.grammar.is_some() {
return Err(CoreError::invalid(
"generation plan v2",
"the embedded generation-plan-v1 grammar must be absent",
));
}
if let Some(grammar) = &self.grammar {
grammar.validate()?;
}
Ok(())
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("generation-plan-v2", self)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn plan() -> GenerationPlan {
GenerationPlan {
sampling: SamplingPlan::default(),
max_tokens: 8,
biases: Vec::new(),
grammar: None,
stops: vec![b"stop".to_vec()],
}
}
#[test]
fn generation_plan_roundtrip_preserves_identity() {
let original = plan();
let encoded = serde_json::to_vec(&original).unwrap();
let decoded: GenerationPlan = serde_json::from_slice(&encoded).unwrap();
assert_eq!(original.digest().unwrap(), decoded.digest().unwrap());
}
#[test]
fn generation_plan_rejects_unbounded_or_nonfinite_mechanics() {
let mut invalid = plan();
invalid.max_tokens = 0;
assert!(invalid.validate().is_err());
invalid.max_tokens = 1;
invalid.sampling.temperature = f32::NAN;
assert!(invalid.validate().is_err());
invalid.sampling.temperature = 0.0;
invalid.stops = vec![Vec::new()];
assert!(invalid.validate().is_err());
}
#[test]
fn stateful_sampler_bounds_are_explicit() {
let mut sampling = SamplingPlan {
temperature: 0.8,
dry: Some(DrySampler {
multiplier: 0.8,
base: 1.75,
allowed_length: 2,
penalty_last_n: -1,
sequence_breakers: vec!["\n".to_owned()],
}),
mirostat: Some(MirostatSampler {
version: MirostatVersion::V2,
tau: 5.0,
eta: 0.1,
m: 0,
}),
..SamplingPlan::default()
};
assert!(sampling.validate().is_ok());
sampling.dry.as_mut().unwrap().sequence_breakers = vec![String::new()];
assert!(sampling.validate().is_err());
sampling.dry.as_mut().unwrap().sequence_breakers = vec!["\n".to_owned()];
sampling.dry.as_mut().unwrap().base = f32::NAN;
assert!(matches!(
sampling.validate(),
Err(CoreError::NonFinite { field: "DRY base" })
));
sampling.dry = None;
sampling.temperature = 0.0;
assert!(sampling.validate().is_err());
sampling.temperature = 0.8;
sampling.mirostat.as_mut().unwrap().m = 1;
assert!(sampling.validate().is_err());
sampling.mirostat = Some(MirostatSampler {
version: MirostatVersion::V1,
tau: 5.0,
eta: 0.1,
m: 0,
});
assert!(sampling.validate().is_err());
}
#[test]
fn grammar_and_stop_inputs_have_explicit_byte_bounds() {
let oversized_source = Grammar {
source: "x".repeat(MAX_GRAMMAR_SOURCE_BYTES + 1),
root: "root".to_owned(),
};
assert!(oversized_source.validate().is_err());
let oversized_root = Grammar {
source: "root ::= \"x\"".to_owned(),
root: "x".repeat(MAX_GRAMMAR_ROOT_BYTES + 1),
};
assert!(oversized_root.validate().is_err());
let mut invalid = plan();
invalid.stops = vec![vec![b'x'; MAX_STOP_SEQUENCE_BYTES + 1]];
assert!(invalid.validate().is_err());
invalid.stops = vec![vec![b'x']; MAX_STOP_SEQUENCES + 1];
assert!(invalid.validate().is_err());
}
#[test]
fn every_logit_bias_must_be_finite() {
let mut invalid = plan();
invalid.biases.push(LogitBias {
token: TokenId::new(7).unwrap(),
bias: f32::INFINITY,
});
assert!(invalid.validate().is_err());
}
#[test]
fn generation_logit_bias_tokens_must_be_unique() {
let mut invalid = plan();
invalid.biases = vec![
LogitBias {
token: TokenId::new(7).unwrap(),
bias: 1.0,
},
LogitBias {
token: TokenId::new(7).unwrap(),
bias: 2.0,
},
];
assert!(invalid.validate().is_err());
}
#[test]
fn version_two_generation_preserves_v1_and_binds_lazy_triggers() {
let grammar = GrammarPlanV2 {
grammar: Grammar {
source: "root ::= \"{}\"".to_owned(),
root: "root".to_owned(),
},
activation: GrammarActivationV2::Lazy {
trigger_patterns: vec!["<tool>.*".to_owned()],
trigger_tokens: vec![TokenId::new(7).unwrap()],
},
};
let version_two = GenerationPlanV2 {
generation: plan(),
grammar: Some(grammar.clone()),
};
assert!(version_two.validate().is_ok());
assert_ne!(
version_two.digest().unwrap(),
version_two.generation.digest().unwrap()
);
let mut duplicate = version_two.clone();
duplicate.grammar.as_mut().unwrap().activation = GrammarActivationV2::Lazy {
trigger_patterns: vec!["x".to_owned(), "x".to_owned()],
trigger_tokens: Vec::new(),
};
assert!(duplicate.validate().is_err());
let mut ambiguous = version_two;
ambiguous.generation.grammar = Some(grammar.grammar);
assert!(ambiguous.validate().is_err());
}
}