Implement Similarity providers

6 files changed, 188 insertions, 0 deletions

diff --git a/MediaBrowser.Controller/Library/ILocalSimilarItemsProvider.cs b/MediaBrowser.Controller/Library/ILocalSimilarItemsProvider.cs
new file mode 100644
index 0000000000..9bf0121f5f
--- /dev/null
+++ b/MediaBrowser.Controller/Library/ILocalSimilarItemsProvider.cs
@@ -0,0 +1,27 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using MediaBrowser.Controller.Entities;
+
+namespace MediaBrowser.Controller.Library;
+
+/// <summary>
+/// Provides similar items from the local library for a specific item type.
+/// Returns fully resolved BaseItems directly - no additional resolution needed.
+/// </summary>
+/// <typeparam name="TItemType">The type of item this provider handles.</typeparam>
+public interface ILocalSimilarItemsProvider<TItemType> : ISimilarItemsProvider
+    where TItemType : BaseItem
+{
+    /// <summary>
+    /// Gets similar items from the local library.
+    /// </summary>
+    /// <param name="item">The source item to find similar items for.</param>
+    /// <param name="query">The query options (user, limit, exclusions, etc.).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The list of similar items from the library.</returns>
+    Task<IReadOnlyList<BaseItem>> GetSimilarItemsAsync(
+        TItemType item,
+        SimilarItemsQuery query,
+        CancellationToken cancellationToken);
+}
diff --git a/MediaBrowser.Controller/Library/IRemoteSimilarItemsProvider.cs b/MediaBrowser.Controller/Library/IRemoteSimilarItemsProvider.cs
new file mode 100644
index 0000000000..a77b6628d9
--- /dev/null
+++ b/MediaBrowser.Controller/Library/IRemoteSimilarItemsProvider.cs
@@ -0,0 +1,26 @@
+using System.Collections.Generic;
+using System.Threading;
+using MediaBrowser.Controller.Entities;
+
+namespace MediaBrowser.Controller.Library;
+
+/// <summary>
+/// Provides similar item references from remote/external sources for a specific item type.
+/// Returns lightweight references with ProviderIds that the manager resolves to library items.
+/// </summary>
+/// <typeparam name="TItemType">The type of item this provider handles.</typeparam>
+public interface IRemoteSimilarItemsProvider<TItemType> : ISimilarItemsProvider
+    where TItemType : BaseItem
+{
+    /// <summary>
+    /// Gets similar item references from an external source as an async stream.
+    /// </summary>
+    /// <param name="item">The source item to find similar items for.</param>
+    /// <param name="query">The query options (user, limit, exclusions).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>An async enumerable of similar item references.</returns>
+    IAsyncEnumerable<SimilarItemReference> GetSimilarItemsAsync(
+        TItemType item,
+        SimilarItemsQuery query,
+        CancellationToken cancellationToken);
+}
diff --git a/MediaBrowser.Controller/Library/ISimilarItemsManager.cs b/MediaBrowser.Controller/Library/ISimilarItemsManager.cs
new file mode 100644
index 0000000000..0ced6f71ee
--- /dev/null
+++ b/MediaBrowser.Controller/Library/ISimilarItemsManager.cs
@@ -0,0 +1,50 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Database.Implementations.Entities;
+using MediaBrowser.Controller.Dto;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Model.Configuration;
+
+namespace MediaBrowser.Controller.Library;
+
+/// <summary>
+/// Interface for managing similar items providers and operations.
+/// </summary>
+public interface ISimilarItemsManager
+{
+    /// <summary>
+    /// Registers similar items providers discovered through dependency injection.
+    /// </summary>
+    /// <param name="providers">The similar items providers to register.</param>
+    void AddParts(IEnumerable<ISimilarItemsProvider> providers);
+
+    /// <summary>
+    /// Gets the similar items providers for a specific item type.
+    /// </summary>
+    /// <typeparam name="T">The item type.</typeparam>
+    /// <returns>The list of similar items providers for that type.</returns>
+    IReadOnlyList<ISimilarItemsProvider> GetSimilarItemsProviders<T>()
+        where T : BaseItem;
+
+    /// <summary>
+    /// Gets similar items for the specified item.
+    /// </summary>
+    /// <param name="item">The source item to find similar items for.</param>
+    /// <param name="excludeArtistIds">Artist IDs to exclude from results.</param>
+    /// <param name="user">The user context.</param>
+    /// <param name="dtoOptions">The DTO options.</param>
+    /// <param name="limit">Maximum number of results.</param>
+    /// <param name="libraryOptions">The library options for provider configuration.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The list of similar items.</returns>
+    Task<IReadOnlyList<BaseItem>> GetSimilarItemsAsync(
+        BaseItem item,
+        IReadOnlyList<Guid> excludeArtistIds,
+        User? user,
+        DtoOptions dtoOptions,
+        int? limit,
+        LibraryOptions? libraryOptions,
+        CancellationToken cancellationToken);
+}
diff --git a/MediaBrowser.Controller/Library/ISimilarItemsProvider.cs b/MediaBrowser.Controller/Library/ISimilarItemsProvider.cs
new file mode 100644
index 0000000000..0d089369a8
--- /dev/null
+++ b/MediaBrowser.Controller/Library/ISimilarItemsProvider.cs
@@ -0,0 +1,26 @@
+using System;
+using MediaBrowser.Model.Configuration;
+
+namespace MediaBrowser.Controller.Library;
+
+/// <summary>
+/// Base marker interface for similar items providers.
+/// </summary>
+public interface ISimilarItemsProvider
+{
+    /// <summary>
+    /// Gets the name of the provider.
+    /// </summary>
+    string Name { get; }
+
+    /// <summary>
+    /// Gets the type of the provider.
+    /// </summary>
+    MetadataPluginType Type { get; }
+
+    /// <summary>
+    /// Gets the cache duration for results from this provider.
+    /// If null, results will not be cached.
+    /// </summary>
+    TimeSpan? CacheDuration => null;
+}
diff --git a/MediaBrowser.Controller/Library/SimilarItemReference.cs b/MediaBrowser.Controller/Library/SimilarItemReference.cs
new file mode 100644
index 0000000000..2a40c93bdd
--- /dev/null
+++ b/MediaBrowser.Controller/Library/SimilarItemReference.cs
@@ -0,0 +1,22 @@
+namespace MediaBrowser.Controller.Library;
+
+/// <summary>
+/// A reference to a similar item by provider ID with a similarity score.
+/// </summary>
+public class SimilarItemReference
+{
+    /// <summary>
+    /// Gets or sets the provider name (e.g., "Tmdb", "MusicBrainzArtist").
+    /// </summary>
+    public required string ProviderName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the provider ID value.
+    /// </summary>
+    public required string ProviderId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the similarity score (0.0 to 1.0).
+    /// </summary>
+    public float? Score { get; set; }
+}
diff --git a/MediaBrowser.Controller/Library/SimilarItemsQuery.cs b/MediaBrowser.Controller/Library/SimilarItemsQuery.cs
new file mode 100644
index 0000000000..1ed3ceec16
--- /dev/null
+++ b/MediaBrowser.Controller/Library/SimilarItemsQuery.cs
@@ -0,0 +1,37 @@
+using System;
+using System.Collections.Generic;
+using Jellyfin.Database.Implementations.Entities;
+using MediaBrowser.Controller.Dto;
+
+namespace MediaBrowser.Controller.Library;
+
+/// <summary>
+/// Query options for similar items requests.
+/// </summary>
+public class SimilarItemsQuery
+{
+    /// <summary>
+    /// Gets or sets the user context.
+    /// </summary>
+    public User? User { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum number of results.
+    /// </summary>
+    public int? Limit { get; set; }
+
+    /// <summary>
+    /// Gets or sets the DTO options.
+    /// </summary>
+    public DtoOptions? DtoOptions { get; set; }
+
+    /// <summary>
+    /// Gets or sets the item IDs to exclude from results.
+    /// </summary>
+    public IReadOnlyList<Guid> ExcludeItemIds { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the artist IDs to exclude from results.
+    /// </summary>
+    public IReadOnlyList<Guid> ExcludeArtistIds { get; set; } = [];
+}