giuseppe99barchetta/SuggestArr

🚀 SuggestArr – AI‑powered media recommendation & request automation

SuggestArr is an open‑source service that watches what your household streams on Jellyfin, Plex, or Emby, then automatically suggests similar titles and sends download requests to Seer (a media‑request manager). It can pull recommendations from TMDb or from any OpenAI‑compatible large language model, letting you get AI‑generated suggestions with a short rationale.

---

Core capabilities

Feature	What it does
Watch‑history sources	Reads recent plays from Jellyfin, Plex, Emby; optional per‑user Trakt sync; can also import CSV or manual TMDb lists.
Recommendation engine	Uses TMDb’s similarity API or any OpenAI‑compatible LLM (OpenAI, Ollama, OpenRouter, LiteLLM, etc.) to produce a list of titles with a short natural‑language reason.
AI Search	Type a free‑form description of what you want to watch; SuggestArr queries the LLM and returns matching titles in one click.
Public‑list import	Pulls lists from MDBList or Trakt on a schedule or on demand.
Request workflow	Sends chosen titles to Seer; can require manual approval, pause when Seer has pending requests, or auto‑decline stale requests.
Cleanup automation	Periodically removes SuggestArr‑generated requests that never got favorited (dry‑run by default).
Filters	Skips content already available on streaming services in your country, respects quality limits, and applies per‑user filters.
Web UI	Setup wizard, scheduling, user management, live logs, and connection tests—all reachable via a browser.
Recaps & milestones	Generates shareable summaries of what has been suggested/added.
Database back‑ends	SQLite out‑of‑the‑box; optional PostgreSQL or MySQL for larger installations.
Public REST API	Stable /api/v1 endpoints with Swagger UI for external integrations.

---

Technical stack & requirements

• Docker (recommended) or a plain Python 3 environment.
• TMDb API key (free registration).
• One of the supported media servers (Jellyfin / Plex / Emby).
• Seer (the request‑handling service) – the tool only creates requests, it does not download media itself.
• Optional: PostgreSQL/MySQL, an OpenAI‑compatible LLM endpoint, Trakt app credentials.

---

Quick start (Docker Compose)

services:
  suggestarr:
    image: ciuse99/suggestarr:latest   # also available as ghcr.io/giuseppe99barchetta/suggestarr
    container_name: SuggestArr
    restart: always
    ports:
      - "${SUGGESTARR_PORT:-5000}:${SUGGESTARR_PORT:-5000}"
    volumes:
      - ./config_files:/app/config/config_files
    environment:
      - LOG_LEVEL=${LOG_LEVEL:-info}
      - SUGGESTARR_PORT=${SUGGESTARR_PORT:-5000}

docker compose up -d

Then open http://localhost:5000 and follow the web‑based setup wizard.

---

Extending & integrating

• API – All external tools can call the stable /api/v1 endpoints; Swagger UI is available at /docs.
• LLM plug‑in – Set the OPENAI_API_BASE (or equivalent) environment variable to point at any compatible model; SuggestArr will use it for AI‑driven recommendations and search.
• Database migration – Switch from SQLite to PostgreSQL/MySQL by updating the connection string in the config file; the schema is managed automatically.

---

Community & support

• Discord: https://discord.com/invite/JXwFd3PnXY
• Donations: Ko‑fi and Buy‑Me‑a‑Coffee links for optional support.
• Contributing: Issues and pull requests are welcomed; the repo includes detailed installation, feature, and API guides.

---

License

MIT – free to use, modify, and redistribute.

---

Bottom line: SuggestArr ties together your existing media server, TMDb (or any LLM), and Seer to turn passive watch history into proactive, AI‑enhanced viewing suggestions and automated request handling, all controllable via a clean web UI or a public REST API.