feat(ai): AI-powered recommendations and natural-language search

compose.ai.yaml

@@ -0,0 +1,35 @@
+services:
+  seerr:
+    environment:
+      # AI Configuration - Optional
+      # Uncomment and configure your preferred AI provider below
+
+      # Option 1: OpenAI (requires API key)
+      # - OPENAI_API_KEY=${OPENAI_API_KEY}
+      # - OPENAI_BASE_URL=https://api.openai.com/v1
+      # - OPENAI_MODEL=gpt-4o-mini
+
+      # Option 2: Ollama (local, free) - Pre-configured for convenience
+      - OLLAMA_BASE_URL=http://ollama:11434/v1
+      - OLLAMA_MODEL=mistral
+
+      # Option 3: OpenRouter (multi-provider)
+      # - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
+      # - OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+      # - OPENROUTER_MODEL=meta-llama/llama-3-8b-instruct:free
+    depends_on:
+      - ollama
+    links:
+      - ollama
+
+  # Ollama for local LLM support (optional, free)
+  # Remove this service if you prefer to use a cloud AI provider
+  ollama:
+    image: ollama/ollama:latest
+    ports:
+      - '127.0.0.1:11434:11434'
+    volumes:
+      - ollama_data:/root/.ollama
+
+volumes:
+  ollama_data:

docs/using-seerr/settings/ai.md

@@ -0,0 +1,62 @@
+---
+title: AI Settings
+description: Configure AI-powered recommendations and natural-language search.
+sidebar_position: 8
+---
+
+# AI Settings
+
+AI Settings lets you opt into personalized recommendations and natural-language search, powered by a large language model. Both features are entirely optional and are **disabled** by default — Seerr continues to work exactly as it did before until you turn them on.
+
+The engine speaks to any OpenAI-compatible endpoint, so you can use a hosted provider such as OpenAI or OpenRouter, or run everything locally with Ollama, LM Studio, or LiteLLM.
+
+:::warning
+When AI features are enabled, Seerr sends the requesting user's request history, watchlist, and library metadata (titles, years, genres, and ratings) to the configured AI provider in order to generate recommendations and interpret searches. **Do not enable these features unless you are comfortable with your provider receiving this data.** A self-hosted provider such as Ollama keeps this traffic entirely on your own network.
+:::
+
+## Enable AI Features
+
+This is the master switch for all AI functionality. When disabled, none of the settings below take effect and no data is sent to any provider.
+
+This setting is **disabled** by default.
+
+## Provider Configuration
+
+Configure the OpenAI-compatible endpoint Seerr will use to generate recommendations and interpret searches.
+
+- **AI Provider** — Choose your provider type. Selecting **Ollama (Local)** adjusts the expected base URL and hides the API key field, since Ollama does not require authentication.
+- **Base URL** — The root URL of the provider's API. For OpenAI this is `https://api.openai.com/v1`. For a local Ollama instance, use `http://localhost:11434/v1` when Seerr runs on your host, or `http://ollama:11434/v1` when Seerr runs in Docker Compose alongside the Ollama service (as in the bundled `compose.ai.yaml`).
+- **Model** — The model name to use (for example, `gpt-4o-mini`, `mistral`, or whatever your local provider exposes).
+- **API Key** — The key for your provider. This is not required for Ollama. Once saved, the field is masked; leave it blank on subsequent edits to keep the existing key. If you would rather provide the key out of band, Seerr falls back to the `OPENAI_API_KEY` environment variable.
+
+Use **Test Connection** to verify your settings before saving. It sends a minimal request to the provider and reports whether a valid response came back, along with the round-trip latency.
+
+## Recommendations
+
+When enabled, Seerr generates a "Recommended for You" slider on the Discover page and a dedicated recommendations page, personalized per user from their requests, watchlist, and available library.
+
+![The Recommended for You discover page](/img/seerr-ai-recommend.png)
+
+Recommendations are produced by a background job (the AI Recommendations Sync job, every 6 hours by default) rather than on demand. You can also trigger it manually from the Jobs & Cache settings tab to populate the slider sooner after first enabling it.
+
+- **Enable Recommendations** — Turns the recommendations slider and page on or off independently of the master toggle above.
+- **Slider Title** — The heading shown above the slider on the Discover page. Defaults to "Recommended for You".
+- **Max Results** — The maximum number of titles to generate per user, between 1 and 50.
+- **Minimum Rating** — The minimum TMDB rating (0.0–10.0) a recommendation must meet; higher values surface better-rated titles at the cost of fewer results. Defaults to 7.
+- **Recommendation TTL (days)** — How long a recommendation lives before it expires. Titles that are re-recommended on a later run are kept alive, while stale ones age out after this many days, so the list refreshes gradually rather than being replaced wholesale.
+
+## AI Search
+
+When enabled, an "AI Search" toggle is added to the search page. Regular keyword search remains the default and does not use the AI provider at all; switching to AI Search interprets a natural-language query ("90s psychological thrillers", "feel-good anime about friendship") using the configured model, resolves it to TMDB results, and shows an "AI interpretation" badge describing how the query was parsed.
+
+This setting is **disabled** by default.
+
+## Feedback
+
+On recommendation cards, each user can rate a title with three quick actions, revealed by hovering over the card:
+
+- 👍 **More like this** — biases future recommendations toward similar content.
+- 👁️ **Already watched** — removes the card and excludes the title from future recommendations.
+- 👎 **Not interested** — removes the card and excludes the title from future recommendations.
+
+Dislike and "already watched" take effect immediately in the current list; like is recorded quietly to refine the next generation run.

