re-com: Skill for Claude Code

These are offline maintenance scripts (README.md "Setup", PLAN.md §7.4), run by hand from the command line. They are not part of the live tool-call path. Full first-time setup takes roughly 45 minutes; most of that is the atlas crawl in step 1.

Use .venv/bin/python, not python — the deps are in the venv. (Its console scripts such as .venv/bin/pytest may carry a stale shebang from an earlier project name; .venv/bin/python -m pytest works regardless.)

Credentials differ per script — check before running

v6 moved some of these onto the provider.Provider seam and left others on ytmusicapi deliberately. The seam scripts reach the account through the ytmusic-mcp subprocess, so they need it pointed out to them in the environment, and crash on startup without it:

RuntimeError: ytmusic-mcp is not configured. Set RECOM_YTMUSIC_MCP_COMMAND ...

script	how it reaches the account
build_atlas.py	ytmusicapi directly, RECOM_AUTH_PATH (default headers_auth.json)
build_genres.py	ytmusicapi directly, RECOM_AUTH_PATH
build_tempo.py	neither — store + Deezer's public API only
build_graph_atlas.py	neither — Deezer + the store (propagate is store-side)
label_library.py	Provider seam → needs the env below
snapshot_history.py	Provider seam → needs the env below
quality_check.py	Provider seam → needs the env below

The values are whatever the re-com MCP server is already configured with in ~/.claude.json (mcpServers.re-com.env) — read them from there rather than guessing:

export RECOM_YTMUSIC_MCP_COMMAND=/path/to/ytmusic-mcp/.venv/bin/python
export RECOM_YTMUSIC_MCP_ARGS=/path/to/ytmusic-mcp/server.py
export YTMUSIC_AUTH_PATH=/path/to/ytmusic-mcp/headers_auth.json

For Spotify it is the RECOM_SPOTIFY_MCP_* pair plus RECOM_PROVIDER=spotify, from mcpServers.re-com-spotify.env.

Order matters — run in this sequence

# (prefix the Provider-seam scripts with the env above)
# 1. Crawl YouTube's editorial mood atlas (~35 min, resumable, safe to interrupt)
.venv/bin/python scripts/build_atlas.py

# 2. Label your library from that atlas + artist propagation (needs only YouTube Music creds)
.venv/bin/python scripts/label_library.py

# 3. Genre/language labels, for the language filter (~10-15 min)
.venv/bin/python scripts/build_genres.py

# 4. Tempo/BPM, from Deezer's public API (~0.4s per song)
.venv/bin/python scripts/build_tempo.py

# 5. Optional: cross-backend mood corpus via Deezer playlist search (works on any backend)
.venv/bin/python scripts/build_graph_atlas.py

# 6. Optional: have Claude read lyrics to cover what the atlas missed (needs an API key)
pip install -e ".[llm]"
.venv/bin/python scripts/label_library.py --claude