Skip to content

fix: automatic search stops grabbing the wrong book (stricter title and author matching) - #459

Merged
kikootwo merged 6 commits into
mainfrom
fix/223-auto-search-match-gates
Oct 27, 2026
Merged

kikootwo merged 6 commits into
mainfrom
fix/223-auto-search-match-gates

Conversation

@kikootwo

@kikootwo kikootwo commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Closes #223
Related: #330 (series position from Audible; stays open)

What changed

Automatic search (audiobooks and ebooks, requireAuthor: true) gets four new reject gates and two scoring fixes in scoreMatch. The 50/50 threshold, size scoring (#318 baseline), format, seeders and bonuses are unchanged.

  • A one-word title must start a name element. For a title like It, Dune or The Martian, at least one occurrence of the word in the release must be the first word, follow the author, follow a number or volume token (Stormlight Archive 3 Oathbringer, Discworld.04.Mort), or follow a separator. The author counts in any form the author check accepts: full name, glued (leechild), surname alone or surname first (Le Guin, Herbert Frank), collapsed initials (JRR Tolkien), with a possessive. Separators are :, ], ), }, a dash with spaces, . and _-_; an unspaced -, . or _ counts only when the name also uses another word delimiter, so Stephen-King-You-Like-It-Darker and Isaac.Asimov.Second.Foundation fail while Andy_Weir-The_Martian passes. Stop words the request itself has before the word are skipped (the for "The Martian"); others are not, so The Getaway Car fails for "Getaway". Nothing after the word is read. The check also applies when the title score already found a complete match, so Children of Dune, Second Foundation and The Fall of Hyperion no longer match "Dune", "Foundation" and "Hyperion". A release that passes is scored as before. Titles with a digit (1Q84) and CJK or Thai titles are exempt.
  • Numbers in the title are required. Every number in the required part of the title must be in the release. Coverage now reads 01 as 1, the English words one to twenty as digits, and t01, tome2, vol3, book4, bk5 as their number. Extra numbers in the release (years, bitrates) never count against it. A bare number right before a . , - or : subtitle split is the series position, not a required number: Die Tribute von Panem - Tödliche Spiele matches "Die Tribute von Panem 1. Tödliche Spiele".
  • Author names match as whole words. Andy Weir no longer matches "Weird Candy", and Lee Child no longer matches "Children". A possessive or plural (Robert Ludlum's, Tom.Clancys), digits touching the name (King2017) and the name glued together (leechild) still match. CJK and Thai names keep substring matching.
  • A different volume is rejected. When the request names one series position ((book 1), #12, or a split number as above) and the release names only other positions, the release is rejected. Explicit markers (T03, Book 2, #11) are read right after the title or series name. Bare numbers are read right after the series name that comes before the requested position, and after a word of the request's subtitle, so Divergent Trilogy 2 - Insurgent, Twilight Saga 2 and Wool Silo 3 no longer tie or beat book 1. A number followed by a unit (64 kbps, 2 CD, 29 Hours, 2 Discs) and 4-digit years are not read, and a glued v2 (often a re-release tag) is not a volume. A range is a box set: Harry Potter Book 1-7 passes for Book 2. Discworld 08 - City Watch Book 1 - Guards! Guards! still matches "Guards! Guards! (Discworld, Book 8)". This is the title-only part of Automatic search can grab the wrong book in a series #330.
  • A colon subtitle counts when it agrees with the request. Deep Down: A Reacher Story is a complete match for "Deep Down (A Jack Reacher short story)". Volume words and numbers do not count as agreement, and a subtitle with a number the request lacks never agrees, so Mistborn: Mistborn 2 and Dune: Book Two get no complete-title credit for a Book 1 request.
  • Initials earn author points. JD Robb for "J D Robb" now gets the full 15, not partial fuzzy credit.
  • New module src/lib/utils/match-gates.ts (303 lines). ranking-algorithm.ts gets shorter (1244 to 1201 lines).
  • Docs: new documentation/phase3/match-gates.md; documentation/phase3/ranking-algorithm.md and TABLEOFCONTENTS.md point to it.

Interactive search still lists every result: no gate rejects there. Scores and order do change through the colon-subtitle rule, initials credit, whole-word author credit and number folding (Ernest Cline - Ready Player 1 for "Ready Player One" 0 to 41.1; Naked in Death by JD Robb 50 to 60).

Why

#223 asked for a configurable threshold. A report in #223 showed that runtime lookups worked and the failures came from the title and author match, in two kinds: right books scoring under 50 (a colon subtitle, initials), and wrong books scoring over 50 for short titles (It grabbed You Like It Darker, Getaway grabbed a MatchUp anthology), because a full author match plus format, size and seeders carried them past the bar. A second report in #223 added two wrong-volume grabs from a French library. A lower threshold would grab more wrong books, so this fixes the matching and keeps the threshold.

Scores (matchScore / total, automatic mode)

Case Request Release Inputs main this PR
F1 It You Like It Darker by Stephen King [ENG / M4B] 1.5 GB, NZB 17.6 / 51.0 grabbed 0 / 33.4
F2 It It Grows on You by Stephen King [ENG / M4B] 1.5 GB, NZB 17.9 / 51.3 grabbed 17.9 / 51.3 (let through, as main)
F3 Getaway The Getaway Car - MatchUp by Lee Child [ENG / M4B] (constructed) 800 MB, NZB 28.2 / 68.2 grabbed 0 / 40.0
F4 Tom Clancy's Op-Center #12: War of Eagles Tom Clancy's Op-Center 11 - Call to Treason [ENG / M4B] (constructed) 500 MB, 30 seeders 44.0 / 73.3 grabbed 0 / 29.4
F4b same Tom Clancy's Op-Center #11: Call to Treason by Tom Clancy [ENG / M4B] (constructed) 500 MB, 30 seeders 39.4 / 68.8 grabbed 0 / 29.4
F5 Le problème à trois corps (book 1) Le.Probleme.a.Trois.Corps.T2.La.Foret.Sombre.Liu.Cixin.VFF.[M4B.128kbs]-NOTAG 900 MB, 20 seeders 37.5 / 70.4 grabbed 0 / 32.9
F6 Dungeon Crawler Carl (book 1) Matt Dinniman - Dungeon Crawler Carl, T03 Le Livre de recettes… 900 MB, 20 seeders 60 / 92.9 grabbed 0 / 32.9
F7 Hail (Andy Weir) Weird Candy Hail by Rando [M4B] (constructed) 900 MB, 60 seeders 16.4 / 52.1 grabbed 0 / 35.7
F7b The Fleet (Lee Child) Children of the Fleet by Orson Scott Card [M4B] (constructed) 900 MB, 60 seeders 18.8 / 54.5 grabbed 0 / 35.7
wrong It Stephen-King-You-Like-It-Darker-ENG-M4B (constructed) 1.5 GB, NZB 17.8 / 51.2 grabbed 0 / 33.4
wrong Dune Frank Herbert - Children of Dune [M4B] (constructed) 600 MB, NZB 60 / 100 grabbed 0 / 40.0
wrong Divergent (Divergent Trilogy, Book 1) Veronica Roth - Divergent Trilogy 2 - Insurgent [M4B] (constructed) 600 MB, NZB 42.4 / 82.4 grabbed 0 / 40.0
right It Stephen King - It (Unabridged) [M4B] 2.6 GB, 60 seeders 18.5 / 53.7 18.5 / 53.7
right It It by Stephen King [ENG / M4B] 2.6 GB, 60 seeders 60 / 95.2 60 / 95.2
right The Martian Andy.Weir.The.Martian.Unabridged.M4B 600 MB, 100 seeders 35.8 / 72.8 35.8 / 72.8
right Getaway leechild-getaway-mp3 600 MB, 100 seeders 32.2 / 63.3 38.5 / 69.5
right Deep Down (A Jack Reacher short story) Deep Down: A Reacher Story by Lee Child [ENG / MP3] 60 MB, 20 seeders 41.3 / 68.2 60 / 86.9
right Naked in Death (J D Robb) Naked in Death by JD Robb [ENG / M4B] 500 MB, 30 seeders 50.0 / 81.4 60 / 91.4
right Primal Hunter 1 Primal.Hunter.01.Zogarth.2024.FR.[MP3.128.KBPS]-NOTAG 900 MB, 10 seeders 0 / 19.2 (rejected) 33.7 / 52.9
right Tom Clancy's Op-Center #12: War of Eagles Tom Clancy - Op-Center 12 - War of Eagles [M4B] 700 MB, 30 seeders 55.0 / 88.5 55.0 / 88.5
right Dungeon Crawler Carl (book 1) Matt Dinniman - Dungeon Crawler Carl, T01 - 2024 [M4B] - SGFx 900 MB, 20 seeders 60 / 92.9 60 / 92.9
right Guards! Guards! (Discworld, Book 8) Terry Pratchett - Discworld 08 - City Watch Book 1 - Guards! Guards! [MP3] 600 MB, 100 seeders 40.4 / 71.4 40.4 / 71.4
right Chamber of Secrets (Harry Potter, Book 2) J.K. Rowling - Harry Potter Book 1-7 - Philosophers Stone, Chamber of Secrets, Prisoner of Azkaban 600 MB, NZB 60 / 91.0 60 / 91.0
right Die Tribute von Panem 1. Tödliche Spiele Suzanne Collins - Die Tribute von Panem - Tödliche Spiele (ungekürzt) [MP3] (de) 600 MB, NZB 45.3 / 79.3 45.3 / 79.3
right Artemis Andy Weir - Artemis (Unabridged) [MP3 64kbps] 420 MB, 60 seeders 60 / 86.4 60 / 86.4

Runtimes (min): It 2683, Getaway 90, Deep Down 60, Op-Center 720, Le problème 900, Dungeon Crawler Carl 800, Hail and The Fleet 800, Naked in Death 600, Primal Hunter 1500, Artemis 540, others 600. "NZB" means no seeders field, which earns the full 15.

Races (two or three results in one search, what automatic search downloads): the right book now wins in every case tested. Veronica.Roth.Divergent.Unabridged.M4B (8 seeders) beats Divergent Trilogy 2 - Insurgent (40 seeders), Frank.Herbert.Dune.64kbps.MP3 beats Children of Dune and God Emperor of Dune, and Isaac.Asimov.Foundation.Unabridged.MP3 beats Second Foundation; main downloads the wrong book in all three.

Evidence

Unit tests
  • tests/utils/ranking-right-books-223.test.ts with fixtures/ranking-right-books-223.json: 193 right-book release names (one-word titles in scene, dotted, dashed and bracket shapes, ebooks, de/fr/es/it, Cyrillic, Greek, Korean, CJK, series and box sets, initials and co-authors) that clear 50 on main. All clear 50 here except 5 listed exceptions (see Risk).
  • tests/utils/ranking-match-gates.test.ts runs every case through rankTorrents / rankEbookTorrents: 42 wrong books (match 0, total under 50), including the sequel, dash-only and title-ending rows; 13 releases the one-word check lets through, pinned to their main score; 74 right books that must clear 50 on both main and this branch (a series number right before a one-word title included), plus 7 ebook rows and one interactive-mode row; 10 races where the right book must be the one downloaded; 3 rows the volume check must not read as a position (v2, 29 Hours, 2 Discs), pinned to their main score; and 8 rows for right books that scored low on main and colon subtitles that must not gain the complete-title score.
  • tests/utils/ranking-oracle-223.test.ts replays all 176 (release, request, mode, language) pairs the existing ranking suites score, against the matchScore each had before this change. All are unchanged except 7 initials rows, which rise (Olive Juice by T J Klune 51 to 60, Olive Juice Book 1 T J Klune 33.7 to 42, A Game of Thrones by George RR Martin 54.3 to 60, and four more to 60).
  • tests/processors/search-indexers-non-latin.test.ts: a request for "It" whose only result is You Like It Darker (NZB) goes back to awaiting_search and queues no download.
  • With ranking-algorithm.ts from main in place, 54 of the new tests fail, all on an assertion: 40 wrong-book rows, 4 races, 4 low-scoring right books, the 5 listed exceptions (which pass on main) and the processor test. The 2 number-word wrong-book rows (One, Twelve), every must-pass row and every corpus row pass on both.
  • No existing test expectation changed.

Checks

  • vitest related for ranking-algorithm.ts and match-gates.ts: PASS, 78 files, 1691/1691
  • Ranking suites plus the new tests (ranking-algorithm, ranking-non-latin, ranking-match-gates, ranking-oracle-223, ranking-right-books-223, match-gates, match-normalize, search-indexers-non-latin): PASS, 808/808; the new wrong-book rows fail before the fix
  • Type check and lint: PASS (tsc --noEmit clean; ESLint finds nothing new in the changed files: 1 warning, already on main, which has 2 in the same files)
  • Full unit suite: PR Tests (CI)

Risk and rollback

Automatic search only. Right books that can now be rejected, so a request waits for a better release. In the 193-row right-book corpus, 5 fail; each falls under one of these classes, which also cover shapes outside the corpus:

  • Volume conflict: competing numbering (The Chronicles of Narnia Book 1 - The Magician's Nephew for Book 6, The Witcher Book 1 - Blood of Elves for Book 3), and a sub-series number right after the title (Guards! Guards! - Book 1 of the City Watch for "(Discworld, Book 8)"). A bare number after the series name meets the same numbering problem: C.S. Lewis - Chronicles of Narnia 1 - The Lion, the Witch and the Wardrobe fails for "The Lion, the Witch and the Wardrobe (The Chronicles of Narnia, Book 2)". Half of a split book (The Way of Kings Vol 2 for "(Book 1)") also fails.
  • One-word titles: a word other than the author or a separator right before the title fails (Frank Herbert Collection Dune, Audiobook Dune by Frank Herbert, Sebastian Fitzek - Thriller Das Paket).
  • Author names: a nickname no longer matches by substring (Ken Follett vs Kenneth Follett), and declined forms fail the gate (Стивена Кинга).
  • Numbers: a Roman numeral (He Who Fights with Monsters I for "… 1"), a number spelled out above twenty, or a release that leaves out a required number (Tom Clancy's Op-Center - War of Eagles for "Fix request button disable logic for status states #12") fails. A box set named by its book count (Divergent 4 Book Collection for "Divergent (Book 1)") is read as volume 4 and fails.

Still let through, scored as on main (the one-word check reads only the left side):

  • A longer title that starts with the word: It Grows on You (F2), It Ends With Us and It Ends Here for "It"; Dune Messiah for "Dune"; Mistborn Secret History; The Martian Chronicles. Also Chapterhouse: Dune, after its colon.
  • A sequel after a series word the request does not carry (Uglies Series 2 - Pretties for "Uglies (Uglies, Book 1)", Skyward Flight 2), a number word after a volume word (Dune: Book Two), and numbered sequels of a title with no position in the request (Frank Herbert - Dune 2).
  • A bare number right after the title alone, when the request's position is only in brackets (Le.Probleme.a.Trois.Corps.2.La.Foret.Sombre…, Dungeon Crawler Carl 03 - …, Dungeon Crawler Carl Book Three). Automatic search can grab the wrong book in a series #330 covers these.
  • An omnibus (Tom Clancy's Op-Center 01-12) still passes.
  • When the request writes its number as 12: without #, a sibling that leaves the number out passes (Tom Clancy's Op-Center: Out of the Ashes for "Tom Clancy's Op-Center 12: War of Eagles", He Who Fights with Monsters II for "He Who Fights with Monsters 1: A LitRPG Adventure").
  • War of Eagles by Jeff Rovin for "Tom Clancy's Op-Center Fix request button disable logic for status states #12: War of Eagles" stays rejected: Audible credits only Tom Clancy. Interactive search finds it.
  • Apostrophes (L'intruse vs L.Intruse) and request subtitle words after . or - are not handled here.

Of 83 wrong-book release names probed, main grabs 80 and this PR 33 (all 33 scored as on main).

Rollback: revert this PR. Nothing is stored; no data needs undoing.

Release note

🤖 Generated with Claude Code

kikootwo and others added 6 commits October 27, 2026 00:15
…title words

Automatic search now rejects a release when a one-word title does not stand
alone, a number in the required title is missing, the author only appears
inside other words, or the release names a different series position right
after the title. A colon subtitle that agrees with the request, and author
initials, now earn full credit. Interactive search keeps listing every result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…after the series name

- G4b now only requires the title word to start a name element: first, after
  an author form G3 accepts, or after a separator. Nothing after the word is
  read, and the check also covers a Stage 2 complete title the word only ends
  (Children of Dune for "Dune"). The complete-title 45 from G4b is gone.
- An unspaced -, . or _ separates only when the name also uses another
  delimiter.
- G4c reads a bare number after the series name before the requested position
  and after a request subtitle word, so Divergent Trilogy 2 no longer ties
  Divergent (Divergent Trilogy, Book 1). Ranges (Book 1-7) are box sets.
- G1 ignores volume words and rejects a subtitle naming another number.
- G4a treats a bare number before a ". ", " - " or ":" split as the series
  position. bk joins the shared volume word list.
- Adds the right-book corpus test: 193 names that clear 50 on main, 5 listed
  exceptions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d unit words are not volumes

- G4b: a number or volume token right before the word counts as a left
  boundary (`Stormlight Archive 3 Oathbringer`, `Discworld.04.Mort`).
  `Book 1 It Grows on You` moves to the let-through table at main's score.
- G4c: positions leave out `v`, so a glued `v2` is not read as volume 2.
- G4c: `hours`, `discs`, `parts`, `tracks`, `books` count as unit words
  after a bare number.
- Tests: four must-pass rows, the Silo 1 Wool race, and three rows pinned
  to main's score (`v2`, `29 Hours`, `2 Discs`). Docs updated.

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

Development

Successfully merging this pull request may close these issues.

Make auto-download quality score threshold configurable (currently hardcoded at 50/100)

1 participant