Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
//! The window plan behind `LayaEngine::predict_long`: how wide the scan windows are, where they
//! start, how many go through one forward pass, and how the per-window answers collapse into one.
//! Ports `window_budget`, `window_batch_cap` and `state_room` from `laya/common.py` and the
//! aggregation in `ONNXAgent.predict_long` (`laya/onnx_agent.py`), `aggregate="auto"` only.
//!
//! Everything here is pure arithmetic over token counts and finished results, so it is testable
//! without a model. The engine supplies the tokenizer-dependent inputs (the per-question state
//! room and the state's token ids) and runs the windows.
//!
//! Python also emits `warnings.warn` when it caps the window or reduces the stride. Those warnings
//! are ported with Python's exact text and sent through the `log` facade at `warn` level, target
//! `laya`; install any `log` backend (for example `env_logger`) to see them.
use crate::answers::{Answer, LayaResult, OptionUsage, ScanUsage, StateUsage, Usage, WindowInfo};
use crate::error::{LayaError, Result};
use crate::questions::{QuestionSet, QuestionType};
use crate::sequence_builder::SequenceBuilder;
use crate::tokenization::LayaTokenizer;
use indexmap::IndexMap;
use std::collections::HashMap;
/// Options for `LayaEngine::predict_long`. Every field is optional; `Default` gives Python's
/// defaults. Build one with the chained setters.
///
/// Per-call hooks and the confidence gate that Python's `predict_long` also accepts are not part
/// of this port. It takes no `max_len` or `head_max_len`, as in Python.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct LongOptions {
/// State tokens per window. `None` or `0` uses the checkpoint default,
/// `max(64, max_len - head_max_len - 8)`. Capped at the smallest state room the questions
/// leave.
pub window: Option<usize>,
/// Token step between windows. `None` or `0` uses half the effective window. A step past the
/// requested window is an error; a valid step past a window the questions' room clamped is
/// reduced.
pub stride: Option<usize>,
/// Only `"auto"` (the default when `None`) is supported.
pub aggregate: Option<String>,
/// Maximum windows per forward pass. `None` or `0` uses Python's automatic cap.
pub batch_size: Option<usize>,
/// Selects an entry of [`crate::LayaOptions::lang_temperatures`] for every window; see
/// [`crate::PredictOptions::lang`]. On `LayaRouter::predict_long` the explicit `lang`
/// argument plays this part, falling back to the detected language, and this field is not
/// read.
pub lang: Option<String>,
}
impl LongOptions {
/// Python's defaults: checkpoint window, half-window stride, `"auto"`, automatic batch cap.
pub fn new() -> Self {
Self::default()
}
/// Set [`Self::window`].
pub fn window(mut self, window: usize) -> Self {
self.window = Some(window);
self
}
/// Set [`Self::stride`].
pub fn stride(mut self, stride: usize) -> Self {
self.stride = Some(stride);
self
}
/// Set [`Self::aggregate`]. Anything but `"auto"` makes `predict_long` return
/// [`LayaError::UnsupportedAggregate`].
pub fn aggregate(mut self, aggregate: impl Into<String>) -> Self {
self.aggregate = Some(aggregate.into());
self
}
/// Set [`Self::batch_size`].
pub fn batch_size(mut self, batch_size: usize) -> Self {
self.batch_size = Some(batch_size);
self
}
/// Set [`Self::lang`].
pub fn lang(mut self, lang: impl Into<String>) -> Self {
self.lang = Some(lang.into());
self
}
pub(crate) fn check_aggregate(&self) -> Result<()> {
match self.aggregate.as_deref() {
None | Some("auto") => Ok(()),
Some(other) => Err(LayaError::UnsupportedAggregate(other.to_string())),
}
}
}
/// The resolved scan geometry, plus the room that decides the one-pass shortcut.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WindowBudget {
/// Tokens per window, after clamping to `room`.
pub window: usize,
/// Tokens between window starts.
pub stride: usize,
/// The smallest state room any question leaves.
pub room: usize,
}
/// The checkpoint's default window: `max(64, max_len - head_max_len - 8)`, the 64 being a floor.
pub(crate) fn default_window(max_len: usize, head_max_len: usize) -> usize {
max_len
.saturating_sub(head_max_len)
.saturating_sub(8)
.max(64)
}
/// `window_budget` with the per-question rooms already measured. An empty `rooms` (no questions)
/// leaves the requested window as the room. The `RuntimeWarning`s Python raises are dropped.
#[cfg(test)]
pub(crate) fn plan_budget(
rooms: &[usize],
max_len: usize,
head_max_len: usize,
window: usize,
stride: usize,
) -> Result<WindowBudget> {
plan_budget_warned(rooms, max_len, head_max_len, window, stride).map(|(budget, _)| budget)
}
/// [`plan_budget`], also returning the text of every `warnings.warn` Python's `window_budget`
/// would emit for the same call, in order, exactly as Python words it.
pub(crate) fn plan_budget_warned(
rooms: &[usize],
max_len: usize,
head_max_len: usize,
window: usize,
stride: usize,
) -> Result<(WindowBudget, Vec<String>)> {
let mut warnings = Vec::new();
let requested = if window > 0 {
window
} else {
default_window(max_len, head_max_len)
};
let room = rooms.iter().copied().min().unwrap_or(requested);
if room == 0 {
return Err(LayaError::InvalidWindow(format!(
"predict_long: the questions' options fill the whole sequence (max_len={max_len}, \
head_max_len={head_max_len}), leaving no room for the state; no window can carry any \
of it. A label set this large is what laya.shortlist.predict_shortlist is for"
)));
}
let size = requested.min(room);
if requested > room {
if window > 0 {
warnings.push(format!(
"laya: predict_long: window={requested} is wider than the {room} state tokens \
these questions leave inside max_len={max_len}, so every window would be \
truncated to {room} on the way to the model; scanning with window={room} instead"
));
} else if requested >= room.saturating_mul(WINDOW_CLAMP_WARN_RATIO) {
warnings.push(format!(
"laya: predict_long: these questions leave only {room} of max_len={max_len} for \
the state (their heads take the rest), so the scan window is capped {requested} \
-> {room} and roughly {:.1}x as many windows -- each a full forward pass -- are \
needed to read the document. Fewer or shorter options, a larger max_len, or \
laya.shortlist.predict_shortlist for a large label set will all cost less than \
scanning at this width",
requested as f64 / room as f64
));
}
}
let mut step = if stride > 0 {
stride
} else {
(size / 2).max(1)
};
if step > size {
if size < requested && stride <= requested {
let reduced = (size / 2).max(1);
warnings.push(format!(
"laya: predict_long: stride={step} was a 50% step for the window={requested} you \
asked for, but the window was reduced to {size} to fit the room these questions \
leave; scanning with stride={reduced} instead"
));
step = reduced;
} else {
return Err(LayaError::InvalidWindow(format!(
"predict_long: stride={step} steps past the {size}-token window{}, so {} tokens \
between every pair of windows would be read by no window at all; pass stride <= \
{size}",
if size < requested {
" these questions leave room for"
} else {
""
},
step - size
)));
}
}
Ok((
WindowBudget {
window: size,
stride: step,
room,
},
warnings,
))
}
/// Python's `_WINDOW_CLAMP_WARN_RATIO`: a default window cut to half its size or less is warned.
const WINDOW_CLAMP_WARN_RATIO: usize = 2;
/// Sends each warning to the `log` facade (`warn`, target `laya`).
///
/// Python's default warnings filter shows an identical warning once per location, so a text that
/// has already been emitted in this process is not emitted again.
///
/// Python keys that on the message text and the file and line of the frame the warning is
/// attributed to (`stacklevel`): the caller's line, not the library's. `at` is that place, taken
/// from `#[track_caller]` on the public entry points. A call made through the router comes from
/// the router's own fixed line, as it does in Python.
pub(crate) fn emit_warnings(warnings: &[String], at: &std::panic::Location<'_>) {
type Shown = std::collections::HashSet<(String, String, u32)>;
static SHOWN: std::sync::Mutex<Option<Shown>> = std::sync::Mutex::new(None);
for message in warnings {
let first = SHOWN
.lock()
.unwrap_or_else(|e| e.into_inner())
.get_or_insert_with(Default::default)
.insert((message.clone(), at.file().to_string(), at.line()));
if first {
log::warn!(target: "laya", "{message}");
}
}
}
/// `window_budget`: measures each question's state room, then plans.
///
/// Public only so the parity tests, a separate crate, can compare the effective window, stride and
/// room with Python's; hidden from the docs like `LayaOutput`.
#[doc(hidden)]
pub fn window_budget(
tokenizer: &dyn LayaTokenizer,
questions: &QuestionSet,
max_len: usize,
head_max_len: usize,
window: usize,
stride: usize,
) -> Result<WindowBudget> {
window_budget_warned(tokenizer, questions, max_len, head_max_len, window, stride)
.map(|(budget, _)| budget)
}
/// [`window_budget`] for the engine: the budget plus Python's warnings, not yet emitted.
pub(crate) fn window_budget_warned(
tokenizer: &dyn LayaTokenizer,
questions: &QuestionSet,
max_len: usize,
head_max_len: usize,
window: usize,
stride: usize,
) -> Result<(WindowBudget, Vec<String>)> {
let mut rooms = Vec::with_capacity(questions.len());
for id in questions.ids() {
rooms.push(SequenceBuilder::state_room(
tokenizer,
&questions[id],
max_len,
head_max_len,
)?);
}
plan_budget_warned(&rooms, max_len, head_max_len, window, stride)
}
/// The overlapping windows over `tokens` state tokens. A window that reaches the end is the last.
pub(crate) fn spans(tokens: usize, window: usize, stride: usize) -> Vec<WindowInfo> {
let mut bounds = Vec::new();
let mut start = 0;
while start < tokens {
bounds.push((start, (start + window).min(tokens)));
if start + window >= tokens {
break;
}
start += stride;
}
let count = bounds.len();
bounds
.into_iter()
.enumerate()
.map(|(index, (token_start, token_end))| WindowInfo {
index,
token_start,
token_end,
count,
})
.collect()
}
/// `window_batch_cap`: windows per forward pass, or `None` for all of them in one pass.
pub(crate) fn batch_cap(
count: usize,
window: usize,
config_budget: usize,
batch_size: usize,
) -> Option<usize> {
if batch_size > 0 {
return Some(batch_size);
}
if window >= config_budget {
return None;
}
let step = (window / 2).max(1);
let config_step = (config_budget / 2).max(1);
let unclamped = (count * step).div_ceil(config_step).max(1);
// Capping that multiplies the window count by 2 or less keeps the shared pass.
(count > unclamped * 2).then_some(unclamped)
}
/// Collapse per-window results into one: for each question the window with the greatest evidence
/// (P(true) for noul, `answer_confidence` for choice and score) wins, the first window on ties.
pub(crate) fn aggregate(
model: &str,
questions: &QuestionSet,
results: &[LayaResult],
spans: &[WindowInfo],
) -> LayaResult {
let ids: Vec<String> = questions.ids().map(str::to_string).collect();
let mut answers: HashMap<String, Answer> = HashMap::with_capacity(ids.len());
for id in &ids {
let evidence = |index: usize| -> f64 {
let answer = &results[index][id.as_str()];
match (questions[id.as_str()].question_type(), answer.as_noul()) {
(QuestionType::Noul, Some(noul)) => noul.probability,
_ => answer.answer_confidence(),
}
};
let mut best = 0;
for index in 1..results.len() {
if evidence(index) > evidence(best) {
best = index;
}
}
answers.insert(
id.clone(),
results[best][id.as_str()].clone().with_window(spans[best]),
);
}
let usage = Usage {
input_tokens: results.iter().map(|r| r.usage().input_tokens).sum(),
output_tokens: 0,
};
let result = LayaResult::new(model, ids, answers, usage);
let diagnostics: Vec<&StateUsage> = results.iter().filter_map(|r| r.state_usage()).collect();
let truncated_windows = diagnostics.iter().filter(|u| u.truncated).count();
let scan = ScanUsage {
windows: results.len(),
truncated_windows,
};
if diagnostics.is_empty() {
return result.with_scan_usage(scan);
}
let mut options: IndexMap<String, OptionUsage> = IndexMap::new();
for usage in &diagnostics {
for (id, stats) in &usage.options {
options.insert(id.clone(), *stats);
}
}
result
.with_state_usage(StateUsage {
state_tokens: diagnostics.iter().map(|u| u.state_tokens).sum(),
state_tokens_dropped: diagnostics.iter().map(|u| u.state_tokens_dropped).sum(),
truncated: truncated_windows > 0,
// The last window's list, as in Python's scan aggregation.
truncated_questions: results
.last()
.and_then(|r| r.state_usage())
.map(|u| u.truncated_questions.clone())
.unwrap_or_default(),
options,
})
.with_scan_usage(scan)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::answers::{ActionInfo, ChoiceAnswer, NoulAnswer, ScoreAnswer};
use crate::questions::Question;
use serde_json::Value;
fn budget(rooms: &[usize], window: usize, stride: usize) -> Result<WindowBudget> {
plan_budget(rooms, 512, 192, window, stride)
}
fn message(result: Result<WindowBudget>) -> String {
result.unwrap_err().to_string()
}
#[test]
fn default_window_has_a_64_token_floor() {
assert_eq!(default_window(512, 192), 312);
assert_eq!(default_window(128, 120), 64);
assert_eq!(default_window(64, 192), 64);
}
#[test]
fn budget_defaults_to_the_checkpoint_window_and_half_stride() {
let b = budget(&[478, 400], 0, 0).unwrap();
assert_eq!((b.window, b.stride, b.room), (312, 156, 400));
}
#[test]
fn budget_without_questions_uses_the_requested_window_as_room() {
let b = budget(&[], 32, 0).unwrap();
assert_eq!((b.window, b.stride, b.room), (32, 16, 32));
}
#[test]
fn budget_clamps_the_window_to_the_room() {
let b = budget(&[100], 4096, 0).unwrap();
assert_eq!((b.window, b.stride, b.room), (100, 50, 100));
let b = budget(&[100], 0, 0).unwrap();
assert_eq!((b.window, b.stride), (100, 50));
}
#[test]
fn budget_keeps_a_stride_inside_the_clamped_window() {
let b = budget(&[100], 4096, 60).unwrap();
assert_eq!(b.stride, 60);
}
#[test]
fn budget_rejects_a_stride_past_the_window() {
assert_eq!(
message(budget(&[478], 32, 33)),
"predict_long: stride=33 steps past the 32-token window, so 1 tokens between every \
pair of windows would be read by no window at all; pass stride <= 32"
);
}
#[test]
fn budget_rejects_a_stride_past_the_requested_window_even_when_clamped() {
assert_eq!(
message(budget(&[100], 120, 130)),
"predict_long: stride=130 steps past the 100-token window these questions leave room \
for, so 30 tokens between every pair of windows would be read by no window at all; \
pass stride <= 100"
);
}
#[test]
fn budget_reduces_a_stride_past_the_clamped_window_but_within_the_request() {
let b = budget(&[100], 4096, 2048).unwrap();
assert_eq!((b.window, b.stride), (100, 50));
}
#[test]
fn budget_refuses_when_the_questions_leave_no_room() {
assert_eq!(
message(budget(&[300, 0], 0, 0)),
"predict_long: the questions' options fill the whole sequence (max_len=512, \
head_max_len=192), leaving no room for the state; no window can carry any of it. A \
label set this large is what laya.shortlist.predict_shortlist is for"
);
}
#[test]
fn spans_overlap_and_stop_at_the_window_that_reaches_the_end() {
let s = spans(100, 40, 20);
let bounds: Vec<_> = s.iter().map(|w| (w.token_start, w.token_end)).collect();
assert_eq!(bounds, [(0, 40), (20, 60), (40, 80), (60, 100)]);
assert!(s.iter().all(|w| w.count == 4));
assert_eq!(s[3].index, 3);
}
#[test]
fn spans_clip_the_last_window_and_handle_an_exact_fit() {
let s = spans(50, 40, 30);
let bounds: Vec<_> = s.iter().map(|w| (w.token_start, w.token_end)).collect();
assert_eq!(bounds, [(0, 40), (30, 50)]);
assert_eq!(spans(40, 40, 20).len(), 1);
assert!(spans(0, 40, 20).is_empty());
}
#[test]
fn batch_cap_honours_an_explicit_size() {
assert_eq!(batch_cap(10, 312, 312, 3), Some(3));
assert_eq!(batch_cap(10, 23, 312, 3), Some(3));
}
#[test]
fn batch_cap_is_off_unless_the_window_was_clamped_hard() {
assert_eq!(batch_cap(29, 312, 312, 0), None);
// A 64-token budget reduced to 43: under twice the windows, a mild cap.
assert_eq!(batch_cap(20, 43, 64, 0), None);
// 23 against 312: windows multiplied about 13x, bounded at the un-capped count.
assert_eq!(batch_cap(413, 23, 312, 0), Some(30));
}
fn noul(p: f64) -> Answer {
Answer::Noul(NoulAnswer::new(p, p, p, ActionInfo::default()))
}
fn choice(c: f64) -> Answer {
let mut p = IndexMap::new();
p.insert("a".to_string(), c);
Answer::Choice(ChoiceAnswer::new("a", p, c, c, ActionInfo::default()))
}
fn window_result(
noul_answer: Answer,
choice_answer: Answer,
input_tokens: u32,
dropped: usize,
) -> LayaResult {
let mut answers = HashMap::new();
answers.insert("flag".to_string(), noul_answer);
answers.insert("topic".to_string(), choice_answer);
LayaResult::new(
"m",
vec!["flag".to_string(), "topic".to_string()],
answers,
Usage {
input_tokens,
output_tokens: 0,
},
)
.with_state_usage(StateUsage {
state_tokens: 40,
state_tokens_dropped: dropped,
truncated: dropped > 0,
truncated_questions: if dropped > 0 {
vec!["flag".to_string()]
} else {
Vec::new()
},
options: IndexMap::new(),
})
}
fn question_set() -> QuestionSet {
QuestionSet::new()
.with("flag", Question::noul("flag?", Value::Null, Value::Null))
.unwrap()
.with(
"topic",
Question::choice_labels("topic?", ["a", "b"]).unwrap(),
)
.unwrap()
}
#[test]
fn aggregate_takes_max_probability_for_noul_and_max_confidence_for_choice() {
let results = vec![
window_result(noul(0.2), choice(0.6), 10, 0),
window_result(noul(0.9), choice(0.5), 11, 3),
window_result(noul(0.4), choice(0.7), 12, 0),
];
let all = spans(100, 40, 30);
let out = aggregate("m", &question_set(), &results, &all[..3]);
assert_eq!(out["flag"].window().unwrap().index, 1);
assert_eq!(out["topic"].window().unwrap().index, 2);
assert_eq!(out["flag"].as_noul().unwrap().probability, 0.9);
assert_eq!(out.usage().input_tokens, 33);
let state = out.state_usage().unwrap();
assert_eq!(state.state_tokens, 120);
assert_eq!(state.state_tokens_dropped, 3);
assert!(state.truncated);
// The last window's list, which lost nothing.
assert!(state.truncated_questions.is_empty());
assert_eq!(
out.scan_usage(),
Some(ScanUsage {
windows: 3,
truncated_windows: 1
})
);
}
#[test]
fn aggregate_prefers_the_first_window_on_ties() {
let results = vec![
window_result(noul(0.7), choice(0.6), 10, 0),
window_result(noul(0.7), choice(0.6), 10, 0),
];
let all = spans(60, 40, 20);
let out = aggregate("m", &question_set(), &results, &all);
assert_eq!(out["flag"].window().unwrap().index, 0);
assert_eq!(out["topic"].window().unwrap().index, 0);
}
#[test]
fn aggregate_merges_options_with_later_windows_winning() {
let usage = |distinct| OptionUsage {
total: 3,
distinct,
tokens_per_option: Some(4),
};
let with_option = |distinct| {
let result = window_result(noul(0.1), choice(0.5), 1, 0);
let mut state = result.state_usage().unwrap().clone();
state.options.insert("topic".into(), usage(distinct));
result.with_state_usage(state)
};
let all = spans(60, 40, 20);
let out = aggregate(
"m",
&question_set(),
&[with_option(1), with_option(2)],
&all,
);
assert_eq!(out.state_usage().unwrap().options["topic"], usage(2));
}
#[test]
fn aggregate_without_questions_still_counts_windows() {
let empty = || LayaResult::new("m", Vec::new(), HashMap::new(), Usage::default());
let all = spans(60, 40, 20);
let out = aggregate("m", &QuestionSet::new(), &[empty(), empty()], &all);
assert!(out.is_empty());
assert!(out.state_usage().is_none());
assert_eq!(out.scan_usage().unwrap().windows, 2);
}
#[test]
fn default_budget_without_questions_keeps_the_64_floor_for_a_widened_head() {
let b = plan_budget(&[], 200, 192, 0, 0).unwrap();
assert_eq!((b.window, b.stride, b.room), (64, 32, 64));
let b = plan_budget(&[], 512, 192, 0, 0).unwrap();
assert_eq!((b.window, b.stride, b.room), (312, 156, 312));
// Nothing clamps the window, so a stride past it is the caller's error.
let error = message(plan_budget(&[], 512, 192, 40, 41));
assert!(
error.contains("stride=41 steps past the 40-token"),
"{error}"
);
assert!(!error.contains("these questions leave room for"), "{error}");
}
#[test]
fn budget_room_may_exceed_the_default_window_and_an_explicit_one() {
let b = budget(&[478], 0, 0).unwrap();
assert_eq!((b.window, b.room), (312, 478));
let b = budget(&[478], 100, 0).unwrap();
assert_eq!((b.window, b.room), (100, 478));
}
#[test]
fn budget_room_equals_the_window_when_the_room_caps_it() {
for window in [0, 1000] {
let b = budget(&[120, 200], window, 0).unwrap();
assert_eq!((b.window, b.room), (120, 120));
}
}
#[test]
fn budget_stride_equal_to_the_requested_window_is_reduced_after_the_clamp() {
let b = budget(&[100], 1000, 1000).unwrap();
assert_eq!((b.window, b.stride, b.room), (100, 50, 100));
let error = message(budget(&[100], 1000, 1001));
assert!(error.contains("these questions leave room for"), "{error}");
}
#[test]
fn budget_floors_the_default_stride_at_one_token() {
let b = budget(&[], 1, 0).unwrap();
assert_eq!((b.window, b.stride), (1, 1));
}
#[test]
fn budget_with_zero_state_room_names_the_cause() {
let error = message(plan_budget(&[0], 10, 192, 0, 0));
assert!(
error.starts_with(
"predict_long: the questions' options fill the whole sequence (max_len=10, \
head_max_len=192), leaving no room for the state"
),
"{error}"
);
}
#[test]
fn spans_cover_every_token_and_stop_at_the_first_complete_window() {
// (tokens, window, stride, count, last start, last end)
let cases = [
(64, 64, 32, 1, 0, 64),
(65, 64, 32, 2, 32, 65),
(128, 64, 32, 3, 64, 128),
(129, 64, 32, 4, 96, 129),
(129, 64, 64, 3, 128, 129),
(5, 1, 1, 5, 4, 5),
];
for (tokens, window, stride, count, last_start, last_end) in cases {
let all = spans(tokens, window, stride);
assert_eq!(all.len(), count, "{tokens}/{window}/{stride}");
let last = all[count - 1];
assert_eq!(
(last.index, last.token_start, last.token_end, last.count),
(count - 1, last_start, last_end, count)
);
assert_eq!(all[0].token_start, 0);
for (i, w) in all.iter().enumerate() {
assert_eq!((w.index, w.count), (i, count));
if i > 0 {
assert!(w.token_start <= all[i - 1].token_end);
}
}
}
}
#[test]
fn spans_of_a_short_state_are_one_span_and_end_at_the_length() {
let one = spans(10, 64, 32);
assert_eq!(one.len(), 1);
assert_eq!(
(
one[0].index,
one[0].token_start,
one[0].token_end,
one[0].count
),
(0, 0, 10, 1)
);
let two = spans(100, 64, 48);
let bounds: Vec<_> = two.iter().map(|w| (w.token_start, w.token_end)).collect();
assert_eq!(bounds, [(0, 64), (48, 100)]);
assert!(two.iter().all(|w| w.count == 2));
}
#[test]
fn batch_cap_edge_cases_match_python() {
// (count, window, budget, batch_size, expected)
let cases = [
(100, 312, 312, 7, Some(7)), // explicit size, even when the window is not capped
(100, 50, 1, 0, None), // window >= budget; budget / 2 floors at 1
(1, 1, 312, 0, None),
(2, 50, 312, 0, None), // n == 2 * unclamped keeps the single pass
(3, 50, 312, 0, Some(1)), // one past it chunks at unclamped
(12, 50, 312, 0, Some(2)), // ceil(300 / 156) = 2; 12 > 4
(34, 50, 312, 0, Some(6)), // ceil(850 / 156) = 6; 34 > 12
(5, 200, 312, 0, None), // ceil(500 / 156) = 4; 5 <= 8
(100, 1, 312, 0, Some(1)), // window / 2 floors at 1
(100, 312, 312, 0, None),
(100, 200, 312, 0, None),
(100, 50, 312, 0, Some(17)),
(100, 50, 312, 3, Some(3)),
];
for (count, window, budget, batch, expected) in cases {
assert_eq!(
batch_cap(count, window, budget, batch),
expected,
"{count}/{window}/{budget}/{batch}"
);
}
}
fn score(level: f64, c: f64) -> Answer {
Answer::Score(ScoreAnswer::new(
level,
vec![Value::from("low"), Value::from("high")],
vec![1.0 - c, c],
0.1,
c,
ActionInfo::default(),
))
}
fn three_questions() -> QuestionSet {
question_set()
.with(
"urgency",
Question::score("urgent?", ["low", "high"]).unwrap(),
)
.unwrap()
}
fn triple(noul_answer: Answer, c: f64, s: f64, input: u32) -> LayaResult {
let mut answers = HashMap::new();
answers.insert("flag".to_string(), noul_answer);
answers.insert("topic".to_string(), choice(c));
answers.insert("urgency".to_string(), score(s, s));
LayaResult::new(
"m",
vec!["flag".into(), "topic".into(), "urgency".into()],
answers,
Usage {
input_tokens: input,
output_tokens: 7,
},
)
}
#[test]
fn aggregate_selects_evidence_not_entropy() {
// Window 1's noul has the lower answer_confidence but the higher P(true): it must win.
let low_p = Answer::Noul(NoulAnswer::new(0.05, 0.95, 0.95, ActionInfo::default()));
let high_p = Answer::Noul(NoulAnswer::new(0.7, 0.7, 0.7, ActionInfo::default()));
let all = spans(65, 64, 32);
let out = aggregate(
"m",
&three_questions(),
&[triple(low_p, 0.8, 0.6, 20), triple(high_p, 0.8, 0.9, 30)],
&all,
);
assert_eq!(out["flag"].window(), Some(all[1]));
assert_eq!(out["topic"].window(), Some(all[0])); // tie
assert_eq!(out["urgency"].window(), Some(all[1]));
assert_eq!(out["urgency"].as_score().unwrap().score, 0.9);
assert_eq!(out.usage().input_tokens, 50);
assert_eq!(out.usage().output_tokens, 0);
}
#[test]
fn aggregate_ties_go_to_the_first_window_for_all_three_types() {
let tie = || triple(noul(0.7), 0.8, 0.6, 20);
let all = spans(65, 64, 32);
let out = aggregate("m", &three_questions(), &[tie(), tie()], &all);
for id in ["flag", "topic", "urgency"] {
assert_eq!(out[id].window(), Some(all[0]), "{id}");
}
assert_eq!(out.scan_usage().unwrap().windows, 2);
}
#[test]
fn aggregate_of_one_window_without_state_usage_leaves_the_fields_none() {
let all = spans(10, 64, 32);
let out = aggregate(
"m",
&three_questions(),
&[triple(noul(0.7), 0.8, 0.6, 20)],
&all,
);
let w = out["flag"].window().unwrap();
assert_eq!(
(w.index, w.token_start, w.token_end, w.count),
(0, 0, 10, 1)
);
assert_eq!(out.usage().input_tokens, 20);
assert_eq!(out.usage().output_tokens, 0);
assert!(out.state_usage().is_none());
assert_eq!(
out.scan_usage(),
Some(ScanUsage {
windows: 1,
truncated_windows: 0
})
);
}
#[test]
fn aggregate_carries_the_last_windows_truncated_questions() {
let truncated = |input, names: &[&str]| {
triple(noul(0.7), 0.8, 0.6, input).with_state_usage(StateUsage {
state_tokens: 10,
state_tokens_dropped: 1,
truncated: true,
truncated_questions: names.iter().map(|n| n.to_string()).collect(),
options: IndexMap::new(),
})
};
let all = spans(65, 64, 32);
let out = aggregate(
"m",
&three_questions(),
&[truncated(20, &["urgency"]), truncated(30, &[])],
&all,
);
let state = out.state_usage().unwrap();
assert!(state.truncated_questions.is_empty());
assert_eq!(state.state_tokens_dropped, 2);
assert_eq!(out.scan_usage().unwrap().truncated_windows, 2);
}
#[test]
fn long_options_default_to_python_and_check_aggregate() {
let options = LongOptions::new();
assert_eq!(
(options.window, options.stride, options.batch_size),
(None, None, None)
);
assert!(options.check_aggregate().is_ok());
assert!(
LongOptions::new()
.aggregate("auto")
.check_aggregate()
.is_ok()
);
let error = LongOptions::new()
.aggregate("max")
.check_aggregate()
.unwrap_err();
assert!(
matches!(error, LayaError::UnsupportedAggregate(_)),
"{error:?}"
);
}
const WARN_CAPPED_DEFAULT: &str = "laya: predict_long: these questions leave only 102 of \
max_len=512 for the state (their heads take the rest), so the scan window is capped 312 \
-> 102 and roughly 3.1x as many windows -- each a full forward pass -- are needed to read \
the document. Fewer or shorter options, a larger max_len, or \
laya.shortlist.predict_shortlist for a large label set will all cost less than scanning \
at this width";
const WARN_WINDOW: &str = "laya: predict_long: window=100 is wider than the 32 state tokens \
these questions leave inside max_len=512, so every window would be truncated to 32 on the \
way to the model; scanning with window=32 instead";
const WARN_STRIDE: &str = "laya: predict_long: stride=64 was a 50% step for the window=100 \
you asked for, but the window was reduced to 32 to fit the room these questions leave; \
scanning with stride=16 instead";
fn warned(rooms: &[usize], window: usize, stride: usize) -> Vec<String> {
plan_budget_warned(rooms, 512, 192, window, stride)
.unwrap()
.1
}
// Expected texts and which calls warn were produced by running Python's
// `common.window_budget` with `warnings.catch_warnings(record=True)`.
#[test]
fn warns_with_pythons_text_when_the_default_window_is_capped_hard() {
assert_eq!(vec![WARN_CAPPED_DEFAULT], warned(&[102], 0, 0));
assert!(warned(&[150], 0, 0)[0].contains("capped 312 -> 150 and roughly 2.1x as many"));
}
#[test]
fn stays_silent_when_the_default_window_is_capped_mildly_or_not_at_all() {
assert!(warned(&[200], 0, 0).is_empty());
assert!(warned(&[400], 0, 0).is_empty());
assert!(warned(&[312], 0, 0).is_empty());
}
// 312 / 96 = 3.25 is an exact tie: Python's `%.1f` rounds it half to even and prints 3.2.
#[test]
fn window_capped_ratio_tie_prints_as_python_does() {
let text = warned(&[96], 0, 0).remove(0);
assert!(
text.contains("capped 312 -> 96 and roughly 3.2x as many windows"),
"{text}"
);
}
#[test]
fn warns_with_pythons_text_when_an_explicit_window_is_capped() {
assert_eq!(vec![WARN_WINDOW], warned(&[32], 100, 0));
assert_eq!(2, warned(&[100], 300, 150).len());
// A stride that already fits the capped window adds nothing.
assert_eq!(1, warned(&[100], 300, 40).len());
}
#[test]
fn warns_with_pythons_text_when_the_stride_is_reduced() {
assert_eq!(vec![WARN_WINDOW, WARN_STRIDE], warned(&[32], 100, 64));
assert_eq!(
"laya: predict_long: stride=150 was a 50% step for the window=300 you asked for, but \
the window was reduced to 100 to fit the room these questions leave; scanning with \
stride=50 instead",
warned(&[100], 300, 150)[1]
);
}
#[test]
fn emit_warnings_reaches_the_log_facade_at_warn_level_under_target_laya() {
use std::sync::Mutex;
static SEEN: Mutex<Vec<(String, log::Level, String)>> = Mutex::new(Vec::new());
struct Capture;
impl log::Log for Capture {
fn enabled(&self, _: &log::Metadata) -> bool {
true
}
fn log(&self, record: &log::Record) {
SEEN.lock().unwrap().push((
record.target().to_string(),
record.level(),
record.args().to_string(),
));
}
fn flush(&self) {}
}
static LOGGER: Capture = Capture;
log::set_logger(&LOGGER).unwrap();
log::set_max_level(log::LevelFilter::Warn);
let at = std::panic::Location::caller();
emit_warnings(&[WARN_WINDOW.to_string(), WARN_STRIDE.to_string()], at);
// Python shows an identical warning once per process; a repeat is dropped.
emit_warnings(&[WARN_WINDOW.to_string()], at);
let seen = SEEN.lock().unwrap();
let ours: Vec<_> = seen.iter().filter(|(t, ..)| t == "laya").collect();
assert_eq!(2, ours.len());
assert_eq!(log::Level::Warn, ours[0].1);
assert_eq!(WARN_WINDOW, ours[0].2);
assert_eq!(WARN_STRIDE, ours[1].2);
}
}