//! Deciding which of a provider's answers is the title you actually have. //! //! A release-named library does not hand you clean titles. `[SubsGroup] Shingeki //! no Kyojin S3` and `Attack on Titan (2013)` are the same show, and the //! provider knows it under four names in three scripts. So matching is scoring, //! not lookup, and the two things that make it work are: //! //! * **Every alias counts.** A candidate is scored on its best name, not its //! canonical one. AniList's romaji, English, native and synonym lists exist //! precisely because none of them is *the* title. //! * **A bad match is worse than none.** Putting the poster of a different show //! on a title is a mistake nobody can see is a mistake — it just looks like //! the library is wrong. So the floor is high, and anything under it is a //! cached miss rather than the best of a bad set. //! //! The similarity itself is Sørensen–Dice over character bigrams. It is not the //! most sophisticated measure available, but it has the properties that matter //! here: it is order-insensitive enough to survive `Bebop, Cowboy`, length-aware //! enough not to match `Gintama` to `Gintama°: Enchousen`, and it needs no //! tuning. use pstr_core::library::{TitleKind, title_key}; use pstr_core::metadata::TitleMetadata; /// A candidate's score has to clear this to be used. /// /// Chosen from what the failure modes cost rather than from a curve: at 0.72 a /// missing subtitle or a swapped season number still matches, while two /// different shows sharing a franchise name — the common near-miss in an anime /// library — do not. See the tests, which pin both sides. pub const MATCH_FLOOR: f32 = 0.72; /// The title being looked up. #[derive(Debug, Clone)] pub struct Query { /// The title as the library has it, already stripped of release tags by /// [`pstr_core::naming`]. pub name: String, pub year: Option, pub kind: TitleKind, /// Whether the library *knows* what kind of thing this is. /// /// The mirror of [`Candidate::kind_known`], and it exists for the same /// reason. A folder holding the three `Heaven's Feel` films is a `Series` /// to [`pstr_core::library`] only because it holds three files — the films /// themselves are numbered nothing — and scoring that guess against the /// provider's (correct) `Film` costs the right answer the 0.05 that puts it /// under the floor. pub kind_known: bool, } impl Query { pub fn new(name: impl Into, year: Option, kind: TitleKind) -> Self { Self { name: name.into(), year, kind, kind_known: true, } } /// Say that [`Query::kind`] was inferred rather than stated — see /// [`Query::kind_known`]. pub fn with_guessed_kind(mut self) -> Self { self.kind_known = false; self } } /// One of a provider's answers, with every name it is known by. #[derive(Debug, Clone)] pub struct Candidate { pub metadata: TitleMetadata, /// Romaji, English, native, synonyms — whatever the provider had. The /// canonical name is included by the providers that build these. pub aliases: Vec, /// Whether the provider actually stated what kind of thing this is. /// /// [`TitleMetadata::kind`] has no "unknown", because a badge has to say /// something — but scoring must not read that fallback as a fact. AniList /// leaves `format` null on anything unaired, and treating that as "film" /// then *penalising* it against a series is how an announced-but-unreleased /// entry loses to a worse match. Absence of evidence, not evidence. pub kind_known: bool, } /// How well `candidate` answers `query`, from 0 to 1. pub fn score(query: &Query, candidate: &Candidate) -> f32 { let wanted = title_key(&query.name); if wanted.is_empty() { return 0.0; } let best = candidate .aliases .iter() .map(|alias| similarity(&wanted, &title_key(alias))) .fold(0.0_f32, f32::max); // Adjustments, not tie-breakers: they move a score across the floor only // when it was already close to it. let mut score = best; match (query.year, candidate.metadata.year) { // Same year is strong evidence for two titles that already read alike. (Some(wanted), Some(found)) if wanted == found => score += 0.06, // A year apart is normal — a season airing across New Year, a provider // dating by première rather than release. Further apart is not. (Some(wanted), Some(found)) if wanted.abs_diff(found) > 1 => score -= 0.15, _ => {} } if query.kind_known && candidate.kind_known && query.kind != candidate.metadata.kind { // A film and a series of the same name are usually genuinely related — // an adaptation, a compilation — so this is a nudge, not a veto. And // only when both sides actually said; see `Candidate::kind_known` and // `Query::kind_known`. score -= 0.05; } score.clamp(0.0, 1.0) } /// The best answer above [`MATCH_FLOOR`], if there is one. /// /// Ties go to whichever the provider listed first, and that is load-bearing /// rather than arbitrary. Franchises share synonyms — every *Evangelion* entry /// on AniList carries `EVANGELION:30+;`, so a library folder named plainly /// `Evangelion` scores several of them identically — and when the text cannot /// separate them, the provider's own relevance ordering is the only evidence /// left. Taking the last one instead, which is what `Iterator::max_by` does, /// picks the *least* relevant of the tied set: it is how a folder of the 1995 /// series came back matched to a 2026 anniversary screening. pub fn best(query: &Query, candidates: Vec) -> Option { let mut best: Option<(TitleMetadata, f32)> = None; for candidate in candidates { let score = score(query, &candidate); // Strictly greater: an equal score leaves the earlier candidate in // place, which is what keeps the provider's ordering as the tie-break. if best.as_ref().is_none_or(|(_, best)| score > *best) { best = Some((candidate.metadata, score)); } } let (metadata, score) = best?; if score < MATCH_FLOOR { tracing::debug!( "no match for {:?}: best candidate scored {score:.2}, floor is {MATCH_FLOOR}", query.name ); return None; } Some(metadata) } /// Sørensen–Dice over character bigrams, on already-normalised strings. /// /// Identical strings are 1.0 and a one-character string is compared directly, /// since it has no bigrams to compare. fn similarity(left: &str, right: &str) -> f32 { if left == right { return 1.0; } if left.is_empty() || right.is_empty() { return 0.0; } let left: Vec = left.chars().collect(); let right: Vec = right.chars().collect(); if left.len() < 2 || right.len() < 2 { return 0.0; } // Multiset intersection: a bigram appearing twice on the left and once on // the right counts once, which is what keeps `aaaa` from matching `aa`. let mut theirs: Vec<[char; 2]> = right.windows(2).map(|pair| [pair[0], pair[1]]).collect(); let mut shared = 0usize; for pair in left.windows(2) { let pair = [pair[0], pair[1]]; if let Some(position) = theirs.iter().position(|other| *other == pair) { theirs.swap_remove(position); shared += 1; } } let total = (left.len() - 1) + (right.len() - 1); (2.0 * shared as f32) / total as f32 } #[cfg(test)] mod tests { use super::*; use pstr_core::metadata::ProviderId; fn candidate(name: &str, aliases: &[&str], year: Option, kind: TitleKind) -> Candidate { Candidate { metadata: TitleMetadata { provider: ProviderId::AniList, remote_id: "1".into(), name: name.into(), original_name: None, overview: None, year, kind, poster_url: None, backdrop_url: None, rating: None, genres: Vec::new(), episodes: None, url: None, }, aliases: std::iter::once(name) .chain(aliases.iter().copied()) .map(str::to_string) .collect(), kind_known: true, } } #[test] fn an_identical_title_scores_perfectly() { let query = Query::new("Cowboy Bebop", None, TitleKind::Series); let candidate = candidate("Cowboy Bebop", &[], None, TitleKind::Series); assert!(score(&query, &candidate) >= 1.0); } /// The case the alias list exists for: the library has the romaji name and /// the provider's canonical name is the English one, or the reverse. #[test] fn a_match_on_an_alias_is_as_good_as_one_on_the_name() { let query = Query::new("Shingeki no Kyojin", None, TitleKind::Series); let candidate = candidate( "Attack on Titan", &["Shingeki no Kyojin"], Some(2013), TitleKind::Series, ); assert!(score(&query, &candidate) >= MATCH_FLOOR); } /// Punctuation and case are the parser's business, not the matcher's — and /// `title_key` has already removed them. #[test] fn punctuation_and_case_do_not_affect_the_score() { let query = Query::new("FULLMETAL ALCHEMIST: BROTHERHOOD", None, TitleKind::Series); let candidate = candidate( "Fullmetal Alchemist: Brotherhood", &[], None, TitleKind::Series, ); assert!(score(&query, &candidate) >= 1.0); } /// The mistake worth preventing: two entries in one franchise, where the /// wrong poster looks like a working feature rather than a bug. #[test] fn a_different_entry_in_the_same_franchise_does_not_match() { let query = Query::new("Gintama", None, TitleKind::Series); let candidate = candidate("Gintama°: Enchousen", &[], None, TitleKind::Series); assert!( score(&query, &candidate) < MATCH_FLOOR, "scored {}", score(&query, &candidate) ); } #[test] fn a_wholly_unrelated_title_does_not_match() { let query = Query::new("Cowboy Bebop", None, TitleKind::Series); let candidate = candidate("Neon Genesis Evangelion", &[], None, TitleKind::Series); assert!(score(&query, &candidate) < MATCH_FLOOR); } /// A decade apart is a different work with a reused name — a remake, or a /// coincidence. One year apart is the same work dated differently. #[test] fn a_distant_year_is_penalised_and_a_near_one_is_not() { let query = Query::new("Bebop", Some(1998), TitleKind::Series); let near = candidate("Bebop", &[], Some(1999), TitleKind::Series); let far = candidate("Bebop", &[], Some(2021), TitleKind::Series); assert!(score(&query, &near) > score(&query, &far)); assert!(score(&query, &near) >= MATCH_FLOOR); } #[test] fn the_best_candidate_wins_and_a_weak_field_yields_nothing() { let query = Query::new("Cowboy Bebop", Some(1998), TitleKind::Series); let found = best( &query, vec![ candidate( "Neon Genesis Evangelion", &[], Some(1995), TitleKind::Series, ), candidate("Cowboy Bebop", &[], Some(1998), TitleKind::Series), ], ); assert_eq!(found.map(|found| found.name), Some("Cowboy Bebop".into())); assert!( best( &query, vec![candidate( "Serial Experiments Lain", &[], None, TitleKind::Series )] ) .is_none() ); assert!(best(&query, Vec::new()).is_none()); } /// Repeated bigrams must not inflate a score: without multiset counting, /// a short repetitive name matches a long repetitive one perfectly. #[test] fn repeated_bigrams_are_counted_once_each() { assert!(similarity("aaaa", "aa") < 1.0); } /// Measured against the real thing: searching AniList for `Evangelion` /// returns several entries that all carry the synonym `EVANGELION:30+;`, /// so they score identically and nothing in the text can separate them. /// The provider's own ordering is then the only evidence there is, and /// taking the last of the tied set — which is what `max_by` does — picked /// a 2026 anniversary screening over the series the folder was named for. #[test] fn tied_candidates_are_settled_by_the_providers_own_ordering() { let query = Query::new("Evangelion", None, TitleKind::Series); let tied = vec![ candidate( "Evangelion (Shinsaku Series)", &["EVANGELION:30+;"], None, TitleKind::Series, ), candidate( "Evangelion 30th Anniversary Special Screening", &["EVANGELION:30+;"], Some(2026), TitleKind::Series, ), ]; // Both clear the floor on the shared synonym; the first one listed wins. assert!(score(&query, &tied[0]) >= MATCH_FLOOR); assert_eq!( best(&query, tied).map(|found| found.name), Some("Evangelion (Shinsaku Series)".into()) ); } /// The other half of the Evangelion mismatch, and the more subtle half. /// /// AniList leaves `format` null on anything unaired. [`TitleMetadata::kind`] /// has to say *something*, so it falls back to `Film` — and scoring must not /// then read that fallback as the provider having said "film" and dock the /// candidate for it. Doing so cost the top-ranked entry 0.05 and handed the /// match to a 2026 anniversary screening that happened to have a format. #[test] fn an_unstated_kind_is_not_penalised_the_way_a_wrong_one_is() { let query = Query::new("Evangelion", None, TitleKind::Series); let mut unstated = candidate("Evangelion", &[], None, TitleKind::Film); unstated.kind_known = false; let stated = candidate("Evangelion", &[], None, TitleKind::Film); assert!(score(&query, &unstated) > score(&query, &stated)); assert_eq!(score(&query, &unstated), 1.0); // And the same in reverse: a library that guessed its own kind has // nothing to disagree with the provider about. let guessed = query.clone().with_guessed_kind(); assert_eq!(score(&guessed, &stated), 1.0); } /// **The apostrophe case, both shapes of it.** A folder cannot carry the /// apostrophe of `Fate/stay night [Heaven's Feel]`, so it is called /// `Heavens Feel` — and until [`title_key`] closed the apostrophe up rather /// than splitting on it, the provider's own entry scored under the floor. /// /// One film per folder matches outright. The trilogy in a single folder is /// the harder half: the library calls three files a series where the /// provider calls each of them a film, so it clears the floor by a hair /// with that mismatch subtracted. #[test] fn a_title_that_lost_its_apostrophe_matches_the_entry_that_kept_one() { let film = candidate( "Fate/stay night [Heaven's Feel] I. presage flower", &[], Some(2017), TitleKind::Film, ); let alone = Query::new( "Fate stay night Heavens Feel I Presage Flower", Some(2017), TitleKind::Film, ); assert!(score(&alone, &film) >= 1.0); // Three films in one folder: a `Series` only because there are three of // them, so the kind is a guess and costs the film entry nothing. let trilogy = Query::new("Fate stay night Heavens Feel", None, TitleKind::Series).with_guessed_kind(); assert!( score(&trilogy, &film) >= MATCH_FLOOR, "scored {}", score(&trilogy, &film) ); } /// The tie-break must not override the score: a later candidate that /// genuinely matches better still wins. #[test] fn a_better_later_candidate_still_beats_an_earlier_weaker_one() { let query = Query::new("Cowboy Bebop", None, TitleKind::Series); let found = best( &query, vec![ candidate("Cowboy Bebop: The Movie", &[], None, TitleKind::Film), candidate("Cowboy Bebop", &[], None, TitleKind::Series), ], ); assert_eq!(found.map(|found| found.name), Some("Cowboy Bebop".into())); } }