use std::collections::BTreeMap;
use logit_loom::{
CandidateMode, CoreError, Digest, LogitTransform, MAX_LOGIT_BIASES, MAX_PIPELINE_STAGES,
Pipeline, RankBias, Stage, TokenBias, TokenId, TransformSpec,
};
use serde::Serialize;
use crate::{Error, Result};
const RANK_BIAS_IDENTITY_DOMAIN: &str = "runtime-rank-bias-v1";
const TOKEN_BIAS_IDENTITY_DOMAIN: &str = "runtime-token-bias-v1";
#[derive(Serialize)]
struct RankBiasIdentity {
rank: u64,
bias_bits: u32,
}
#[derive(Serialize)]
struct TokenBiasIdentity {
biases: Vec<(i32, u32)>,
}
pub struct PipelineBuilder {
mode: CandidateMode,
max_steps: u32,
stages: Vec<Stage>,
}
impl PipelineBuilder {
pub fn new(mode: CandidateMode, max_steps: u32) -> Result<Self> {
mode.validate()?;
if max_steps == 0 {
return Err(
CoreError::invalid("pipeline maximum steps", "must be greater than zero").into(),
);
}
Ok(Self {
mode,
max_steps,
stages: Vec::new(),
})
}
pub const fn mode(&self) -> CandidateMode {
self.mode
}
pub const fn max_steps(&self) -> u32 {
self.max_steps
}
pub fn stage_count(&self) -> usize {
self.stages.len()
}
pub fn rank_bias(mut self, rank: usize, bias: f32) -> Result<Self> {
self.ensure_stage_capacity()?;
let transform = RankBias::new(rank, bias)?;
let rank = u64::try_from(rank).map_err(|_| {
Error::from(CoreError::invalid(
"rank bias",
"rank exceeds the portable u64 identity representation",
))
})?;
let identity = Digest::of_serializable(
RANK_BIAS_IDENTITY_DOMAIN,
&RankBiasIdentity {
rank,
bias_bits: bias.to_bits(),
},
)?;
self.push_stage(identity, transform)?;
Ok(self)
}
pub fn token_bias(mut self, biases: impl IntoIterator<Item = (TokenId, f32)>) -> Result<Self> {
self.ensure_stage_capacity()?;
let entries = biases
.into_iter()
.take(MAX_LOGIT_BIASES + 1)
.collect::<Vec<_>>();
if entries.len() > MAX_LOGIT_BIASES {
return Err(CoreError::invalid(
"token bias input",
format!("requires at most {MAX_LOGIT_BIASES} entries"),
)
.into());
}
let transform = TokenBias::new(entries.iter().copied())?;
let mut normalized = BTreeMap::new();
for (token, bias) in entries {
normalized.insert(token, bias.to_bits());
}
let identity = Digest::of_serializable(
TOKEN_BIAS_IDENTITY_DOMAIN,
&TokenBiasIdentity {
biases: normalized
.into_iter()
.map(|(token, bits)| (token.get(), bits))
.collect(),
},
)?;
self.push_stage(identity, transform)?;
Ok(self)
}
pub fn stage(
mut self,
implementation: Digest,
transform: impl LogitTransform + 'static,
) -> Result<Self> {
self.ensure_stage_capacity()?;
self.push_stage(implementation, transform)?;
Ok(self)
}
pub fn build(self) -> Result<Pipeline> {
Pipeline::new(self.stages).map_err(Error::from)
}
fn push_stage(
&mut self,
implementation: Digest,
transform: impl LogitTransform + 'static,
) -> Result<()> {
self.ensure_stage_capacity()?;
let specification = TransformSpec::new(implementation, self.mode, self.max_steps)?;
self.stages.push(Stage::new(specification, transform)?);
Ok(())
}
fn ensure_stage_capacity(&self) -> Result<()> {
if self.stages.len() >= MAX_PIPELINE_STAGES {
return Err(CoreError::invalid(
"pipeline stages",
format!("requires at most {MAX_PIPELINE_STAGES} stages"),
)
.into());
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn built_in_rank_identity_is_deterministic_and_configuration_bound() {
let first = PipelineBuilder::new(CandidateMode::FullVocabulary, 2)
.unwrap()
.rank_bias(1, 2.0)
.unwrap()
.build()
.unwrap();
let same = PipelineBuilder::new(CandidateMode::FullVocabulary, 2)
.unwrap()
.rank_bias(1, 2.0)
.unwrap()
.build()
.unwrap();
let different = PipelineBuilder::new(CandidateMode::FullVocabulary, 2)
.unwrap()
.rank_bias(0, 2.0)
.unwrap()
.build()
.unwrap();
assert_eq!(
first.specification().stages[0].implementation,
same.specification().stages[0].implementation
);
assert_ne!(
first.specification().stages[0].implementation,
different.specification().stages[0].implementation
);
}
#[test]
fn token_bias_identity_normalizes_duplicate_inputs() {
let token = TokenId::new(7).unwrap();
let duplicate = PipelineBuilder::new(CandidateMode::FullVocabulary, 1)
.unwrap()
.token_bias([(token, 1.0), (token, 2.0)])
.unwrap()
.build()
.unwrap();
let normalized = PipelineBuilder::new(CandidateMode::FullVocabulary, 1)
.unwrap()
.token_bias([(token, 2.0)])
.unwrap()
.build()
.unwrap();
assert_eq!(
duplicate.specification().stages[0].implementation,
normalized.specification().stages[0].implementation
);
}
#[test]
fn rank_bias_pipeline_runs_against_an_in_memory_vocabulary() {
let mut pipeline = PipelineBuilder::new(CandidateMode::FullVocabulary, 1)
.unwrap()
.rank_bias(1, 4.0)
.unwrap()
.build()
.unwrap();
pipeline.begin(&[]).unwrap();
let mut logits = [3.0, 2.0, 1.0];
pipeline.apply_to_vocabulary(0, &[], &mut logits).unwrap();
assert_eq!(
logits.map(f32::to_bits),
[3.0_f32.to_bits(), 6.0_f32.to_bits(), 1.0_f32.to_bits()]
);
}
#[test]
fn empty_and_zero_bound_builders_are_rejected() {
assert!(PipelineBuilder::new(CandidateMode::FullVocabulary, 0).is_err());
assert!(
PipelineBuilder::new(CandidateMode::FullVocabulary, 1)
.unwrap()
.build()
.is_err()
);
}
#[test]
fn stage_bound_is_enforced_by_the_builder() {
let mut builder = PipelineBuilder::new(CandidateMode::FullVocabulary, 1).unwrap();
for rank in 0..MAX_PIPELINE_STAGES {
builder = builder.rank_bias(rank, 1.0).unwrap();
}
assert_eq!(builder.stage_count(), MAX_PIPELINE_STAGES);
assert!(builder.rank_bias(MAX_PIPELINE_STAGES, 1.0).is_err());
}
}