Expose IMDb ratings in detail responses and derive season ratings

- CompleteMediaSerializer/CompleteEpisodeSerializer now surface item
  imdb_rating/imdb_rating_count alongside the TMDB-based score, sourced
  from the Item resolved in each view.
- Untracked seasons/episodes in related.seasons/related.episodes now do
  a batched DB lookup for an already-synced Item instead of always
  building a blank in-memory one.
- Add sync_season_ratings(): derives a season's IMDb rating as a
  vote-weighted average of its episodes' ratings, wired into the
  Celery task and the backfill_imdb_ratings command.
- _build_imdb_rating_context now supports SEASON so season detail
  pages show the IMDb rating chip.
- Add imdb_rating/imdb_rating_count to the API contract and regenerate
  openapi.yaml.

Fixes #984

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dannyvfilms

src/api/contract_serializers.py

@@ -212,6 +212,9 @@ class CompleteMediaResponseSerializer(serializers.Serializer):
     genres = serializers.ListField(child=serializers.CharField(), allow_null=True)
     score = serializers.FloatField(allow_null=True)
     score_count = serializers.IntegerField(allow_null=True)
+    # FORK: IMDb rating alongside TMDB-based score
+    imdb_rating = serializers.FloatField(allow_null=True)
+    imdb_rating_count = serializers.IntegerField(allow_null=True)
     cast = serializers.ListField(child=serializers.DictField())
     crew = serializers.ListField(child=serializers.DictField())
     details = serializers.DictField()

src/api/serializers.py

@@ -173,6 +173,8 @@ def to_representation(self, instance):
             many=True,
         )
 
+        item = instance.get("item")
+
         return {
             "id": user_medias[0].item_id if user_medias else None,
             "media_id": (
@@ -192,6 +194,9 @@ def to_representation(self, instance):
             "genres": media_metadata.get("genres", []),
             "score": float(episode.get("vote_average")),
             "score_count": episode.get("vote_count"),
+            # FORK: IMDb rating alongside TMDB-based score
+            "imdb_rating": getattr(item, "imdb_rating", None),
+            "imdb_rating_count": getattr(item, "imdb_rating_count", None),
             "details": {
                 "air_date": episode.get("air_date"),
                 "episode_number": episode.get("episode_number"),
@@ -224,6 +229,18 @@ def _process_seasons(self, media_metadata, seasons_by_number=None):
         ):
             media_metadata["related"]["seasons"] = []
 
+        # FORK: look up already-synced season Items (e.g. IMDb ratings) for
+        # untracked seasons instead of always building an ephemeral in-memory
+        # Item, one batched query for the whole show rather than per-season.
+        existing_items_by_season = {
+            existing_item.season_number: existing_item
+            for existing_item in Item.objects.filter(
+                media_id=str(media_metadata.get("media_id") or ""),
+                source=media_metadata.get("source"),
+                media_type=MediaTypes.SEASON.value,
+            )
+        }
+
         processed_seasons = []
         for season in media_metadata["related"]["seasons"]:
             season_number = season.get("season_number")
@@ -232,6 +249,8 @@ def _process_seasons(self, media_metadata, seasons_by_number=None):
             )
 
             item = getattr(tracked_season, "item", None)
+            if item is None:
+                item = existing_items_by_season.get(season_number)
             if item is None:
                 item = Item(
                     media_id=str(
@@ -279,10 +298,23 @@ def _process_episodes(self, media_metadata, episodes_by_number=None):
             media_metadata["related"]["episodes"] = []
 
         episodes = media_metadata.pop("episodes", [])
+        # FORK: look up already-synced episode Items (e.g. IMDb ratings) for
+        # untracked episodes instead of always building an ephemeral in-memory
+        # Item, one batched query for the whole season rather than per-episode.
+        existing_items_by_episode = {
+            existing_item.episode_number: existing_item
+            for existing_item in Item.objects.filter(
+                media_id=str(media_metadata.get("media_id") or ""),
+                source=media_metadata.get("source"),
+                media_type=MediaTypes.EPISODE.value,
+                season_number=media_metadata.get("season_number"),
+            )
+        }
         serializer = EpisodeSerializer(
             context={
                 "source": media_metadata.get("source"),
                 "tracked_episodes": episodes_by_number or {},
+                "existing_items_by_episode": existing_items_by_episode,
             },
         )
         processed_episodes = [
@@ -370,6 +402,11 @@ def to_representation(self, instance):
             "score_count": int(media_metadata.get("score_count"))
             if media_metadata.get("score_count") is not None
             else None,
+            # FORK: IMDb rating alongside TMDB-based score
+            "imdb_rating": getattr(instance.get("item"), "imdb_rating", None),
+            "imdb_rating_count": getattr(
+                instance.get("item"), "imdb_rating_count", None,
+            ),
             "cast": media_metadata.get("cast") or [],
             "crew": media_metadata.get("crew") or [],
             "details": details,
@@ -433,23 +470,28 @@ def to_representation(self, instance):
         if hasattr(episode, "item"):
             item = getattr(episode, "item", None)
         else:
-            image = (
-                "https://image.tmdb.org/t/p/original" + instance.get("still_path")
-                if instance.get("still_path")
-                else None
-            )
-            item = Item(
-                media_id=media_id,
-                source=context.get("source"),
-                media_type=MediaTypes.EPISODE.value,
-                title=instance.get("name") or "",
-                image=image,
-                season_number=season_number,
-                episode_number=episode_number,
-                release_datetime=app_helpers.extract_release_datetime(
-                    {"release_date": instance.get("air_date")},
-                ),
-            )
+            # FORK: reuse an already-synced episode Item (e.g. IMDb ratings)
+            # instead of always building an ephemeral in-memory Item.
+            existing_items_by_episode = context.get("existing_items_by_episode", {})
+            item = existing_items_by_episode.get(episode_number)
+            if item is None:
+                image = (
+                    "https://image.tmdb.org/t/p/original" + instance.get("still_path")
+                    if instance.get("still_path")
+                    else None
+                )
+                item = Item(
+                    media_id=media_id,
+                    source=context.get("source"),
+                    media_type=MediaTypes.EPISODE.value,
+                    title=instance.get("name") or "",
+                    image=image,
+                    season_number=season_number,
+                    episode_number=episode_number,
+                    release_datetime=app_helpers.extract_release_datetime(
+                        {"release_date": instance.get("air_date")},
+                    ),
+                )
 
         if hasattr(episode, "lists"):
             lists = episode.lists

src/api/tests/helpers.py

@@ -85,6 +85,8 @@ def check_complete_media_structure(test_case, item):
     test_case.assertIn("genres", item)
     test_case.assertIn("score", item)
     test_case.assertIn("score_count", item)
+    test_case.assertIn("imdb_rating", item)
+    test_case.assertIn("imdb_rating_count", item)
     test_case.assertIn("cast", item)
     test_case.assertIsInstance(item["cast"], list)
     test_case.assertIn("crew", item)

src/api/tests/test_media_core.py

@@ -711,6 +711,8 @@ def test_media_detail_get_returns_expected_shape(self, mock_metadata):
                 "genres",
                 "score",
                 "score_count",
+                "imdb_rating",
+                "imdb_rating_count",
                 "cast",
                 "crew",
                 "details",
@@ -759,6 +761,51 @@ def test_tv_detail_reports_tracked_season(self, mock_metadata):
         self.assertTrue(season["tracked"])
         self.assertEqual(season["id"], season_media.item_id)
 
+    @patch("api.views.services.get_media_metadata")
+    def test_tv_detail_untracked_season_reports_synced_imdb_rating(
+        self,
+        mock_metadata,
+    ):
+        """An untracked season with a previously-synced Item still shows its rating."""
+        tv_item = self.items_by_type[MediaTypes.TV.value][0]
+        Item.objects.create(
+            media_id=tv_item.media_id,
+            source=tv_item.source,
+            media_type=MediaTypes.SEASON.value,
+            title="Untracked Season 5",
+            season_number=5,
+            imdb_rating=6.7,
+            imdb_rating_count=42,
+        )
+        mock_metadata.return_value = {
+            "media_id": tv_item.media_id,
+            "source": tv_item.source,
+            "media_type": MediaTypes.TV.value,
+            "related": {
+                "seasons": [
+                    {
+                        "media_id": tv_item.media_id,
+                        "source": tv_item.source,
+                        "media_type": MediaTypes.SEASON.value,
+                        "season_number": 5,
+                    },
+                ],
+            },
+        }
+
+        response = self.call_api(
+            "get",
+            "api_media_detail",
+            args=(MediaTypes.TV.value, tv_item.source, tv_item.media_id),
+            headers=self.auth_headers,
+        )
+
+        self.assertEqual(response.status_code, 200)
+        season = response.json()["related"]["seasons"][0]
+        self.assertFalse(season["tracked"])
+        self.assertEqual(season["item"]["imdb_rating"], 6.7)
+        self.assertEqual(season["item"]["imdb_rating_count"], 42)
+
     def test_media_detail_get_invalid_type_returns_bad_request(self):
         """Media detail endpoint should reject unsupported media types."""
         response = self.call_api(
@@ -789,6 +836,41 @@ def test_media_detail_get_invalid_media_id_returns_ok_with_null_item_id(self):
         self.assertIsNone(response.data["item_id"])
         self.assertIsNone(response.data["parent_id"])
 
+    def test_media_detail_get_exposes_imdb_rating_for_untracked_item(self):
+        """Untracked movies with a previously-synced Item still show IMDb rating."""
+        Item.objects.create(
+            media_id="777",
+            source="tmdb",
+            media_type=MediaTypes.MOVIE.value,
+            title="Synced Movie",
+            imdb_rating=8.5,
+            imdb_rating_count=1200,
+        )
+
+        response = self.call_api(
+            "get",
+            "api_media_detail",
+            args=(MediaTypes.MOVIE.value, "tmdb", 777),
+            headers=self.auth_headers,
+        )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["imdb_rating"], 8.5)
+        self.assertEqual(response.data["imdb_rating_count"], 1200)
+
+    def test_media_detail_get_imdb_rating_none_without_synced_item(self):
+        """Media with no Item row at all reports a null IMDb rating."""
+        response = self.call_api(
+            "get",
+            "api_media_detail",
+            args=(MediaTypes.MOVIE.value, "tmdb", 999999),
+            headers=self.auth_headers,
+        )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertIsNone(response.data["imdb_rating"])
+        self.assertIsNone(response.data["imdb_rating_count"])
+
     @patch("api.views.services.get_media_metadata")
     def test_media_detail_get_podcast_resolves_tracked_and_untracked_episodes(
         self,

src/api/tests/test_media_episode.py

@@ -163,6 +163,42 @@ def test_episode_detail_get_returns_expected_shape(self, mock_metadata):
         self.assertNotIn("season_number", payload)
         self.assertNotIn("episode_number", payload)
 
+    @patch("api.views.services.get_media_metadata")
+    def test_episode_detail_get_exposes_imdb_rating(self, mock_metadata):
+        """Episode detail GET should expose the episode Item's IMDb rating."""
+        tv_item = self.items_by_type[MediaTypes.TV.value][0]
+        season_item = self.items_by_type[MediaTypes.SEASON.value][0]
+        episode_item = self.items_by_type[MediaTypes.EPISODE.value][0]
+        episode_item.imdb_rating = 9.2
+        episode_item.imdb_rating_count = 4321
+        episode_item.save()
+
+        mock_metadata.return_value = self.build_episode_metadata(
+            tv_item=tv_item,
+            season_number=season_item.season_number,
+            episode_number=episode_item.episode_number,
+            title=episode_item.title,
+            image=episode_item.image,
+        )
+
+        response = self.call_api(
+            "get",
+            "api_media_episode_detail",
+            args=(
+                MediaTypes.TV.value,
+                tv_item.source,
+                tv_item.media_id,
+                season_item.season_number,
+                episode_item.episode_number,
+            ),
+            headers=self.auth_headers,
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["imdb_rating"], 9.2)
+        self.assertEqual(payload["imdb_rating_count"], 4321)
+
     @patch("api.views.services.get_media_metadata")
     def test_episode_detail_patch_with_invalid_field_returns_400(self, mock_metadata):
         """Episode PATCH with unknown field should return 400."""

src/api/tests/test_media_season.py

@@ -539,6 +539,102 @@ def test_season_detail_get_invalid_media_id_returns_ok_with_null_item_id(self):
         self.assertIsNone(response.data["item_id"])
         self.assertIsNone(response.data["parent_id"])
 
+    @patch("api.views.services.get_media_metadata")
+    def test_season_detail_get_exposes_imdb_rating(self, mock_metadata):
+        """Season detail GET should expose the season Item's IMDb rating."""
+        tv_item = self.items_by_type[MediaTypes.TV.value][0]
+        season_item = self.items_by_type[MediaTypes.SEASON.value][0]
+        season_item.imdb_rating = 7.3
+        season_item.imdb_rating_count = 890
+        season_item.save()
+
+        mock_metadata.return_value = {
+            "media_id": tv_item.media_id,
+            "source": tv_item.source,
+            "media_type": "season",
+            "season_number": season_item.season_number,
+            "related": {"episodes": []},
+        }
+
+        response = self.call_api(
+            "get",
+            "api_media_season_detail",
+            args=(
+                MediaTypes.TV.value,
+                tv_item.source,
+                tv_item.media_id,
+                season_item.season_number,
+            ),
+            headers=self.auth_headers,
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["imdb_rating"], 7.3)
+        self.assertEqual(payload["imdb_rating_count"], 890)
+
+    @patch("api.views.services.get_media_metadata")
+    def test_season_detail_untracked_episode_reports_synced_imdb_rating(
+        self,
+        mock_metadata,
+    ):
+        """An untracked episode with a previously-synced Item still shows its rating."""
+        tv_item = self.items_by_type[MediaTypes.TV.value][0]
+        season_item = self.items_by_type[MediaTypes.SEASON.value][0]
+        Item.objects.create(
+            media_id=tv_item.media_id,
+            source=tv_item.source,
+            media_type=MediaTypes.EPISODE.value,
+            title="Untracked Episode 99",
+            season_number=season_item.season_number,
+            episode_number=99,
+            imdb_rating=5.4,
+            imdb_rating_count=17,
+        )
+
+        mock_metadata.return_value = {
+            "source": tv_item.source,
+            "media_id": tv_item.media_id,
+            "media_type": "season",
+            "season_number": season_item.season_number,
+            "episodes": [
+                {
+                    "episode_number": 99,
+                    "season_number": season_item.season_number,
+                    "show_id": tv_item.media_id,
+                    "name": "Untracked Episode 99",
+                    "overview": "",
+                    "vote_average": 0.0,
+                    "vote_count": 0,
+                    "air_date": None,
+                    "runtime": None,
+                    "episode_type": None,
+                    "crew": [],
+                    "guest_stars": [],
+                    "still_path": None,
+                },
+            ],
+            "related": {"episodes": []},
+        }
+
+        response = self.call_api(
+            "get",
+            "api_media_season_detail",
+            args=(
+                MediaTypes.TV.value,
+                tv_item.source,
+                tv_item.media_id,
+                season_item.season_number,
+            ),
+            headers=self.auth_headers,
+        )
+
+        self.assertEqual(response.status_code, 200)
+        episode = response.json()["related"]["episodes"][0]
+        self.assertFalse(episode["tracked"])
+        self.assertEqual(episode["item"]["imdb_rating"], 5.4)
+        self.assertEqual(episode["item"]["imdb_rating_count"], 17)
+
     @patch("api.views.services.get_media_metadata")
     def test_season_detail_patch_updates_season_fields(self, mock_metadata):
         """Season detail PATCH should update season fields."""