Fix title-to-slug resolution so generic token overlap no longer picks unrelated shows

[Zzackllack]

Description

This pull request improves the reliability and precision of TV series title resolution in Torznab TV search queries, especially when the query (q) parameter is missing but identifier hints (like tvdbid, tmdbid, or imdbid) are provided. It introduces a new fallback mechanism to resolve missing queries via external lookups, enhances the title matching algorithm to reduce false positives, and adds comprehensive tests to verify the new behaviors.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Testing

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Screenshots (if applicable)

Additional Notes

Torznab API improvements:

• Added logic to resolve a missing q parameter in tvsearch requests using identifier hints (tvdbid, tmdbid, imdbid) via Sonarr's SkyHook API, improving compatibility with clients that rely on ID-based lookups. (app/api/torznab/api.py [1] [2] [3] [4]
• Introduced helper functions _coerce_positive_int and _resolve_tvsearch_query_from_ids for robust identifier parsing and external lookups. (app/api/torznab/api.py app/api/torznab/api.pyR66-R142)

Title resolution and matching algorithm enhancements:

• Improved the title matching algorithm in slug_from_query to use a new scoring function based on token overlap, precision/recall, normalized string similarity, and substring/exact checks. This reduces false matches and ensures only high-confidence matches are accepted. (app/utils/title_resolver.py [1] [2] [3] [4]
• Added a minimum confidence threshold to reject low-quality matches, and introduced stop word filtering for more accurate token comparison. (app/utils/title_resolver.py [1] [2] [3]

Testing improvements:

• Added new tests to verify that the resolver prefers precise title matches over token overlap, and that low-confidence overlaps are rejected. Also added a test to ensure that the Torznab API uses the ID-resolved query when q is missing. (tests/test_title_resolver_sto.py [1] tests/test_torznab.py [2]

Summary by CodeRabbit

• New Features

  • TV show search can resolve shows from IDs (TVDB/TMDB/IMDB) when the name is missing.
  • Improved title-matching scoring for more accurate slug/query selection.

• Bug Fixes / Behavior

  • tvsearch now returns an empty feed (instead of error) when resolution fails and logs the outcome.
  • Acceptance criteria for season/episode tightened while allowing missing query if resolvable.

• Tests

  • Added tests covering ID-based resolution and low-confidence slug rejection.

[coderabbitai]

Warning

Rate limit exceeded

@Zzackllack has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 6 minutes and 34 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between a5db7ec and a4b9fe6.

📒 Files selected for processing (2)

• app/api/torznab/api.py
• app/utils/title_resolver.py

📝 Walkthrough

Walkthrough

Adds identifier-based TV show title resolution to the Torznab API using SkyHook lookups and URL-encoding; and replaces token-intersection slug matching with a tokenized scoring-based title matcher to improve slug resolution confidence.

Changes

Cohort / File(s)	Summary
TV Show Title Resolution app/api/torznab/api.py	Added _coerce_positive_int() and _resolve_tvsearch_query_from_ids() for resolving tv search queries from tvdbid/tmdbid/imdbid, using http_get + SkyHook endpoints and URL-encoding. Adjusted tvsearch flow to allow missing q when season present, attempt id-based resolution, log outcomes, and return empty RSS on unresolved slugs.
Title Matching Algorithm app/utils/title_resolver.py	Introduced _MATCH_STOPWORDS, _MIN_TITLE_MATCH_SCORE, _match_tokens(), and _score_title_candidate(); reworked slug_from_query() search to use composite scoring (token overlap, fuzzy similarity, exact/substring checks) and enforce minimum confidence, with existing s.to fallback retained.
Tests tests/test_title_resolver_sto.py, tests/test_torznab.py	Added tests: slug selection preference and low-confidence rejection for slug_from_query, and tvsearch behavior when q is missing but id-resolution returns a title. Mocks exercise resolution and slug lookup flows.

Sequence Diagram

sequenceDiagram
    participant Client as Client
    participant TorznabAPI as Torznab API
    participant Resolver as Query Resolver
    participant SkyHook as SkyHook API
    participant RSS as RSS Builder

    Client->>TorznabAPI: tvsearch (season, ep, maybe tvdbid/tmdbid/imdbid, no q)
    TorznabAPI->>Resolver: _resolve_tvsearch_query_from_ids(tvdbid, tmdbid, imdbid)
    alt Direct tvdbid present
        Resolver->>Resolver: lookup tvdbid -> title
        Resolver-->>TorznabAPI: title
    else tmdbid/imdbid provided
        Resolver->>SkyHook: search (tmdbid/imdbid) [http_get]
        SkyHook-->>Resolver: search results
        Resolver->>SkyHook: get show details (extract tvdb_id)
        SkyHook-->>Resolver: show details with tvdb_id/title
        Resolver-->>TorznabAPI: title
    else Resolution fails
        Resolver-->>TorznabAPI: None
    end
    TorznabAPI->>TorznabAPI: slug_from_query (token scoring) or return empty RSS
    TorznabAPI->>RSS: build feed
    RSS-->>TorznabAPI: RSS XML
    TorznabAPI-->>Client: HTTP 200 + RSS

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• Mapping of AniWorld Specials/Extras/"Filme" to Sonarr #56 — modifies app/api/torznab/api.py with ID-based tvdb/tmdb/imdb handling and special-mapping logic; closely related to the SkyHook/id-resolution changes here.

Suggested labels

enhancement, documentation

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 70.59% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main fix: improving title-to-slug resolution to prevent generic token overlap from selecting unrelated shows.
Description check	✅ Passed	The description is comprehensive, well-structured, includes all required template sections, and clearly explains the changes, type of change, and testing efforts.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-search-and-results

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR tightens TV series title resolution for Torznab tvsearch by (1) resolving missing q via ID hints (tvdb/tmdb/imdb) and (2) improving slug matching to avoid false positives from generic token overlap, with new tests covering both behaviors.

Changes:

• Add SkyHook-based fallback to derive q from tvdbid/tmdbid/imdbid when q is missing in tvsearch.
• Replace token-overlap-only title matching with a weighted scoring function + minimum confidence threshold.
• Add unit tests for the new ID-based fallback behavior and improved title/slug selection.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
app/api/torznab/api.py	Adds _resolve_tvsearch_query_from_ids and uses it to derive q for tvsearch when missing.
app/utils/title_resolver.py	Introduces stopword-filtered tokenization + candidate scoring and a minimum confidence threshold.
tests/test_torznab.py	Adds a test ensuring tvsearch uses the ID-resolved query when q is missing.
tests/test_title_resolver_sto.py	Adds tests ensuring the resolver prefers precise matches and rejects low-confidence overlaps.
uv.lock	Bumps the local package version to 2.4.1.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	anibridge-docs	0bd8a63	Feb 11 2026, 05:31 PM