beetbox / beetbox/beets

Refactor Candidate Resolution into `Candidates` Collections

Open
#6,685 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
15.7k
Forks
2.1k
Avg merge
4d 21h
Merged PRs (30d)
31

Description

## Summary
Refactor album and singleton candidate handling into dedicated `Candidates` collection types that share orchestration behavior.

This includes:
- owning candidate storage keyed by provider+id
- deduplication
- sorting by distance
- recommendation calculation
- search orchestration (`resolve`, `search_ids`, `search`, fallback strategy)

## Why
- Replace separate `tag_album` / `tag_item` orchestration with one pattern.
- Keep recommendation logic in one place.
- Let importer/session interact with a unified API (`task.candidates`).

## Scope
- Introduce base `Candidates` collection contract.
- Implement `AlbumCandidates` and `TrackCandidates` provider-specific fetch hooks.
- Move recommendation logic into `Candidates.recommendation`.
- Update manual search/manual ID flows to mutate and reuse the same candidate collection.

## Acceptance Criteria
- [ ] `task.lookup_candidates(...)` delegates to `task.candidates.resolve(...)`.
- [ ] Manual search/manual ID reuse the same candidate collection object.
- [ ] Album and singleton candidate lists are sorted and deduplicated consistently.
- [ ] Recommendation behavior remains equivalent to previous thresholds/gap logic.
- [ ] Tests cover multi-source candidate dedup/sorting for album and singleton paths.

Contributor guide

Open the contributing guide

Research direction

Start by locating the existing tag_album and tag_item orchestration, then trace task.lookup_candidates and the current manual search and manual ID flows. Compare their candidate storage, deduplication, sorting, recommendation thresholds, and fallback behavior before defining the shared Candidates contract. Done means both album and singleton paths reuse one collection API and tests cover multi-source deduplication, sorting, and equivalent recommendations.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.