sweepify

AI-powered curator for your Spotify music — sweep your songs into playlists.

sweepify fetches your liked songs (or any playlist), sends their metadata to Claude for classification, and creates Spotify playlists based on the categories it discovers (genre, mood, energy, etc.).

Prerequisites

• Python 3.11+
• uv
• A Spotify Developer account
• An Anthropic API key or AWS Bedrock access

Setup

1. Clone and install

git clone https://github.com/luiul/sweepify.git
cd sweepify
uv sync

2. Create a Spotify app

1. Go to the Spotify Developer Dashboard
2. Click Create App
3. Set the Redirect URI to http://127.0.0.1:8888/callback
4. Note the Client ID and Client Secret

3. Configure environment variables

cp .env.example .env

Edit .env with your credentials:

SPOTIPY_CLIENT_ID=your_spotify_client_id
SPOTIPY_CLIENT_SECRET=your_spotify_client_secret
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback
SWEEPIFY_LLM_PROVIDER=bedrock   # or "anthropic"
ANTHROPIC_API_KEY=               # only if using anthropic provider

Usage

Full pipeline

uv run sweepify run

This runs all three steps in sequence: fetch, classify, and create playlists.

Target a specific playlist

uv run sweepify run -p "My Playlist"

Individual commands

uv run sweepify fetch      # Fetch liked songs from Spotify
uv run sweepify classify   # Classify songs using Claude
uv run sweepify create     # Create Spotify playlists
uv run sweepify status     # Show song and classification counts
uv run sweepify reset      # Clear classifications (keeps songs)
uv run sweepify clear      # Remove sweepify playlists from Spotify + reset

Genre-based playlists

Create playlists from songs matching specific genres:

uv run sweepify playlist -g "lo-fi house, minimal techno"             # Claude picks the name
uv run sweepify playlist -g "corrido, banda" --name "Corridos Mix"    # custom name
uv run sweepify playlist -g "latin, reggaeton" -n 3                   # split into 3 playlists

Use -n 0 with run or classify to classify songs only into existing sweepify playlists:

uv run sweepify run -n 0

Database explorer

Browse your songs, explore genre breakdowns, build playlist commands, and run ad-hoc SQL queries in an interactive Streamlit UI:

uv run --group ui sweepify ui

The Playlist Builder tab lets you select genres, preview matching songs, and generates the CLI command to run.

First run

On your first run, a browser window will open for Spotify authorization. Grant the requested permissions and you'll be redirected back. The auth token is cached locally for subsequent runs.

Configuration

Variable	Default	Description
SPOTIPY_CLIENT_ID		Spotify app client ID
SPOTIPY_CLIENT_SECRET		Spotify app client secret
SPOTIPY_REDIRECT_URI	http://127.0.0.1:8888/callback	OAuth redirect URI
SWEEPIFY_LLM_PROVIDER	bedrock	LLM provider: bedrock or anthropic
ANTHROPIC_API_KEY		Anthropic API key (only for anthropic provider)
SWEEPIFY_PLAYLIST_PREFIX	sweepify:	Prefix for created playlist names
SWEEPIFY_DB_DIR	~/.sweepify	Directory for the local SQLite database

How it works

1. Fetch — Retrieves all Liked Songs (or a specific playlist) via the Spotify API with pagination, enriches them with artist genre data, and stores everything in a local SQLite database.
2. Classify — Sends unclassified songs (in batches of ~100) to Claude, which groups them into 5-15 categories based on genre, mood, and thematic coherence. Categories stay consistent across batches. Progress is saved after each batch so you can resume if interrupted.
3. Create — Creates private Spotify playlists for each category and adds the songs. Re-running is safe: existing playlists are reused, and already-classified songs are skipped.

Development

uv run pytest           # Run tests
uv run ruff check .     # Lint
uv run ruff format .    # Format
uv sync --group ui      # Install UI dependencies (Streamlit, Plotly)