Skip to content

armgit / laya

Public Imported from GitHub
0

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.

14.4 KB
Raw Blame
//! Builds the typed token sequence one question is answered from. Ports `build_sequence`,
//! `render_options` and `render_criterion` from `laya/common.py`, step by step.
//!
//! The layout is `[CLS] <type> question: instructions [SEP] [MASK] opt0 [MASK] opt1 ... [SEP]
//! state [SEP]`. The scorer reads the hidden state at each `[MASK]`, so a marker position that is
//! off by one token attaches an option's probability to the wrong place in the sequence and the
//! model answers a different question without anything failing. Every offset here is therefore
//! load-bearing.

use crate::error::Result;
use crate::python_json::PythonJson;
use crate::questions::Question;
use crate::tokenization::LayaTokenizer;
use serde_json::Value;

/// Namespace for sequence construction. See the module docs for the source this ports.
pub struct SequenceBuilder;

#[derive(Debug, Clone, Copy)]
pub(crate) struct StateTokenStats {
    pub tokens: usize,
    pub dropped: usize,
    pub options: Option<crate::answers::OptionUsage>,
}

/// The question-specific start of a sequence, before any state.
struct Head {
    ids: Vec<u32>,
    markers: Vec<usize>,
    options: Option<crate::answers::OptionUsage>,
}

impl SequenceBuilder {
    /// One option fragment is capped at this many tokens, before the marker is prepended.
    const MAX_OPTION_TOKENS: usize = 48;

    /// The head is never squeezed below this, even when the options have eaten the budget.
    const MIN_HEAD_TOKENS: usize = 8;

