Address review comments

MediaBrowser.Controller/Library/ISimilarItemsManager.cs

@@ -6,6 +6,7 @@ using Jellyfin.Database.Implementations.Entities;
 using MediaBrowser.Controller.Dto;
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Model.Configuration;
+using MediaBrowser.Model.Dto;
 
 namespace MediaBrowser.Controller.Library;
 
@@ -49,12 +50,21 @@ public interface ISimilarItemsManager
         CancellationToken cancellationToken);
 
     /// <summary>
-    /// Gets similar items for multiple source items in a single batch.
+    /// Builds movie recommendations for a user: a mix of similar-items and person-based categories,
+    /// scheduled round-robin and capped to <paramref name="categoryLimit"/>.
     /// </summary>
-    /// <param name="sourceItems">The source items to find similar items for.</param>
-    /// <param name="query">The query options.</param>
-    /// <returns>Per-source-item results keyed by source item ID.</returns>
-    Task<Dictionary<Guid, IReadOnlyList<BaseItem>>> GetBatchSimilarItemsAsync(
-        IReadOnlyList<BaseItem> sourceItems,
-        SimilarItemsQuery query);
+    /// <param name="user">The user the recommendations are for. May be <see langword="null"/> for anonymous access.</param>
+    /// <param name="parentId">The library/folder to localize the search to. Pass <see cref="Guid.Empty"/> to use the root.</param>
+    /// <param name="categoryLimit">Maximum number of recommendation categories to return.</param>
+    /// <param name="itemLimit">Maximum number of items per category.</param>
+    /// <param name="dtoOptions">DTO options used when querying the library.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The list of recommendation categories, ordered by <see cref="RecommendationType"/>.</returns>
+    Task<IReadOnlyList<SimilarItemsRecommendation>> GetMovieRecommendationsAsync(
+        User? user,
+        Guid parentId,
+        int categoryLimit,
+        int itemLimit,
+        DtoOptions dtoOptions,
+        CancellationToken cancellationToken);
 }

MediaBrowser.Controller/Library/SimilarItemsRecommendation.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Collections.Generic;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Model.Dto;
+
+namespace MediaBrowser.Controller.Library;
+
+/// <summary>
+/// A recommendation category derived from a baseline item, holding similar items prior to DTO conversion.
+/// </summary>
+public sealed class SimilarItemsRecommendation
+{
+    /// <summary>
+    /// Gets the display name of the baseline item the recommendation is based on.
+    /// </summary>
+    public required string BaselineItemName { get; init; }
+
+    /// <summary>
+    /// Gets an identifier for the recommendation category.
+    /// </summary>
+    public required Guid CategoryId { get; init; }
+
+    /// <summary>
+    /// Gets the recommendation type.
+    /// </summary>
+    public required RecommendationType RecommendationType { get; init; }
+
+    /// <summary>
+    /// Gets the similar items for the baseline, ordered by relevance.
+    /// </summary>
+    public required IReadOnlyList<BaseItem> Items { get; init; }
+}