Refactor Candidate Resolution into `Candidates` Collections
- 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
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