    /// The Python type name, which appears verbatim in the prompt text.
    pub fn type_name(qtype: crate::questions::QuestionType) -> &'static str {
        use crate::questions::QuestionType;
        match qtype {
            QuestionType::Choice => "choice",
            QuestionType::Score => "score",
            QuestionType::Noul => "noul",
        }
    }

    /// The instruction text as it reaches the tokenizer: a string verbatim, anything else through
    /// the `json.dumps` dialect that keeps non-ASCII characters literal (`ensure_ascii=False`).
    /// Ports `Agent._to_internal` (laya 0.3.21; 0.3.6 escaped non-ASCII here instead).
    pub fn render_instructions(question: &Question) -> String {
        match question.instructions() {
            Value::String(s) => s.clone(),
            other => PythonJson::instructions(other),
        }
    }

    /// The option texts in label-index order. Index N is the option the Nth logit scores, so this
    /// order is what binds a probability to a label.
    pub fn render_options(question: &Question) -> Vec<String> {
        match question {
            Question::Choice(c) => c
                .options()
                .iter()
                .map(|(label, description)| {
                    if Self::is_blank_criterion(description) {
                        label.clone()
                    } else {
                        format!("{label}: {}", PythonJson::criterion(description))
                    }
                })
                .collect(),
            Question::Score(s) => s
                .levels()
                .iter()
                .enumerate()
                .map(|(i, level)| format!("level {i}: {}", PythonJson::criterion(level)))
                .collect(),
            Question::Noul(n) => {
                let false_text = if Self::is_blank_criterion(n.if_false()) {
                    "no, the statement does not hold".to_string()
                } else {
                    PythonJson::criterion(n.if_false())
                };
                let true_text = if Self::is_blank_criterion(n.if_true()) {
                    "yes, the statement holds".to_string()
                } else {
                    PythonJson::criterion(n.if_true())
                };
                vec![format!("false: {false_text}"), format!("true: {true_text}")]
            }
        }
    }

    /// Whether a criterion value means "no description". Python tests `v is None or v == ""`, so
    /// only null and the empty string qualify: `0` and `false` are real descriptions and get
    /// rendered.
    fn is_blank_criterion(value: &Value) -> bool {
        matches!(value, Value::Null) || matches!(value, Value::String(s) if s.is_empty())
    }

    /// A literal mask token anywhere in user input would forge a marker the scorer then reads as
    /// an option, so every fragment has it replaced with a space before encoding.
    fn scrub(text: &str, mask_token: &str) -> String {
        if mask_token.is_empty() {
            text.to_string()
        } else {
            text.replace(mask_token, " ")
        }
    }

    /// Python's `//`: floor division, rounding toward negative infinity. `b` is always `>= 1` at
    /// every call site here, so this is equivalent to (and implemented with) `div_euclid`.
    fn floor_div(a: i64, b: i64) -> i64 {
        a.div_euclid(b)
    }

    /// Build the token sequence and marker positions for one question.
    ///
    /// `tokenizer` must encode without special tokens. `state` is the value being judged;
    /// `max_len` is the total sequence budget; `head_max_len` is the budget for instructions plus
    /// option fragments; `truncate_left` keeps the end of an over-long state rather than its
    /// start. `LayaEngine::predict_value` sets this to `true` exactly when `state` is a JSON
    /// array, matching `Agent._encode_state`'s `truncate_left = isinstance(state, list)` (laya
    /// 0.3.21): a conversation-turn list is serialized newest-last, so right-truncating it would
    /// drop the newest turn instead of the oldest one.
    ///
    /// Returns the token ids and one marker position per option. Markers landing at or past
    /// `max_len` are dropped — a short marker list means options did not fit, which the caller
    /// must treat as an error rather than answering a truncated question; this function itself
    /// never errors on that condition, matching `SequenceBuilder.Build` exactly.
    pub fn build(
        tokenizer: &dyn LayaTokenizer,
        state: &Value,
        question: &Question,
        max_len: usize,
        head_max_len: usize,
        truncate_left: bool,
    ) -> Result<(Vec<u32>, Vec<usize>)> {
        Self::build_with_stats(
            tokenizer,
            state,
            question,
            max_len,
            head_max_len,
            truncate_left,
        )
        .map(|(ids, markers, _)| (ids, markers))
    }

    /// The question's own part of the sequence: everything up to and including the SEP that
    /// closes the options. Ports `build_head` from `laya/common.py`.
    fn build_head(
        tokenizer: &dyn LayaTokenizer,
        question: &Question,
        head_max_len: i64,
    ) -> Result<Head> {
        let special = tokenizer.special();
        let mask_token = special.mask_token.as_str();

        let options = Self::render_options(question);
        let instructions = Self::scrub(&Self::render_instructions(question), mask_token);
        let header_text = format!(
            "{} question: {instructions}",
            Self::type_name(question.question_type())
        );
        let mut header_ids: Vec<u32> = tokenizer.encode(&header_text)?;

        let mut option_ids: Vec<Vec<u32>> = Vec::with_capacity(options.len());
        for option in &options {
            let encoded = tokenizer.encode(&format!(" {}", Self::scrub(option, mask_token)))?;
            let take = Self::MAX_OPTION_TOKENS.min(encoded.len());
            let mut fragment = Vec::with_capacity(take + 1);
            fragment.push(special.mask_id);
            fragment.extend_from_slice(&encoded[..take]);
            option_ids.push(fragment);
        }

        let option_len_sum =
            |opts: &[Vec<u32>]| -> i64 { opts.iter().map(|o| o.len() as i64).sum() };

        // A bound beyond i64 (Python accepts any int) is as good as i64::MAX here: nothing the
        // head can hold comes near it, and a plain `as i64` would wrap it negative.
        let head_bound = head_max_len;
        let mut opt_budget = head_bound.saturating_sub(option_len_sum(&option_ids));
        let mut tokens_per_option = None;
        if opt_budget < 16 {
            let per = 4i64.max(Self::floor_div(
                head_bound.saturating_sub(16),
                1i64.max(option_ids.len() as i64),
            )) as usize;
            tokens_per_option = Some(per);
            for fragment in &mut option_ids {
                if fragment.len() > per {
                    fragment.truncate(per);
                }
            }
            opt_budget = head_bound.saturating_sub(option_len_sum(&option_ids));
        }

        let head_take = (Self::MIN_HEAD_TOKENS as i64).max(opt_budget) as usize;
        if header_ids.len() > head_take {
            header_ids.truncate(head_take);
        }

        // Sized from what is appended (CLS, header, SEP, the option fragments, SEP), never from
        // the configured bound, which can be any size.
        let appended = header_ids.len() + option_ids.iter().map(Vec::len).sum::<usize>() + 3;
        let mut ids: Vec<u32> = Vec::with_capacity(appended);
        ids.push(special.cls_id);
        ids.extend_from_slice(&header_ids);
        ids.push(special.sep_id);

        let mut markers = Vec::with_capacity(option_ids.len());
        for fragment in &option_ids {
            markers.push(ids.len());
            ids.extend_from_slice(fragment);
        }
        ids.push(special.sep_id);

        let distinct = option_ids
            .iter()
            .collect::<std::collections::HashSet<_>>()
            .len();
        let options = (distinct < option_ids.len()).then_some(crate::answers::OptionUsage {
            total: option_ids.len(),
            distinct,
            tokens_per_option,
        });
        Ok(Head {
            ids,
            markers,
            options,
        })
    }

    /// How many state tokens `question` leaves inside `max_len`: what `build_sequence` keeps of
    /// the state. Ports `state_room` from `laya/common.py`.
    pub(crate) fn state_room(
        tokenizer: &dyn LayaTokenizer,
        question: &Question,
        max_len: usize,
        head_max_len: usize,
    ) -> Result<usize> {
        let head = Self::build_head(tokenizer, question, Self::signed(head_max_len))?;
        // -1 reserves the SEP that closes the state.
        Ok(max_len.saturating_sub(head.ids.len() + 1))
    }

    /// The state's token ids exactly as `build_with_stats` slices them: serialized, mask token
    /// scrubbed, encoded without special tokens.
    pub(crate) fn encode_state(tokenizer: &dyn LayaTokenizer, state: &Value) -> Result<Vec<u32>> {
        let mask_token = tokenizer.special().mask_token.as_str();
        tokenizer.encode(&Self::scrub(&PythonJson::state(state), mask_token))
    }

    /// [`Self::build`] with signed budgets, as a per-call `max_len` / `head_max_len` override
    /// gives them; see `build_with_overrides`. Hidden from the docs: it exists so the integration
    /// tests can reach the signed arithmetic without a model.
    #[doc(hidden)]
    pub fn build_signed(
        tokenizer: &dyn LayaTokenizer,
        state: &Value,
        question: &Question,
        max_len: i64,
        head_max_len: i64,
        truncate_left: bool,
    ) -> Result<(Vec<u32>, Vec<usize>)> {
        Self::build_with_overrides(
            tokenizer,
            state,
            question,
            max_len,
            head_max_len,
            truncate_left,
        )
        .map(|(ids, markers, _)| (ids, markers))
    }

    /// A budget beyond i64 (Python accepts any int) is as good as i64::MAX here: nothing the
    /// sequence can hold comes near it, and a plain `as i64` would wrap it negative.
    pub(crate) fn signed(length: usize) -> i64 {
        i64::try_from(length).unwrap_or(i64::MAX)
    }

    pub(crate) fn build_with_stats(
        tokenizer: &dyn LayaTokenizer,
        state: &Value,
        question: &Question,
        max_len: usize,
        head_max_len: usize,
        truncate_left: bool,
    ) -> Result<(Vec<u32>, Vec<usize>, StateTokenStats)> {
        Self::build_with_overrides(
            tokenizer,
            state,
            question,
            Self::signed(max_len),
            Self::signed(head_max_len),
            truncate_left,
        )
    }

    /// [`Self::build_with_stats`] with the budgets as a per-call override can give them: Python
    /// does no validation, so `0` and negative values flow into the same arithmetic and slices
    /// (`ids[:max_len]` with a negative `max_len` drops that many tokens from the end, and every
    /// marker is then past it). The caller refuses a question that lost a marker.
    ///
    pub(crate) fn build_with_overrides(
        tokenizer: &dyn LayaTokenizer,
        state: &Value,
        question: &Question,
        max_len: i64,
        head_max_len: i64,
        truncate_left: bool,
    ) -> Result<(Vec<u32>, Vec<usize>, StateTokenStats)> {
        let special = tokenizer.special();
        let mask_token = special.mask_token.as_str();
        let Head {
            mut ids,
            mut markers,
            options,
        } = Self::build_head(tokenizer, question, head_max_len)?;

        // -1 reserves the final SEP that closes the whole sequence, appended below.
        let room = usize::try_from(max_len.saturating_sub(ids.len() as i64 + 1)).unwrap_or(0);
        let state_text = Self::scrub(&PythonJson::state(state), mask_token);
        let state_ids = tokenizer.encode(&state_text)?;
        let sliced: &[u32] = if truncate_left {
            // Python's `state_ids[max(0, len(state_ids) - room):]` (laya 0.3.21): newest tokens
            // kept, and with no room left none of the state (0.3.6's `st[-room:]` kept all of
            // it). `LayaEngine::predict_value` reaches this branch for a JSON-array state (a
            // conversation-turn list).
            &state_ids[state_ids.len().saturating_sub(room)..]
        } else {
            &state_ids[..room.min(state_ids.len())]
        };
        ids.extend_from_slice(sliced);
        ids.push(special.sep_id);

        // `ids[:max_len]`: a negative bound counts from the end.
        let keep = if max_len >= 0 {
            usize::try_from(max_len).unwrap_or(usize::MAX)
        } else {
            usize::try_from(ids.len() as i64 + max_len).unwrap_or(0)
        };
        if ids.len() > keep {
            ids.truncate(keep);
        }
        markers.retain(|&m| (m as i64) < max_len);

        let stats = StateTokenStats {
            tokens: state_ids.len(),
            dropped: state_ids.len() - sliced.len(),
            options,
        };
        Ok((ids, markers, stats))
    }
}