giuseppe99barchetta/SuggestArr

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

New jobs follow the global Approve requests before sending them to Seer setting, disabled by default under Advanced. Each job can inherit that setting or override it to always approve or always send automatically. Held results appear on the Requests page, where the job owner or an administrator can send them to Seer, reject them, or blacklist them globally.

The global Request Workflow settings can also pause a job while its SuggestArr suggestions await review and automatically reject suggestions left pending for a configured number of days. The pause behavior can be overridden per job.

Features

• Multi-Media Server Support: Supports Jellyfin, Plex, and Emby for retrieving media content.
• TMDb Integration: Searches for similar movies and TV shows on TMDb.
• AI-Powered Recommendations (beta): Uses any OpenAI-compatible LLM (OpenAI, Ollama, Gemini, LiteLLM…) to generate hyper-personalized suggestions based on watch history, complete with AI reasoning for each pick.
• AI Search (beta): Describe in natural language what you want to watch and let the AI find matching titles, personalised to your viewing history, with one-click request to Seer.
• Trakt Watch History: Let each user link their own Trakt account. SuggestArr can use Trakt recent watches as recommendation seeds and skip content already watched on Trakt.
• Automated Requests: Sends download requests for recommended content to Seer.
• Pending-Request Job Pause: Skip scheduled or manual jobs while Seer still has requests waiting for approval or denial.
• Unwatched-Suggestion Pause: Optionally pause scheduled recommendation jobs when a user has not watched a SuggestArr request within a configurable number of days; manual runs remain available.
• Cleanup Automation: Optionally prune old SuggestArr-originated requests and files when users never favorite them in Plex, Jellyfin, or Emby.
• Web Interface: A user-friendly interface for configuration and management.
• Real-Time Logs: View and filter logs in real time (e.g., INFO, ERROR, DEBUG).
• User Selection: Choose specific users to initiate requests, allowing management and approval of auto-requested content.
• Per-User Request Visibility: Filter requests by media-server account, or let administrators limit regular users to requests for their linked Plex, Jellyfin, or Emby account.
• Cron Job Management: Update the cron job schedule directly from the web interface.
• Configuration Pre-testing: Automatically validates API keys and URLs during setup.
• Content Filtering: Exclude requests for content already available on streaming platforms in your country.
• External Database Support: Use external databases (PostgreSQL, MySQL) in addition to SQLite for improved scalability and performance.

Prerequisites

• Python 3.x or Docker
• TMDb API Key
• Configured Jellyfin, Plex, or Emby
• Configured Seer
• (Optional) External database (PostgreSQL or MySQL) for improved performance
• (Optional) Trakt OAuth application for per-user Trakt watch-history integration

Docker Usage

You can run the project using Docker Compose for easy setup and execution.

Docker Compose Example

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 with Docker Compose:

docker-compose up

Web Interface

Access the web interface at: http://localhost:5000 (or your custom port if configured with SUGGESTARR_PORT). Use this interface to configure the application, select your media service, and manage cron schedules.

Make sure your environment is set up correctly and that the application is running to access the web interface.

Using a Specific Seer User for Requests

If you'd like to use a specific Seer user to make media requests, follow these steps:

1. In the web interface, enable the user selection option by checking the corresponding box.
2. Select the desired user from the dropdown list.
3. Enter the password for the selected user.
4. The system will now use this user to make media requests, rather than using the admin or default profile.

Note: Currently, only local Seer users are supported.

Trakt Watch History Integration

SuggestArr can enrich recommendations with each user's own Trakt watch history. Trakt is optional: media-server history still works without it.

What Trakt adds

• Recent Trakt watches can be used as recommendation seeds.
• Fully watched Trakt items can be added to the skip-watched set.
• Each SuggestArr user links their own Trakt account from their profile.
• Admins configure only the shared Trakt app credentials.
• A collapsible Recent Trakt Preview panel shows the latest items fetched from Trakt when opened.

How to enable

1. Create a Trakt OAuth app at https://trakt.tv/oauth/applications.
2. In SuggestArr, go to Services -> Trakt.
3. Enter the Trakt Client ID and Client Secret, then save.
4. Each user goes to Profile -> Trakt Account and clicks Link Trakt.
5. Enter the Trakt device code shown by SuggestArr at the Trakt activation URL.
6. Open Recent Trakt Preview to verify the latest Trakt history is being read.

For admins, the same profile panel is available under Users. Trakt links are tied to the user's linked Plex, Jellyfin, or Emby media profile, so users should link their media-server account first.

Job Pause and Cleanup Automation

SuggestArr includes two safety tools for running automation without flooding Seer or keeping unwanted media forever.

Pause jobs while Seer has pending requests

Each job has a Pause while Seer requests are pending option in its schedule settings.

When enabled, SuggestArr checks Seer before running that job. If Seer has requests still awaiting approval or denial, the job is skipped and logged as paused/skipped. This applies to scheduled runs, single job runs, and force-run-all.

