laya_core/

question.rs

//! Typed question definitions, validated and rendered exactly as upstream does.

use crate::error::{Error, Result};
use crate::json_compat::{dumps_ascii, dumps_unicode};
use serde_json::{Map, Value};

/// Question type, and the integer the model's type embedding expects.
///
/// Mirrors upstream's `QTYPES = {"choice": 0, "score": 1, "noul": 2}`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum QuestionKind {
    Choice = 0,
    Score = 1,
    Noul = 2,
}

impl QuestionKind {
    pub fn index(self) -> usize {
        self as usize
    }

    pub fn name(self) -> &'static str {
        match self {
            Self::Choice => "choice",
            Self::Score => "score",
            Self::Noul => "noul",
        }
    }

    pub fn parse(value: &str) -> Option<Self> {
        match value {
            "choice" => Some(Self::Choice),
            "score" => Some(Self::Score),
            "noul" => Some(Self::Noul),
            _ => None,
        }
    }
}

/// Validated criteria, in label order.
#[derive(Clone, Debug, PartialEq)]
pub enum Criteria {
    /// Ordered `(label, description)` pairs. A `Null` or `""` description means
    /// the label is rendered on its own.
    Choice(Vec<(String, Value)>),
    /// Ordered rubric levels, rendered as `level 0: ...`.
    Score(Vec<Value>),
    /// Optional `false` / `true` descriptions.
    Noul {
        false_desc: Option<Value>,
        true_desc: Option<Value>,
    },
}

/// A question after validation, equivalent to upstream's internal
/// `{"t": ..., "ins": ..., "crit": ...}` triple.
#[derive(Clone, Debug, PartialEq)]
pub struct Question {
    pub kind: QuestionKind,
    pub instructions: String,
    pub criteria: Criteria,
}

fn is_blank(value: &Value) -> bool {
    // Upstream treats only None and "" as "no description"; 0 and false are
    // legitimate criterion values and must still render.
    value.is_null() || value.as_str() == Some("")
}

/// Upstream's `render_criterion`: strings pass through, anything structured
/// becomes compact JSON so a rubric reads as JSON rather than a Python repr.
pub fn render_criterion(value: &Value) -> String {
    match value {
        Value::String(text) => text.clone(),
        other => dumps_unicode(other),
    }
}

impl Question {
    /// Validate one question definition, mirroring `Agent._to_internal`.
    pub fn from_value(value: &Value) -> Result<Self> {
        let object = value
            .as_object()
            .ok_or_else(|| Error::Question("Each question must be a dictionary".into()))?;

        let kind = object
            .get("type")
            .and_then(Value::as_str)
            .and_then(QuestionKind::parse)
            .ok_or_else(|| {
                let shown = object.get("type").map_or("None".to_string(), render_repr);
                Error::Question(format!(
                    "Unknown question type {shown}; expected choice, score, or noul"
                ))
            })?;

        let instructions_value = object
            .get("instructions")
            .ok_or_else(|| Error::Question("Question is missing instructions".into()))?;
        let instructions = match instructions_value {
            Value::String(text) => text.clone(),
            // Upstream falls back to `json.dumps(instructions)` with CPython's
            // defaults here, which means ensure_ascii stays on.
            other => dumps_ascii(other),
        };

        let criteria = object.get("criteria").unwrap_or(&Value::Null);
        let criteria = match kind {
            QuestionKind::Choice => Self::choice_criteria(criteria)?,
            QuestionKind::Score => {
                let items = criteria.as_array().filter(|items| !items.is_empty());
                let items = items.ok_or_else(|| {
                    Error::Question("Score criteria must be a nonempty list".into())
                })?;
                Criteria::Score(items.clone())
            }
            QuestionKind::Noul => {
                if criteria.is_null() {
                    Criteria::Noul {
                        false_desc: None,
                        true_desc: None,
                    }
                } else {
                    let map = criteria.as_object().ok_or_else(|| {
                        Error::Question(
                            "Noul criteria must be a dictionary with false/true descriptions"
                                .into(),
                        )
                    })?;
                    Criteria::Noul {
                        false_desc: map.get("false").cloned(),
                        true_desc: map.get("true").cloned(),
                    }
                }
            }
        };

        Ok(Self {
            kind,
            instructions,
            criteria,
        })
    }

    fn choice_criteria(criteria: &Value) -> Result<Criteria> {
        match criteria {
            // A list of unique labels becomes `dict.fromkeys(...)`: every
            // description is null.
            Value::Array(items) => {
                let mut labels = Vec::with_capacity(items.len());
                for item in items {
                    let label = item
                        .as_str()
                        .ok_or_else(|| Error::Question("Choice labels must be strings".into()))?;
                    labels.push(label.to_string());
                }
                let mut seen = std::collections::HashSet::with_capacity(labels.len());
                if !labels.iter().all(|label| seen.insert(label.as_str())) {
                    return Err(Error::Question("Choice labels must be unique".into()));
                }
                if labels.is_empty() {
                    return Err(Error::Question(
                        "Choice criteria must be a nonempty dictionary or list".into(),
                    ));
                }
                Ok(Criteria::Choice(
                    labels
                        .into_iter()
                        .map(|label| (label, Value::Null))
                        .collect(),
                ))
            }
            Value::Object(map) if !map.is_empty() => Ok(Criteria::Choice(
                map.iter().map(|(k, v)| (k.clone(), v.clone())).collect(),
            )),
            _ => Err(Error::Question(
                "Choice criteria must be a nonempty dictionary or list".into(),
            )),
        }
    }

    /// Option texts in label-index order. Noul is always `[false, true]`.
    pub fn render_options(&self) -> Vec<String> {
        match &self.criteria {
            Criteria::Choice(pairs) => pairs
                .iter()
                .map(|(label, description)| {
                    if is_blank(description) {
                        label.clone()
                    } else {
                        format!("{label}: {}", render_criterion(description))
                    }
                })
                .collect(),
            Criteria::Score(levels) => levels
                .iter()
                .enumerate()
                .map(|(index, level)| format!("level {index}: {}", render_criterion(level)))
                .collect(),
            Criteria::Noul {
                false_desc,
                true_desc,
            } => {
                let render = |value: &Option<Value>, fallback: &str| match value {
                    Some(inner) if !is_blank(inner) => render_criterion(inner),
                    _ => fallback.to_string(),
                };
                vec![
                    format!(
                        "false: {}",
                        render(false_desc, "no, the statement does not hold")
                    ),
                    format!("true: {}", render(true_desc, "yes, the statement holds")),
                ]
            }
        }
    }

    /// Labels for a choice question, in order.
    pub fn choice_labels(&self) -> Option<Vec<String>> {
        match &self.criteria {
            Criteria::Choice(pairs) => Some(pairs.iter().map(|(k, _)| k.clone()).collect()),
            _ => None,
        }
    }

    /// Rubric legend for a score question, rendered as upstream stores it.
    pub fn score_legend(&self) -> Option<Map<String, Value>> {
        match &self.criteria {
            Criteria::Score(levels) => {
                let mut legend = Map::new();
                for (index, level) in levels.iter().enumerate() {
                    legend.insert(index.to_string(), level.clone());
                }
                Some(legend)
            }
            _ => None,
        }
    }
}

/// Render a value the way a Python error message would show it.
fn render_repr(value: &Value) -> String {
    match value {
        Value::String(text) => format!("{text:?}"),
        Value::Null => "None".into(),
        Value::Bool(true) => "True".into(),
        Value::Bool(false) => "False".into(),
        other => other.to_string(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    fn q(value: Value) -> Question {
        Question::from_value(&value).expect("valid question")
    }

    #[test]
    fn choice_list_renders_bare_labels() {
        let question = q(json!({
            "type": "choice", "instructions": "Pick", "criteria": ["a", "b"]
        }));
        assert_eq!(question.render_options(), vec!["a", "b"]);
    }

    #[test]
    fn choice_map_renders_descriptions_and_keeps_order() {
        let question = q(json!({
            "type": "choice",
            "instructions": "Pick",
            "criteria": {"billing": "refunds", "tech": "", "zero": 0}
        }));
        assert_eq!(
            question.render_options(),
            vec!["billing: refunds", "tech", "zero: 0"]
        );
    }

    #[test]
    fn structured_criterion_becomes_json() {
        let question = q(json!({
            "type": "choice",
            "instructions": "Pick",
            "criteria": {"a": {"desc": "x", "n": 1}}
        }));
        assert_eq!(
            question.render_options(),
            vec![r#"a: {"desc": "x", "n": 1}"#]
        );
    }

    #[test]
    fn score_levels_are_numbered() {
        let question = q(json!({
            "type": "score", "instructions": "How bad", "criteria": ["low", "high"]
        }));
        assert_eq!(
            question.render_options(),
            vec!["level 0: low", "level 1: high"]
        );
    }

    #[test]
    fn noul_defaults_and_overrides() {
        let bare = q(json!({"type": "noul", "instructions": "True?"}));
        assert_eq!(
            bare.render_options(),
            vec![
                "false: no, the statement does not hold",
                "true: yes, the statement holds"
            ]
        );
        let described = q(json!({
            "type": "noul",
            "instructions": "True?",
            "criteria": {"true": "it holds"}
        }));
        assert_eq!(
            described.render_options(),
            vec!["false: no, the statement does not hold", "true: it holds"]
        );
    }

    #[test]
    fn rejects_bad_definitions() {
        assert!(Question::from_value(&json!({"type": "nope", "instructions": "x"})).is_err());
        assert!(Question::from_value(&json!({"type": "choice"})).is_err());
        assert!(Question::from_value(&json!({
            "type": "choice", "instructions": "x", "criteria": ["a", "a"]
        }))
        .is_err());
        assert!(Question::from_value(&json!({
            "type": "score", "instructions": "x", "criteria": []
        }))
        .is_err());
    }

    #[test]
    fn non_string_instructions_use_ascii_json() {
        let question = q(json!({
            "type": "noul", "instructions": {"ask": "h\u{e9}llo"}
        }));
        assert_eq!(question.instructions, "{\"ask\": \"h\\u00e9llo\"}");
    }
}