Skip to content

fix: search and ranking handle titles with apostrophes - #469

Merged
kikootwo merged 5 commits into
mainfrom
fix/316-apostrophe-search
Oct 27, 2026
Merged

kikootwo merged 5 commits into
mainfrom
fix/316-apostrophe-search

Conversation

@kikootwo

@kikootwo kikootwo commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Closes #316

What changed

  • Fallback search pass (src/lib/integrations/prowlarr.service.ts, query helpers in the new src/lib/integrations/prowlarr-query-variations.ts). searchWithVariations() still sends "title author" then "title". Only when none of those results names the title does it try more queries, each as "variation author" then "variation", and it stops at the first query whose results name the title. A result names the title when it holds 80% of the title's words before its subtitle. This is close to ranking's first word-coverage check, with apostrophes and numbers folded the same way, but it always uses English stop words, and a number's . also starts a subtitle there. The variations:
    1. The title with its apostrophes folded and other punctuation inside a word turned into a space: The Dungeon Anarchist's Cookbook becomes The Dungeon Anarchists Cookbook, L'intruse becomes L intruse, Op-Center becomes Op Center. Only sent when some word has punctuation inside it.
    2. The title without its subtitle: the text before the first :, or before . right after a number (Primal Hunter 1. Une aventure de LitRPG becomes Primal Hunter 1). Not sent when it has fewer than 3 letters and digits and no non-Latin letter (Re:Zero sends no Re; 三体 is still sent).
  • This includes the change from PR Fix Prowlarr searches for Audible titles with subtitles #304 by @connor2k (search again without the subtitle), re-implemented with a guard: a title that starts with : gives no subtitle-free query, so no empty query is sent. The split after a number's . is @Eyji's suggestion on that PR, and the subtitle-free idea also came from @thehaven in feat(search): 3-pass subtitle search and configurable preferred search language with score penalties #254.
  • Custom search terms are sent exactly as given, with no fallback: the admin's terms on a request (automatic and interactive search), and a title edited in interactive search, on a request, on both ebook routes, and with no request. For the last one, the modal now sends exactTitle: true to POST /api/audiobooks/search-torrents when the title differs from the book's own. Callers pass { exactTitle }.
  • A blank query is never sent: a blank title with an author sends the author once, and repeated queries (ignoring case) are skipped.
  • Ranking (src/lib/utils/match-normalize.ts): normalizeForMatching and foldForMatching now fold apostrophes. Straight and typographic apostrophes count as one; before an English ending (s t d m ll re ve) the apostrophe is dropped, anywhere else it becomes a space. So L'intruse matches L intruse and L.Intruse.
  • Release side of the fold (keepUnrequestedApostrophes, the first step of scoreMatch and of the fallback check): a release word with an apostrophe ending folds only when the request writes that word with one. Any other keeps its apostrophe, as ꞌ (U+A78C, a Latin letter), so it stays one word that matches no plain word, as on main. So "Ender's Game" matches Enders.Game and Ender's Game, while "The Titans" does not match The Titan's Curse. The author check (G3) accepts that kept ꞌs after a name, as it accepts 's.
  • Docs: documentation/phase3/prowlarr.md (fallback pass, which searches are exact, cost, Fixed Search fails for titles containing apostrophes; add a punctuation-stripped query variation #316), phase3/ranking-algorithm.md (apostrophe fold and its release side, other consumers, known limits, Fixed Ranking rejects the right release when the title has an apostrophe or a subtitle after ". " or " - " #466 apostrophe rows), phase3/match-gates.md.

Why

Indexer release names usually drop the apostrophe, so a search for "The Dungeon Anarchist's Cookbook" or "The Butcher's Masquerade" can return nothing while the same title without it finds the book. Even when such a release came back, ranking kept the apostrophe inside the word (anarchist's, ender's, l'intruse), so Anarchists, Enders.Game and L.Intruse failed word coverage and scored 0 in automatic and interactive search.

The fold is one-way on purpose. Folding both sides the same would make Lover's and Lovers one word, so a possessive title by the same author (The Titan's Curse) would clear automatic search for a request whose title has the plural ("The Titans").

This fixes the apostrophe rows of #466 (L.Intruse… for "L'intruse", Changer.L.Eau.Des.Fleurs…, Enders.Game… for "Ender's Game"). The subtitle rows of #466 (". " and " - " in the request title) are not changed here and stay open there.

Evidence

  • tests/integrations/prowlarr-search-variations.test.ts runs the real searchWithVariations() with search() stubbed. It covers:
    • no extra query when the first pass names the title, also when the release drops the apostrophe;
    • the stripped query after an empty first pass, stopping at the first query that finds the title, and the fallback after a first pass of other books;
    • the subtitle-free query for a colon and for a number's . , and the stripped subtitle-free query;
    • no Re query for Re:Zero, while a 2-character CJK base is still sent;
    • no fallback for Mr. Mercedes, for exact custom terms, or when every first-pass query failed;
    • no empty or repeated query for : The Book, : , '' and a blank title;
    • the fallback check: a possessive release does not name a plural title ("The Lovers", "Enders").
  • tests/utils/ranking-match-gates.test.ts:
    • The three Ranking rejects the right release when the title has an apostrophe or a subtitle after ". " or " - " #466 apostrophe rows, the two Search fails for titles containing apostrophes; add a punctuation-stripped query variation #316 titles and a curly-apostrophe request clear word coverage and reach 50 in automatic search, and score above 0 in interactive search.
    • Five possessive releases for a request without the apostrophe (The Lover's Dictionary for "The Lovers", The Titan's Curse for "The Titans", The Handmaid's Tale for "The Handmaids", The Husband's Secret for "The Husbands", Ender's Game for "Enders"), plus Ender’s Game for "Enders Game", score match 0 and total 40 in automatic search, as on main, and match 0 in interactive search. So do two curly possessives that main picked: The Lover’s Dictionary for "The Lover" and The Housemaid’s Secret for "The Housemaid".
    • The same possessive releases still clear 50 for a request with the apostrophe, and Stephen King's The Stand still counts the author.
  • tests/utils/match-normalize.test.ts: the fold table, the request words with an apostrophe ending, and the release side (a kept apostrophe survives every later normalization). foldForMatching and normalizeForMatching agree on apostrophe text.
  • tests/utils/bulk-import-keys.test.ts: apostrophe titles key as before (the existing all-ASCII key test also still passes). tests/integrations/audible-series-search-ranking.test.ts: series match share for apostrophe titles.
  • Caller tests check exactTitle for the processor, both ebook interactive routes, the audiobook search route (an edited title sends exactTitle: true), its hook and the modal.
  • Fails on main: with main's source (08dc816) and this branch's tests, 70 failed and 347 passed in 11 files. 56 fail on assertions. The other 14 are unit tests of the two new match-normalize helpers, which do not exist on main. On this branch, 417/417 pass.
  • Score scan, main against this branch, on the Make auto-download quality score threshold configurable (currently hardcoded at 50/100) #223 right-book corpus (193 rows) and oracle (176 rows): no oracle score changes. Two right-book rows rise (Harry Potter and the Philosophers Stone for "Harry Potter and the Philosopher's Stone", 93.1 and 91.2 to 100). Two Op-Center rows dip by 0.1 and 0.2 (86.9 to 86.8, 84.2 to 84.0) through fuzzy title similarity, still far above 50.

Checks

  • Unit tests for the changed code (vitest related on the changed source files, plus the new tests and the ranking suites): PASS, 115 files, 2293/2293
  • Ranking suites: ranking-algorithm, ranking-match-gates, ranking-non-latin, ranking-oracle-223, ranking-right-books-223, match-normalize: PASS
  • Type check and lint: PASS (tsc --noEmit clean; ESLint reports nothing new in the touched files compared with main, and the new file is clean)
  • No image build or E2E run: the change is in src/lib, route call sites, one hook and one modal call
  • Full unit suite: PR Tests (CI)

Risk and rollback

  • Extra indexer calls happen only on the fallback: after a first pass that returned nothing naming the title, for a title that has punctuation inside a word or a subtitle. At most 4 more queries per indexer group, and it stops at the first query that finds the title. Normal searches send the same 2 queries as before. Searches with custom terms or an edited interactive title never use the fallback.
  • Scores that rise, and for whom:
    • Requests whose title or author is written with an apostrophe. A release that drops it (Enders.Game, Anarchists, Philosophers), uses the other apostrophe form (curly for straight), or splits an elision (L.Intruse for "L'intruse", O Brien for "O'Brien") now matches. Such a request also matches the release word without the apostrophe when that is the plural (Lovers for "Lover's"), which needs the rest of the title to match too.
    • Elision on the release side only (L'Héritage for a request "Héritage", French): the release splits into l heritage, so interactive search now shows it (match 0 to 60); automatic search still scores it 0.
    • Requests without an apostrophe: no rise. A release possessive (The Titan's Curse) is never matched by a plural request word ("The Titans").
  • Scores that fall: none that change a decision in the corpus. The Op-Center rows above dip a fraction of a point. A curly possessive in a release now stays one word, like a straight one, where main split it in two. That takes two wrong books that main picked in automatic search to 0: The Lover’s Dictionary for "The Lover" (70.4) and The Housemaid’s Secret for "The Housemaid" (76.5), both by the requested author. Stephen King’s It for "It" moves from 60.3 to 60.0.
  • Known limits: a release that splits an English ending (Ender.s.Game) does not match Ender's, and a request written without the apostrophe ("Enders Game") does not match Ender’s Game, as on main.
  • Bulk Import grouping keys do not change: they already drop every character that is not a letter or digit.
  • Series search: apostrophe titles now match either spelling (enders game for "Ender's Game" was 0.5, now 1); other titles rank as before.
  • Rollback: revert this PR. Nothing is stored or migrated.

Release note

🤖 Generated with Claude Code

…ck query pass (#316)

Search tries the title without its apostrophes, then without its subtitle, only when the first pass finds nothing that names it (custom search terms are sent as given, and an empty query is never sent); ranking folds apostrophes so Enders.Game and L.Intruse match their titles.

Closes #316.

Co-authored-by: connor2k <connormiddleton@gmail.com>
Co-authored-by: Eyji <10639815+Eyji@users.noreply.github.com>
Co-authored-by: thehaven <420380+thehaven@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kikootwo and others added 4 commits October 27, 2026 03:10
… edited interactive titles are sent as given (#316)

Ranking folds a release word with an apostrophe ending only when the request
writes that word with one, so "The Lover's Dictionary" no longer matches a
request for "The Lovers". The Prowlarr fallback check uses the same rule.
A title edited in interactive search with no request is sent as given, and a
subtitle-free base under 3 letters and digits ("Re" from "Re:Zero") is not sent.

Co-authored-by: connor2k <connormiddleton@gmail.com>
Co-authored-by: Eyji <10639815+Eyji@users.noreply.github.com>
Co-authored-by: thehaven <420380+thehaven@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…phe (#316)

Co-authored-by: connor2k <connormiddleton@gmail.com>
Co-authored-by: Eyji <10639815+Eyji@users.noreply.github.com>
Co-authored-by: thehaven <420380+thehaven@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kikootwo
kikootwo marked this pull request as ready for review October 27, 2026 07:48
@kikootwo
kikootwo merged commit f182a0d into main Oct 27, 2026
1 check passed
@kikootwo
kikootwo deleted the fix/316-apostrophe-search branch October 27, 2026 07:51
kikootwo added a commit that referenced this pull request Oct 27, 2026
…from #469 (#470)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant