//! Call detection: does Jarvis answer this utterance? (`app/src/conversation.spec.md`). //! //! A pure function of the settings, the speaker and the text. Wake words and stop words are settings; //! matching works on Unicode-normalised letters, so it behaves the same in any script. use std::collections::HashSet; use std::time::Duration; use unicode_normalization::UnicodeNormalization; #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum CallMode { /// Answer only when called by a wake word (default). WakeWord, /// Also answer what the brain judges to be said to Jarvis. Addressed, /// Answer every utterance. Everything, } #[derive(Debug, Clone, PartialEq)] pub struct CallSettings { pub wake_words: Vec, /// Share of a wake word's normalised letters a heard word may differ by (0-0.5). pub similarity: f64, pub mode: CallMode, pub designated: HashSet, pub designated_only: bool, pub designated_no_wake_word: bool, pub stop_words: Vec, /// After a wake word said alone, how long the speaker's next utterance may take to start and /// still be joined to it (the pause after "Jarvis," often ends an utterance). pub follow_up: Duration, /// Play the earcon when Jarvis takes a voice call (`call.earcon`). pub earcon: bool, } impl Default for CallSettings { fn default() -> Self { Self { wake_words: vec!["자비스".into()], similarity: 0.2, mode: CallMode::WakeWord, designated: HashSet::new(), designated_only: false, designated_no_wake_word: false, stop_words: ["멈춰", "그만", "정지", "stop"].map(String::from).to_vec(), follow_up: Duration::from_millis(1500), earcon: true, } } } #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Call { Ignore, /// Answer it. `direct`: called by a wake word. Request { direct: bool }, /// Ask the brain whether it was said to Jarvis (`call.mode` `addressed`). Ask, /// Stop the current answer and drop the waiting requests. Stop, } /// Most letters after a stop word that still count as the stop ("멈춰 줘", "그만해"). const STOP_TAIL: usize = 3; /// NFKD, lower case, letters and digits only. pub fn normalise(text: &str) -> Vec { text.nfkd().flat_map(char::to_lowercase).filter(|c| c.is_alphanumeric()).collect() } /// The stretch `[start, end)` of `text` closest to `word`, if within `max_edits` edits /// (approximate substring matching: the match may start and end anywhere in `text`). fn find(text: &[char], word: &[char], max_edits: usize) -> Option<(usize, usize)> { if word.is_empty() || text.is_empty() { return None; } let (n, m) = (text.len(), word.len()); // d[i][j]: fewest edits turning word[..i] into a stretch of text ending at j; start[i][j] where it began. let mut d = vec![vec![0usize; n + 1]; m + 1]; let mut start = vec![vec![0usize; n + 1]; m + 1]; for j in 0..=n { start[0][j] = j; } for i in 1..=m { d[i][0] = i; start[i][0] = 0; for j in 1..=n { let sub = d[i - 1][j - 1] + usize::from(word[i - 1] != text[j - 1]); let del = d[i - 1][j] + 1; // word letter missing from text let ins = d[i][j - 1] + 1; // extra letter in text let (best, from) = if sub <= del && sub <= ins { (sub, start[i - 1][j - 1]) } else if del <= ins { (del, start[i - 1][j]) } else { (ins, start[i][j - 1]) }; d[i][j] = best; start[i][j] = from; } } (1..=n) .filter(|&j| d[m][j] <= max_edits) .min_by_key(|&j| (d[m][j], j)) .map(|j| (start[m][j], j)) } impl CallSettings { fn allowed_edits(&self, word: &[char]) -> usize { (self.similarity.clamp(0.0, 0.5) * word.len() as f64 + 1e-9).floor() as usize } /// The text with the first heard wake word removed, if one is heard. fn without_wake_word(&self, text: &[char]) -> Option> { // The earliest heard wake word is the one used to address Jarvis. let (s, e) = self .wake_words .iter() .map(|w| normalise(w)) .filter_map(|word| find(text, &word, self.allowed_edits(&word))) .min()?; Some(text[..s].iter().chain(&text[e..]).copied().collect()) } fn is_stop(&self, rest: &[char]) -> bool { self.stop_words.iter().map(|w| normalise(w)).any(|w| { !w.is_empty() && rest.starts_with(&w) && rest.len() - w.len() <= STOP_TAIL }) } /// A wake word is heard and nothing else (no letters or digits around it). pub fn wake_word_only(&self, text: &str) -> bool { self.without_wake_word(&normalise(text)).is_some_and(|rest| rest.is_empty()) } /// Decide what to do with one finished utterance. pub fn judge(&self, speaker: u64, text: &str) -> Call { let norm = normalise(text); if norm.is_empty() { return Call::Ignore; } let designated = self.designated.contains(&speaker); if self.designated_only && !designated { return Call::Ignore; } if let Some(rest) = self.without_wake_word(&norm) { if self.is_stop(&rest) { return Call::Stop; } return Call::Request { direct: true }; } if self.designated_no_wake_word && designated { return Call::Request { direct: false }; } match self.mode { CallMode::Everything => Call::Request { direct: false }, CallMode::Addressed => Call::Ask, CallMode::WakeWord => Call::Ignore, } } } #[cfg(test)] mod tests { use super::*; const A: u64 = 1; const B: u64 = 2; fn s() -> CallSettings { CallSettings::default() } #[test] fn a_wake_word_with_nothing_else_is_told_apart() { let c = s(); assert!(c.wake_word_only("자비스,")); assert!(c.wake_word_only("자비즈?")); assert!(!c.wake_word_only("자비스, 지금 몇 시야?")); assert!(!c.wake_word_only("서비스")); assert!(!c.wake_word_only("")); } #[test] fn exact_and_near_wake_words_call_but_a_different_word_does_not() { let c = s(); assert_eq!(c.judge(A, "자비스, 오늘 날씨 어때?"), Call::Request { direct: true }); assert_eq!(c.judge(A, "자비즈 날씨 알려 줘"), Call::Request { direct: true }); assert_eq!(c.judge(A, "오늘 날씨 어때 자비스"), Call::Request { direct: true }); assert_eq!(c.judge(A, "서비스 센터 몇 시에 열어?"), Call::Ignore); assert_eq!(c.judge(A, "오늘 날씨 어때?"), Call::Ignore); } #[test] fn latin_wake_words_ignore_case_spacing_and_accents() { let c = CallSettings { wake_words: vec!["Jarvis".into()], ..s() }; assert_eq!(c.judge(A, "hey JARVIS, what's up"), Call::Request { direct: true }); assert_eq!(c.judge(A, "Jervis, lights on"), Call::Request { direct: true }); assert_eq!(c.judge(A, "Jär vis?"), Call::Request { direct: true }); assert_eq!(c.judge(A, "the service is down"), Call::Ignore); } #[test] fn similarity_zero_needs_the_exact_word() { let c = CallSettings { similarity: 0.0, ..s() }; assert_eq!(c.judge(A, "자비즈 날씨"), Call::Ignore); assert_eq!(c.judge(A, "자비스 날씨"), Call::Request { direct: true }); } #[test] fn stop_needs_the_wake_word_and_little_else() { let c = s(); assert_eq!(c.judge(A, "자비스, 멈춰!"), Call::Stop); assert_eq!(c.judge(A, "자비스 그만해"), Call::Stop); assert_eq!(c.judge(A, "자비스 멈춰 줘"), Call::Stop); assert_eq!(c.judge(A, "멈춰"), Call::Ignore); assert_eq!(c.judge(A, "자비스 그만 얘기하고 날씨 알려 줘"), Call::Request { direct: true }); } #[test] fn empty_and_punctuation_only_text_is_ignored() { let c = CallSettings { mode: CallMode::Everything, ..s() }; assert_eq!(c.judge(A, ""), Call::Ignore); assert_eq!(c.judge(A, " ... ?! "), Call::Ignore); } #[test] fn modes_decide_utterances_without_a_wake_word() { let every = CallSettings { mode: CallMode::Everything, ..s() }; assert_eq!(every.judge(A, "날씨 어때"), Call::Request { direct: false }); let addressed = CallSettings { mode: CallMode::Addressed, ..s() }; assert_eq!(addressed.judge(A, "날씨 어때"), Call::Ask); assert_eq!(addressed.judge(A, "자비스 날씨 어때"), Call::Request { direct: true }); } #[test] fn designated_switches_combine_as_the_design_table_says() { let base = CallSettings { designated: [A].into(), ..s() }; // only on, no-wake off: designated people answered only when called. let c = CallSettings { designated_only: true, ..base.clone() }; assert_eq!(c.judge(A, "자비스 날씨"), Call::Request { direct: true }); assert_eq!(c.judge(A, "날씨"), Call::Ignore); assert_eq!(c.judge(B, "자비스 날씨"), Call::Ignore); assert_eq!(c.judge(B, "자비스 멈춰"), Call::Ignore); // only on, no-wake on: designated people only, without a wake word. let c = CallSettings { designated_only: true, designated_no_wake_word: true, ..base.clone() }; assert_eq!(c.judge(A, "날씨"), Call::Request { direct: false }); assert_eq!(c.judge(B, "자비스 날씨"), Call::Ignore); // only off, no-wake on: anyone by wake word, designated people without. let c = CallSettings { designated_no_wake_word: true, ..base.clone() }; assert_eq!(c.judge(A, "날씨"), Call::Request { direct: false }); assert_eq!(c.judge(B, "날씨"), Call::Ignore); assert_eq!(c.judge(B, "자비스 날씨"), Call::Request { direct: true }); // both off (default): anyone, by wake word only. assert_eq!(base.judge(A, "날씨"), Call::Ignore); assert_eq!(base.judge(B, "자비스 날씨"), Call::Request { direct: true }); } #[test] fn several_wake_words_all_count() { let c = CallSettings { wake_words: vec!["자비스".into(), "javis".into()], ..s() }; assert_eq!(c.judge(A, "javis 날씨"), Call::Request { direct: true }); assert_eq!(c.judge(A, "javis stop"), Call::Stop); } }