Skip to content
DritteRippePublic

About

KI-Kurator für Radarr: Filmempfehlungen via Claude, FastAPI-Web-GUI für Docker/Synology.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Pickarr

An AI curator for a household media server. Pickarr suggests movies and series that fit the household's library and taste, explains why, and adds the chosen titles to Radarr or Sonarr with one click. It runs as a single container on a Synology NAS (LAN only, behind Nginx Proxy Manager) and is used from phones, desktops and the TV as a PWA.

Version 2 is a full rebuild. The binding specification is docs/REBUILD-SPEC.md; the visual system ("Nachtvorstellung") is docs/DESIGN-SYSTEM.md. Operations (deploy, rollout, rollback, backups, troubleshooting) live in docs/OPERATIONS.md.

What it does

  • Grounded recommendations (Entdecken): Claude ranks real TMDB candidates and explains its picks; hard rules (owned, seen, dismissed, exclusions, cooldown, profile rules) are enforced in code. Presets for moods, occasions and collections, "Mehr wie dieser", refine chips, auto count. Without AI credit or budget, a deterministic ranking takes over (Sparmodus).
  • Household profiles: personas with rules (for example no horror, kids profile with FSK limit), per-profile seen state synced from Jellyfin, taste profiles with a feedback loop.
  • Filmabend and Swipe & Match: one-tap picks for tonight from the own library, or a shared swipe deck for two.
  • Library tools (Bibliothek): overview and stats, maintenance audit (quality, German audio, cutoff), collection gaps, seen list, history, watchlist CSV import, kids wishes with approval.
  • Assistant: multi-turn chat with read-only tools on Radarr, Sonarr, Jellyfin and TMDB, plus a structured setup analysis.
  • Scheduler and push: weekly digest, Jellyfin lists, rating pings and maintenance jobs run inside the app; push via ntfy, Discord, a webhook or plain text.
  • Guardrail: nothing is ever added, downloaded, deleted or changed in Radarr/Sonarr without an explicit click; Pickarr's own adds can be undone within the undo window.

Architecture

Part Stack Path
Backend Python 3.12, FastAPI, uvicorn (one process, one worker), SQLite (WAL, one writer thread), httpx, Anthropic SDK backend/pickarr/
Frontend Svelte 5, Vite, TypeScript, PWA (service worker) frontend/
Shared Media key test vectors used by both sides shared/
Container Multi-stage Dockerfile (Node build, hash-checked Python deps, non-root runtime), compose.yaml repo root

Data lives in DATA_DIR (/data in the container): the v2 database pickarr-v2.sqlite, daily backups under backups/, and the untouched v1 files (pickarr.sqlite, seen_movies.json), which are imported once, losslessly, at the first start.

Configuration

All configuration comes from environment variables; secrets are never stored in the database or shown in the UI. .env.example lists every variable with a dummy value and a one-line comment (spec section 4.7). Required: RADARR_URL, RADARR_API_KEY, and with AUTH_ENABLED=true (the default) APP_USER plus APP_PASSWORD_HASH. Without credentials and with auth enabled the app starts in locked mode and refuses to serve (fail closed).

Create a password hash (the password is read interactively or from stdin, never from argv):

python -m pickarr.cli hash-password

Put the value in single quotes in the .env file, because it contains $.

Development

Requirements: Python 3.12 with uv, Node 24 or newer.

# backend
cd backend
uv venv .venv --python 3.12
uv pip sync requirements-dev.lock                          # hash-pinned lock (uses ./.venv)
.venv/bin/python -m pytest                                 # Windows: .venv\Scripts\python.exe

# frontend
cd frontend
npm ci
npm run dev        # Vite dev server, proxies /api to 127.0.0.1:8090

# run the app locally (serves the built frontend from frontend/dist)
cd frontend && npm run build
cd ../backend
DATA_DIR=/tmp/pickarr-data PICKARR_STATIC_DIR=../frontend/dist AUTH_ENABLED=false \
  RADARR_URL=http://radarr.local:7878 RADARR_API_KEY=dummy .venv/bin/python -m pickarr

Quality gates

scripts/check.sh runs every gate of spec 10.5: ruff, black, pytest with at least 80 % coverage, npm ci, svelte-check (no warnings), vitest, vite build, the bundle budget, the API contract check (gen:types + check:contract), export_openapi.py --check and the Docker build (skipped with a SKIP line where Docker is not installed).

The HTTP contract is frozen in backend/pickarr/api/schemas.py and frontend/src/lib/api/types.ts. After a deliberate contract change, regenerate the exported schema and types:

python scripts/export_openapi.py          # writes frontend/src/lib/api/openapi.json
cd frontend && npm run gen:types && npm run check:contract

Smoke test

scripts/smoke.py (standard library only) checks a running instance end to end: health, app shell and CSP, service worker and manifest, 401 without a session, CSRF and login, the main read endpoints, the legacy /digest 410, logout. --ai additionally measures two real recommendation runs (costs a few cents).

SMOKE_PASSWORD=... python scripts/smoke.py --base-url http://127.0.0.1:8090 --user maik

Repository layout

backend/            FastAPI app (pickarr/), tests (tests/platform, tests/domain, tests/ai)
frontend/           Svelte app (src/), static assets (public/), build scripts
shared/             media-key-vectors.json (shared test vectors)
scripts/            check.sh, export_openapi.py, smoke.py
docs/               REBUILD-SPEC.md, DESIGN-SYSTEM.md, OPERATIONS.md, contract-requests/, archive/
Dockerfile, compose.yaml, .env.example

License and credits

Private household project. Streaming availability data is provided by JustWatch through TMDB; this product uses the TMDB API but is not endorsed or certified by TMDB.

About

KI-Kurator für Radarr: Filmempfehlungen via Claude, FastAPI-Web-GUI für Docker/Synology.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages