Feat/content recommendation engine part2 (#459)

* feat(content): add trending, personalized, and editorial recommendations (steps 2-4 of #226)

Completes the Content Recommendation Engine (issue #226) on top of step 1
(similar-content, #458):

- trending: recent UsageEvent popularity (downloads > api access > views),
  precomputed every 15 minutes into a global + per-category Redis leaderboard.
  GET /recommendations/trending/?category=
- personalized: scores the catalog against a user's own recent usage history
  using the same facet weights as similar-content, precomputed nightly at
  2:15am, falling back to trending when a user has no precomputed data yet.
  GET /recommendations/personalized/ (requires an API key)
- editorial: new EditorialRecommendation/EditorialRecommendationAsset models
  for admin-curated collections (e.g. seasonal spotlights) with an active
  window (starts_at/ends_at) and ordered assets, exposed in Django admin.
  GET /recommendations/editorial/ (read straight from the DB, no cache)

Shared scoring helpers were factored out of the similar-content implementation
(facet indexing, pair scoring) so trending/personalized reuse the same
candidate-generation approach rather than duplicating it.

38 new tests across service and public-endpoint layers; full apps/content and
apps/usage_tracking suites pass with zero regressions (905 passed, 6 skipped).

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

* fix(content): resolve redis test clients from django-redis and fix import order/formatting

Same issue as #458: hardcoding host="localhost" for the Redis test client
only works when pytest runs natively, not inside the django container CI
uses (Redis lives on host "redis" there). Applied the same fix -- reuse
get_redis_connection("default").connection_pool.connection_kwargs -- to
all four files affected (similar, trending, personalized, service tests).

Also fixes isort import ordering (redis vs model_bakery/django/oauth2_provider)
in the same four files, and a black formatting fix in
test_recommendations_service.py that pre-commit would have caught.

* fix(content): resolve redis test client host from REDIS_URL, not django-redis

Same correction as feat/content-recommendation-engine: get_redis_connection
always raises NotImplementedError under dev/CI settings, since
config/settings/development.py forces CACHES to LocMemCache regardless of
REDIS_URL. Resolve host/port from REDIS_URL directly via decouple.config()
instead, matching base.py's own resolution and working in both native runs
(localhost) and CI's docker-compose network (redis).

* fix(content): resolve migration conflict, missing translation, and import formatting

- Add merge migration for the two independent content leaf nodes created by
  merging staging (asset-versioning: 0051_assetversion_content_edited) and
  this branch's own editorial recommendations migration
  (0050_editorialrecommendation_editorialrecommendationasset_and_more) --
  migrate/makemigrations --check both failed without it.
- Add the missing Arabic translation for "You must be signed in to get
  personalized recommendations." (personalized endpoint's 401 message) --
  the string was added to code but never localized, which fails the
  extendedmakemessages --check CI step.
- Let isort/black reformat an import in recommendations.py that pre-commit
  would have caught.

Verified end-to-end against the actual CI Docker stack (docker-compose.local.yml):
migrate, makemigrations --check, extendedmakemessages --check, full
apps/content + apps/usage_tracking suite (941 passed, 6 skipped), and
pre-commit run --all-files all pass clean.

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: farhaghallab3

apps/content/admin.py

@@ -30,6 +30,8 @@
     AssetVersion,
     CategoryChoice,
     ContentIssueReport,
+    EditorialRecommendation,
+    EditorialRecommendationAsset,
     Qiraah,
     RecitationAyahTiming,
     RecitationFolder,
@@ -943,3 +945,38 @@ def _bulk_update_status(self, request, queryset, new_status, label):
         for item in changing:
             send_issue_status_update_email.delay(item["id"], item["status"], new_status)
         self.message_user(request, f"Marked {count} reports as {label}.")
+
+
+class EditorialRecommendationAssetInline(admin.TabularInline):
+    """Ordered assets within an editorial recommendation collection."""
+
+    model = EditorialRecommendationAsset
+    extra = 1
+    fields = ["asset", "position"]
+    raw_id_fields = ["asset"]
+    ordering = ["position"]
+
+
+@admin.register(EditorialRecommendation)
+class EditorialRecommendationAdmin(admin.ModelAdmin):
+    list_display = ["id", "title", "is_active", "starts_at", "ends_at", "assets_count", "created_at"]
+    list_filter = ["is_active"]
+    search_fields = ["title_en", "title_ar", "description_en", "description_ar"]
+    readonly_fields = ["created_at", "updated_at"]
+    inlines = [EditorialRecommendationAssetInline]
+
+    fieldsets = (
+        (
+            "Basic Information",
+            {"fields": ("title_en", "title_ar", "description_en", "description_ar", "is_active")},
+        ),
+        ("Active Window", {"fields": ("starts_at", "ends_at")}),
+        (
+            "Timestamps",
+            {"fields": ("created_at", "updated_at"), "classes": ("collapse",)},
+        ),
+    )
+
+    @admin.display(description="Assets")
+    def assets_count(self, obj: EditorialRecommendation) -> int:
+        return obj.recommendation_assets.count() if obj.pk else 0

apps/content/api/public/recommendations.py

@@ -5,8 +5,14 @@
 from ninja import Schema
 
 from apps.content.models import Asset, StatusChoice
-from apps.content.services.recommendations import get_similar_asset_ids, hydrate_visible_assets_in_order
-from apps.core.ninja_utils.errors import NinjaErrorResponse
+from apps.content.services.recommendations import (
+    get_personalized_asset_ids,
+    get_similar_asset_ids,
+    get_trending_asset_ids,
+    hydrate_visible_assets_in_order,
+    list_active_editorial_recommendations,
+)
+from apps.core.ninja_utils.errors import ItqanError, NinjaErrorResponse
 from apps.core.ninja_utils.request import Request
 from apps.core.ninja_utils.router import ItqanRouter
 from apps.core.ninja_utils.tags import NinjaTag
@@ -84,3 +90,79 @@ def get_similar_recommendations(request: Request, asset_id: int):
 
     similar_ids = get_similar_asset_ids(asset_id)
     return hydrate_visible_assets_in_order(similar_ids)
+
+
+@router.get(
+    "recommendations/trending/",
+    response={200: list[RecommendedAssetOut]},
+)
+@track_usage(entity_type="recommendation_trending")
+def get_trending_recommendations(request: Request, category: str | None = None):
+    """
+    Currently popular content, ranked by recent usage weighted by event kind (a
+    download counts for more than a view). Precomputed periodically via Celery beat
+    (see apps.content.services.recommendations); an empty/not-yet-computed cache
+    simply yields an empty list, same as /similar/ treats "no matches".
+
+    `category` optionally scopes the leaderboard to one CategoryChoice value (e.g.
+    "recitation"); an unrecognised value behaves like "nothing trending yet" (empty
+    list) rather than a 400, since that's cheap to tell apart from a client bug by
+    just looking at the response.
+    """
+    trending_ids = get_trending_asset_ids(category=category)
+    return hydrate_visible_assets_in_order(trending_ids)
+
+
+@router.get(
+    "recommendations/personalized/",
+    response={
+        200: list[RecommendedAssetOut],
+        401: NinjaErrorResponse[Literal["authentication_required"]],
+    },
+)
+@track_usage(entity_type="recommendation_personalized")
+def get_personalized_recommendations(request: Request):
+    """
+    Suggestions based on the authenticated user's own download/view history (see
+    compute_personalized_recommendations). Falls back to global trending when the
+    user has no precomputed personalized data yet -- new account, no history since the
+    last nightly run, or a history too narrow to score any candidates all count as "no
+    personalized data", a valid non-error outcome, not "nothing to recommend at all".
+
+    Requires authentication (unlike similar/trending/editorial, which are pure
+    discovery metadata): personalized results are tied to a specific user's history.
+    """
+    user = getattr(request, "user", None)
+    if not (user and user.is_authenticated):
+        raise ItqanError(
+            "authentication_required",
+            _("You must be signed in to get personalized recommendations."),
+            status_code=401,
+        )
+
+    personalized_ids = get_personalized_asset_ids(user.id)
+    if not personalized_ids:
+        personalized_ids = get_trending_asset_ids()
+    return hydrate_visible_assets_in_order(personalized_ids)
+
+
+class EditorialRecommendationOut(Schema):
+    id: int
+    title: str
+    description: str
+    assets: list[RecommendedAssetOut]
+
+
+@router.get(
+    "recommendations/editorial/",
+    response={200: list[EditorialRecommendationOut]},
+)
+@track_usage(entity_type="recommendation_editorial")
+def get_editorial_recommendations(request: Request):
+    """
+    Admin-curated featured collections (e.g. seasonal spotlights) currently in their
+    active window, newest first. Unlike similar/trending/personalized this reads
+    straight from the DB -- editorial collections change rarely and the query is
+    already small and indexed, so there's no precompute/cache step.
+    """
+    return list_active_editorial_recommendations()

apps/content/migrations/0050_editorialrecommendation_editorialrecommendationasset_and_more.py

@@ -0,0 +1,54 @@
+# Generated by Django 5.2.14 on 2026-08-23 16:56
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('content', '0049_recitation_track_folder_constraints'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='EditorialRecommendation',
+            fields=[
+                ('id', models.AutoField(help_text='Unique identifier for this record', primary_key=True, serialize=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True, help_text='Timestamp when this record was created')),
+                ('updated_at', models.DateTimeField(auto_now=True, help_text='Timestamp when this record was last updated')),
+                ('title', models.CharField(help_text="Collection title, e.g. 'Ramadan Recitations'", max_length=255)),
+                ('title_en', models.CharField(help_text="Collection title, e.g. 'Ramadan Recitations'", max_length=255, null=True)),
+                ('title_ar', models.CharField(help_text="Collection title, e.g. 'Ramadan Recitations'", max_length=255, null=True)),
+                ('description', models.TextField(blank=True, default='')),
+                ('description_en', models.TextField(blank=True, default='', null=True)),
+                ('description_ar', models.TextField(blank=True, default='', null=True)),
+                ('is_active', models.BooleanField(default=True, help_text='Whether this collection is eligible to be served')),
+                ('starts_at', models.DateTimeField(blank=True, help_text='Optional start of the active window', null=True)),
+                ('ends_at', models.DateTimeField(blank=True, help_text='Optional end of the active window', null=True)),
+            ],
+            options={
+                'ordering': ['-created_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='EditorialRecommendationAsset',
+            fields=[
+                ('id', models.AutoField(help_text='Unique identifier for this record', primary_key=True, serialize=False)),
+                ('created_at', models.DateTimeField(auto_now_add=True, help_text='Timestamp when this record was created')),
+                ('updated_at', models.DateTimeField(auto_now=True, help_text='Timestamp when this record was last updated')),
+                ('position', models.PositiveIntegerField(default=1, help_text='Display order within the collection')),
+                ('asset', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='editorial_recommendation_assets', to='content.asset')),
+                ('recommendation', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='recommendation_assets', to='content.editorialrecommendation')),
+            ],
+            options={
+                'ordering': ['position'],
+                'unique_together': {('recommendation', 'asset')},
+            },
+        ),
+        migrations.AddField(
+            model_name='editorialrecommendation',
+            name='assets',
+            field=models.ManyToManyField(related_name='editorial_recommendations', through='content.EditorialRecommendationAsset', to='content.asset'),
+        ),
+    ]

apps/content/migrations/0052_merge_20260826_1701.py

@@ -0,0 +1,14 @@
+# Generated by Django 5.2.14 on 2026-08-26 14:01
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('content', '0050_editorialrecommendation_editorialrecommendationasset_and_more'),
+        ('content', '0051_assetversion_content_edited'),
+    ]
+
+    operations = [
+    ]

apps/content/models.py

@@ -922,3 +922,53 @@ def clean(self):
     def save(self, *args, **kwargs) -> None:
         self.full_clean()
         super().save(*args, **kwargs)
+
+
+class EditorialRecommendation(BaseModel):
+    """Admin-curated collection of assets for a featured spotlight (e.g. Ramadan, Hajj).
+
+    Served by GET /recommendations/editorial/ (apps.content.services.recommendations)
+    while ``is_active`` and within [starts_at, ends_at] -- both bounds are optional, so
+    a collection can be always-on or scheduled ahead of time and left to auto-expire.
+    """
+
+    title = models.CharField(max_length=255, help_text="Collection title, e.g. 'Ramadan Recitations'")
+    description = models.TextField(blank=True, default="")
+    is_active = models.BooleanField(default=True, help_text="Whether this collection is eligible to be served")
+    starts_at = models.DateTimeField(null=True, blank=True, help_text="Optional start of the active window")
+    ends_at = models.DateTimeField(null=True, blank=True, help_text="Optional end of the active window")
+
+    assets = models.ManyToManyField(
+        Asset,
+        through="EditorialRecommendationAsset",
+        related_name="editorial_recommendations",
+    )
+
+    class Meta:
+        ordering = ["-created_at"]
+
+    def __str__(self) -> str:
+        return f"EditorialRecommendation({self.title})"
+
+
+class EditorialRecommendationAsset(BaseModel):
+    """One asset's position within an EditorialRecommendation collection."""
+
+    recommendation = models.ForeignKey(
+        EditorialRecommendation,
+        on_delete=models.CASCADE,
+        related_name="recommendation_assets",
+    )
+    asset = models.ForeignKey(
+        Asset,
+        on_delete=models.CASCADE,
+        related_name="editorial_recommendation_assets",
+    )
+    position = models.PositiveIntegerField(default=1, help_text="Display order within the collection")
+
+    class Meta:
+        unique_together = [["recommendation", "asset"]]
+        ordering = ["position"]
+
+    def __str__(self) -> str:
+        return f"EditorialRecommendationAsset(recommendation={self.recommendation_id}, asset={self.asset_id})"