feat: implement episode matching policy for improved media handling

[g0ldyy]

Added a new function to determine episode matching criteria based on media type, season, and episode number. Updated the stream function to utilize this policy, enhancing the handling of IMDB episode requests and refining the logic for rejecting unknown episode files.

Summary by CodeRabbit

• Improvements
  • Smarter episode-matching for IMDb-like episode lookups, improving identification across sources.
  • More consistent gating of episode files—unknown or mismatched files are now rejected based on cache, debrid and torrent policies.
  • Improved handling and logging when episode air dates are unavailable to aid troubleshooting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e3c1b8b-fa76-460d-b2ff-b6c40e4c1788

📥 Commits

Reviewing files that changed from the base of the PR and between d406bb5 and 0529c04.

📒 Files selected for processing (1)

• comet/api/endpoints/stream.py

---

Walkthrough

Introduces a centralized _episode_matching_policy() helper in the stream endpoint that produces is_imdb_episode_request and reject_unknown_episode_files flags; replaces the previous strict_episode_matching usage to drive target air date lookups and torrent file rejection behavior.

Changes

Cohort / File(s)	Summary
Episode matching policy refactor comet/api/endpoints/stream.py	Added _episode_matching_policy() to compute is_imdb_episode_request and reject_unknown_episode_files; removed strict_episode_matching; switched target air date lookup and logging to use is_imdb_episode_request; passed policy-derived reject_unknown_episode_files into TorrentManager and get_account_torrents_for_media calls.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: introducing an episode matching policy helper function for improved episode handling logic, which aligns with the file changes and PR objectives.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

---

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.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

comet/api/endpoints/stream.py (1)

743-757: ⚠️ Potential issue | 🟡 Minor

Account-snapshot path ignores allow_debrid_verified_season_packs and may drop valid season packs from the user's debrid library.

The policy at L154–179 deliberately sets reject_unknown_episode_files=False when cached_only && has_debrid && !enable_torrent so that debrid-verified season packs can be surfaced. However, here you pass reject_unknown_episode_files=is_imdb_episode_request (always True for imdb episode requests), so in exactly that permissive mode, season packs already present in the user's debrid account snapshot are filtered out at torrent-level before any later file verification can occur.

The inline comment notes this is deferred "until a later file-level debrid verification happens," but account-snapshot entries come from the debrid account itself — this is precisely where file-level verification would succeed. Consider passing the policy's reject_unknown_episode_files here as well (or make the divergence explicit via a separate flag/policy output) so behavior stays consistent with the main scrape path.

Proposed alignment

-            # Account snapshots only expose torrent-level names, so keep strict
-            # episode gating until a later file-level debrid verification happens.
-            reject_unknown_episode_files=is_imdb_episode_request,
+            # Mirror the main scrape path so debrid-verified season packs from
+            # the account snapshot are not filtered out before file-level checks.
+            reject_unknown_episode_files=reject_unknown_episode_files,

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@comet/api/endpoints/stream.py` around lines 743 - 757, The account-snapshot
call to get_account_torrents_for_media is using
reject_unknown_episode_files=is_imdb_episode_request which causes
debrid-verified season packs to be dropped; change the call to pass the
policy-computed reject_unknown_episode_files value (the same variable set at
L154–179, or introduce and pass a new explicit flag like
allow_debrid_verified_season_packs/reject_unknown_episode_files_from_policy) so
the account-snapshot path follows the same permissive behavior as the main
scrape path and does not filter valid season packs prematurely; update the
argument to get_account_torrents_for_media and any upstream variable names
(e.g., reject_unknown_episode_files) accordingly.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@comet/api/endpoints/stream.py`:
- Around line 743-757: The account-snapshot call to
get_account_torrents_for_media is using
reject_unknown_episode_files=is_imdb_episode_request which causes
debrid-verified season packs to be dropped; change the call to pass the
policy-computed reject_unknown_episode_files value (the same variable set at
L154–179, or introduce and pass a new explicit flag like
allow_debrid_verified_season_packs/reject_unknown_episode_files_from_policy) so
the account-snapshot path follows the same permissive behavior as the main
scrape path and does not filter valid season packs prematurely; update the
argument to get_account_torrents_for_media and any upstream variable names
(e.g., reject_unknown_episode_files) accordingly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4fc29f32-ad05-49bd-81e5-f74bc0aa05e3

📥 Commits

Reviewing files that changed from the base of the PR and between a0c75e5 and d406bb5.

📒 Files selected for processing (1)

• comet/api/endpoints/stream.py