Recommendation and Trakt Recommendation jobs can also enable Pause if suggestions remain unwatched. Movie and TV activity is tracked separately per linked media user. Watching a requested movie or one episode of a requested show starts a fresh cycle; only scheduled runs are paused.

Use this when Seer approvals are part of your workflow and you want new automation runs to wait until the previous batch has been reviewed.

Cleanup Automation

Cleanup Automation is available under Advanced -> Cleanup Automation.

It looks at requests created by SuggestArr, waits for the configured grace period, checks whether the item is favorited in Plex, Jellyfin, or Emby, and then:

• keeps favorited items
• skips items no longer present in the media library
• logs what would be deleted in dry-run mode
• asks Seer to delete matching media files when real mode is enabled

Cleanup is off by default and starts safely in dry-run mode. Always run dry-run first and review the audit log before enabling real deletions.

AI-Powered Recommendations (Beta)

SuggestArr includes an optional AI recommendation engine that analyzes your watch history and suggests titles that match your taste, with a short explanation for each pick.

The engine works with any OpenAI-compatible API, so you can use a cloud provider or a local model running on your own machine.

How to enable

1. Open the web interface and go to Settings → Advanced.
2. Check Enable beta features.
3. Check Use advanced suggestion algorithm.
4. Fill in the AI Provider Configuration fields that appear (click the ⓘ button next to the section title for an in-app guide).
5. Save. The AI engine will be used automatically on the next automation run.

If the LLM is unavailable or returns no results, SuggestArr falls back to the standard TMDb-based recommendation algorithm transparently.

Supported providers

Provider	API Key	Base URL	Example model
OpenAI	Required (sk-proj-...)	(leave blank)	gpt-4o-mini
Ollama (local)	Not required	http://localhost:11434/v1	mistral, llama3
OpenRouter	Required (sk-or-v1-...)	https://openrouter.ai/api/v1	meta-llama/llama-3-8b-instruct
LiteLLM Proxy	Depends on config	http://<your-proxy>:4000	Depends on config

Note for Ollama users: make sure Ollama is running and the model is pulled (ollama pull mistral) before saving. The API Key field can be left blank — SuggestArr will use a placeholder automatically.

Docker Compose with Ollama (example)

services:
  suggestarr:
    image: ciuse99/suggestarr:latest
    container_name: SuggestArr
    restart: always
    ports:
      - "5000:5000"
    volumes:
      - ./config_files:/app/config/config_files

  ollama:
    image: ollama/ollama
    container_name: ollama
    restart: always
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

volumes:
  ollama_data:

After starting both containers, pull your preferred model:

docker exec -it ollama ollama pull mistral

Then in SuggestArr Advanced settings set:

• Base URL → http://ollama:11434/v1
• Model → mistral
• API Key → (leave blank)

---

🔍 AI Search (Beta)

SuggestArr includes an AI Search tab in the dashboard that lets you find movies and TV shows using plain text, no browsing required.

How it works

Type a natural-language description of what you feel like watching. The LLM interprets your query (genres, era, language, rating threshold, mood…) and translates it into structured TMDB filters. Results are ranked and enriched with an AI-generated rationale explaining why each title was picked for you.

Examples of queries you can use:

• "A psychological thriller from the 90s with a twist ending"
• "Feel-good anime with strong friendships"
• "80s sci-fi movies with practical effects"
• "A dark comedy series like Breaking Bad"

Key capabilities

• Natural language queries — describe mood, genre, decade, language, or specific themes
• Viewing-history personalisation — the AI tailors results based on what you (or your users) have already watched
• Exclude already-watched titles — hide content you've already seen
• One-click requesting — send results directly to Seer without leaving the page
• Query interpretation badge — see how the AI parsed your query (genres, year range, language, min rating)

How to enable

AI Search requires an LLM to be configured (same setup as AI-Powered Recommendations):

1. Open the web interface → Settings → Advanced.
2. Check Enable beta features.
3. Fill in the AI Provider Configuration fields (API key, base URL, model).
4. Save. The AI Search tab will become active in the dashboard.

AI Search is independent of the automated recommendations run — it is triggered manually from the dashboard and does not affect cron-based automation.

---

Installation

For Docker, Unraid, source install, reverse proxy, backup, and recommended configuration instructions, see the Installation Guide.

Support SuggestArr ❤️

If you enjoy SuggestArr, consider making a donation to support its continued development and help keep the project running at its best:

• ☕ Ko-fi
• 💛 Buy Me a Coffee

Every contribution, no matter the size, is greatly appreciated. Thank you for supporting SuggestArr!

Join Our Discord Community

Feel free to join our Discord community to share ideas, ask questions, or get help with SuggestArr: Join here.

Contribute

Contributions are highly welcome! Feel free to open issues, submit pull requests, or provide any feedback that can improve the project. Whether you're fixing bugs, improving documentation, or adding new features, all contributions are greatly appreciated.

License

This project is licensed under the MIT License.