package.json

@@ -48,6 +48,7 @@
     "ace-builds": "1.43.6",
     "axios": "1.15.0",
     "axios-rate-limit": "1.9.0",
+    "openai": "^6.25.0",
     "bcrypt": "6.0.0",
     "bowser": "2.14.1",
     "connect-typeorm": "2.0.0",

seerr-api.yml

@@ -6395,6 +6395,282 @@ paths:
                           type: string
                         title:
                           type: string
+  /discover/ai-recommendations:
+    get:
+      summary: Get AI-powered personalized recommendations
+      description: |
+        Returns personalized media recommendations generated by the AI engine based on the
+        user's request history, watchlist, and available library content.
+      tags:
+        - discover
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      parameters:
+        - in: query
+          name: page
+          schema:
+            type: number
+            example: 1
+            default: 1
+        - in: query
+          name: language
+          schema:
+            type: string
+            example: en
+      responses:
+        '200':
+          description: AI recommendations returned
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  page:
+                    type: number
+                  totalPages:
+                    type: number
+                  totalResults:
+                    type: number
+                  results:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: number
+                        mediaType:
+                          type: string
+                        title:
+                          type: string
+                        posterPath:
+                          type: string
+                          nullable: true
+                        backdropPath:
+                          type: string
+                          nullable: true
+                        overview:
+                          type: string
+                        releaseDate:
+                          type: string
+                          nullable: true
+                        voteAverage:
+                          type: number
+                        aiRationale:
+                          type: string
+                          nullable: true
+                        aiScore:
+                          type: number
+                          nullable: true
+        '404':
+          description: AI recommendations are disabled
+  /ai/settings:
+    get:
+      summary: Get AI settings
+      description: Retrieves the current AI provider and feature configuration.
+      tags:
+        - ai
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      responses:
+        '200':
+          description: AI settings returned
+          content:
+            application/json:
+              schema:
+                type: object
+    put:
+      summary: Update AI settings
+      description: Updates the AI provider and feature configuration.
+      tags:
+        - ai
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        '200':
+          description: AI settings updated
+  /ai/test:
+    post:
+      summary: Test AI provider connection
+      description: Tests connectivity to the configured AI provider.
+      tags:
+        - ai
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        '200':
+          description: Connection test result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  latency:
+                    type: number
+                  error:
+                    type: string
+  /ai/search:
+    post:
+      summary: AI-powered natural language search
+      description: |
+        Interprets a natural language query and returns personalized media results
+        based on the user's viewing history.
+      tags:
+        - ai
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                query:
+                  type: string
+                options:
+                  type: object
+      responses:
+        '200':
+          description: Search results returned
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  page:
+                    type: number
+                  totalPages:
+                    type: number
+                  totalResults:
+                    type: number
+                  results:
+                    type: array
+                    items:
+                      type: object
+                  query:
+                    type: string
+                  interpretation:
+                    type: object
+                    nullable: true
+                    description: |
+                      How the AI parsed the query (genres, year range, language,
+                      min rating, keywords) — surfaced to the UI as a badge.
+                    properties:
+                      discover_params:
+                        type: object
+                      suggested_titles:
+                        type: array
+                        items:
+                          type: object
+  /ai/feedback:
+    post:
+      summary: Submit user feedback on a recommendation
+      description: Records like/dislike/seen feedback for a media item.
+      tags:
+        - ai
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                tmdbId:
+                  type: number
+                mediaType:
+                  type: string
+                  enum: [movie, tv]
+                feedbackType:
+                  type: string
+                  enum: [like, dislike, seen]
+      responses:
+        '200':
+          description: Feedback submitted
+  /ai/feedback/stats:
+    get:
+      summary: Get user feedback statistics
+      description: Returns counts and recent feedback for the current user.
+      tags:
+        - ai
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      responses:
+        '200':
+          description: Feedback statistics returned
+          content:
+            application/json:
+              schema:
+                type: object
+  /ai/feedback/{tmdbId}:
+    delete:
+      summary: Delete user feedback
+      description: Removes feedback for a specific media item.
+      tags:
+        - ai
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      parameters:
+        - in: path
+          name: tmdbId
+          required: true
+          schema:
+            type: number
+        - in: query
+          name: mediaType
+          required: true
+          schema:
+            type: string
+            enum: [movie, tv]
+      responses:
+        '200':
+          description: Feedback deleted
+        '404':
+          description: Feedback not found
+  /ai/regenerate:
+    post:
+      summary: Regenerate AI recommendations
+      description: Manually triggers recommendation generation for the current user.
+      tags:
+        - ai
+      security:
+        - cookieAuth: []
+        - apiKey: []
+      responses:
+        '200':
+          description: Recommendations regenerated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  count:
+                    type: number
   /request:
     get:
       summary: Get all requests