SuggestArr Documentation

SuggestArr automates media content recommendations and download requests based on user activity in media servers like Jellyfin, Plex, and Emby. It retrieves recently watched content, searches for similar titles using the TMDb API, and sends automated download requests to Seer.

Key features include:

• Multi-Media Server Support: Jellyfin, Plex, and Emby.
• TMDb Integration: For similarity searches.
• AI-Powered Recommendations (beta): Uses OpenAI-compatible LLMs for personalized suggestions.
• Trakt Integration: Uses Trakt watch history as recommendation seeds.
• Automated Requests: Direct integration with Seer.
• Safety Controls: Job pausing based on pending Seer requests or unwatched suggestions, and cleanup automation for old requests.

SuggestArr separates administrative management from individual user settings:

• Admins (Users page): Create accounts, manage permissions, and assign media-server accounts to users.
• Users (Profile page):
  • Link their own Plex, Jellyfin, or Emby account.
  • Link their own Trakt account (via Profile > Trakt Account) using device-code OAuth.
  • View Recent Trakt Preview to verify watch history is being fetched.

The design system is built on several categories of tokens defined in variables.css. Use these categories to maintain visual consistency:

• Colors: Includes surface hierarchy (backgrounds), semantic colors (success, warning, error, info), text colors, border colors, and alpha transparency modifiers.
• Spacing: An 8px-based scale ranging from 2xs to 3xl. Use this for all margins, paddings, and gaps.
• Typography: Includes font sizes (xs to 5xl), font weights (normal to extrabold), and line heights.
• Elevation: A shadow scale (sm to 2xl), focus states, and glow effects.
• Border Radius: Consistent rounding from sm to xl and full.
• Component Density: Pre-defined sizing for buttons (sm, md, lg), inputs (sm, md, lg), cards, modals, badges, and dropdowns.

The Jobs page allows you to manage automated recommendation and discovery tasks.

Job Features

• Scheduling: Use presets like daily, every_12h, or standard cron syntax (e.g., 0 3 * * *).
• Execution Control: Create, preview, run, enable, or disable jobs.
• Pause while Seer requests are pending: When enabled, SuggestArr checks if Seer has any requests awaiting approval or denial. If so, the job is skipped to prevent overwhelming the queue. Paused jobs are logged with the reason: Paused: Seer has pending requests awaiting approval or denial.

Best Practices

• Create focused jobs (e.g., one for movies, one for TV) rather than one broad job.
• Use dry-run mode before enabling aggressive automation.
• Use lower result counts for frequent jobs.

To run SuggestArr behind a reverse proxy (e.g., Nginx, Traefik):

1. Keep SuggestArr listening on port 5000 internally.
2. Terminate HTTPS at the proxy.
3. Forward X-Forwarded-For, X-Forwarded-Proto, and Host headers.
4. Use SUGGESTARR_ALLOWED_ORIGINS if the frontend is served from a different origin.
5. Use SUBPATH if hosting under a path like /suggestarr.

environment:
  - SUGGESTARR_PORT=5000
  - SUGGESTARR_ALLOWED_ORIGINS=https://suggestarr.example.com
  - SUBPATH=suggestarr

To compile and minify the project for production deployment, use the build script:

npm run build

The easiest way to run SuggestArr is using Docker Compose. You can customize the port using the SUGGESTARR_PORT environment variable (defaults to 5000) and set the log level with LOG_LEVEL (defaults to info).

Ensure you have a directory for configuration files mapped to ./config_files.

services:
  suggestarr:
    image: ciuse99/suggestarr:latest
    container_name: SuggestArr
    restart: always
    ports:
      - "${SUGGESTARR_PORT:-5000}:${SUGGESTARR_PORT:-5000}"
    volumes:
      - ./config_files:/app/config/config_files
    environment:
      # Optional: Only needed if something goes wrong and you need to inspect deeper
      - LOG_LEVEL=${LOG_LEVEL:-info}
      # Optional: Customize the port (defaults to 5000 if not set)
      - SUGGESTARR_PORT=${SUGGESTARR_PORT:-5000}

To start the container:

docker-compose up

The AI Search feature allows for natural-language queries to find movies and TV shows by translating descriptions (mood, era, genre, etc.) into TMDB filters. To use this feature, you must configure an LLM provider.

Steps to enable:

1. Navigate to the web interface.
2. Go to Settings → Advanced.
3. Check the Enable beta features checkbox.
4. Complete the AI Provider Configuration fields (API key, base URL, and model).
5. Save your settings.

The AI Search tab will then appear in the dashboard. Note that AI Search is a manual feature triggered from the dashboard and is independent of the automated cron-based recommendations.

To run linting and automatically fix style issues in the codebase, use the lint script:

npm run lint

Use this method for development. For production, Docker is recommended.

# From repository root
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r api_service\requirements.txt

cd client
npm install
npm run build
cd ..

New-Item -ItemType Directory -Force static
Copy-Item -Path client\dist\* -Destination static -Recurse -Force

$env:SUGGESTARR_PORT = "5000"
python -m api_service.app

Trakt integration provides extra watch-history context for recommendation jobs.

Setup Workflow

1. App Credentials: Create an OAuth app at trakt.tv/oauth/applications. Copy the Client ID and Client Secret.
2. Admin Configuration: In SuggestArr, go to Services > Trakt and paste the credentials.
3. User Linking:
   • Users must first link their media-server account (Plex/Jellyfin/Emby) in their Profile.
   • Once linked, users go to Profile > Trakt Account and click Link Trakt.
   • A device code will be shown; users enter this on the Trakt activation page.

Job Usage

Once linked, recommendation jobs can use Trakt in two ways:

• Use Trakt as Seed: Uses recent Trakt watches to seed recommendations.
• Exclude Trakt Watched: Skips items already marked as watched on Trakt.