ReadMeABook/documentation/phase3/ranking-algorithm.md

Intelligent Ranking Algorithm

Status: ✅ Implemented

Evaluates and scores torrents to automatically select best audiobook download.

Scoring Criteria (100 points max)

1. Title/Author Match (50 pts max) - MOST IMPORTANT

Multi-Stage Matching:

Stage 1: Word Coverage Filter (MANDATORY)

• Extracts significant words from request (filters stop words: "the", "a", "an", "of", "on", "in", "at", "by", "for")
• Calculates coverage: % of request words found in torrent title
• Hard requirement: 80%+ coverage or automatic 0 score
• Example: "The Wild Robot on the Island" → ["wild", "robot", "island"]
  • "The Wild Robot" → ["wild", "robot"] → 2/3 = 67% → REJECTED
  • "The Wild Robot on the Island" → 3/3 = 100% → PASSES
• Prevents wrong series books from matching

Stage 2: Title Matching (0-35 pts)

• Only scored if Stage 1 passes
• Complete title match (followed by metadata: " by", " [", " -") → 35 pts
• Title is substring but continues with more words → fuzzy similarity (partial credit)
• Prevents series confusion: "The Housemaid" vs "The Housemaid's Secret"
• No exact match → fuzzy similarity (partial credit)

Stage 3: Author Matching (0-15 pts)

• Exact substring match → proportional credit

• No exact match → fuzzy similarity (partial credit)

• Splits authors on delimiters (comma, &, "and", " - ")

• Filters out roles ("translator", "narrator")

• Order-independent, no structure assumptions

• Ensures correct book is selected over wrong book with better format

2. Format Quality (25 pts max)

• M4B with chapters: 25
• M4B without chapters: 22
• M4A: 16
• MP3: 10
• Other: 3

3. Seeder Count (15 pts max)

• Formula: Math.min(15, Math.log10(seeders + 1) * 6)
• 1 seeder: 0pts, 10 seeders: 6pts, 100 seeders: 12pts, 1000+: 15pts

4. Size Reasonableness (10 pts max)

• Expected: 1-2 MB/min (64-128 kbps)
• Perfect match: 10 pts
• Deviation → penalty
• Unknown duration: 5 pts (neutral)

Interface

interface RankedTorrent extends TorrentResult {
  score: number;
  rank: number;
  breakdown: {
    formatScore: number;
    seederScore: number;
    sizeScore: number;
    matchScore: number;
    totalScore: number;
    notes: string[];
  };
}

function rankTorrents(
  torrents: TorrentResult[],
  audiobook: AudiobookRequest
): RankedTorrent[];

Tech Stack

• string-similarity (fuzzy matching)
• Regex for format detection