Autotagger Refactor: Unify Album and Singleton Matching Flows
- Dominant language
- Python
- Stars
- 15.7k
- Forks
- 2.1k
- Avg merge
- 4d 21h
- Merged PRs (30d)
- 31
Description
## Summary
The autotagger currently has separate matching paths for albums and singletons, with duplicated orchestration logic spread across matching, candidate lookup, and importer session flow.
This refactor series unifies both paths under a shared model:
- `Source` encapsulates search context and current metadata origin.
- `Candidates` encapsulates candidate discovery, deduplication, and recommendation logic.
- `Match` subclasses encapsulate validation and match construction.
- `ImportTask` is split into clear album and singleton task variants with explicit responsibilities.
The goal is to make behavior consistent between album and singleton imports, reduce duplication, and simplify importer architecture with stronger typing and clearer ownership.
## Motivation
- Reduce duplicate logic between album and singleton tagging paths.
- Keep recommendation and candidate lifecycle behavior consistent.
- Make importer/session code operate on one conceptual model (`source`, `candidates`, `match`) regardless of item type.
- Replace mixed importer task responsibilities with a clean album/singleton split.
## Scope
- Introduce shared source context abstraction.
- Move candidate collection and recommendation behavior into dedicated candidate containers.
- Move match validation/construction into `Match` subclasses.
- Update importer/session flows to use the shared abstractions.
- Split importer task responsibilities into explicit album and singleton task types.
## Out of Scope
- New user-facing autotagger features.
- Plugin API redesign beyond compatibility-preserving adjustments required by refactor.
## Deliverables
- [ ] `Source` introduced and integrated in importer candidate lookup.
- [ ] Candidate orchestration moved to `Candidates` classes.
- [ ] Album/singleton importer session paths consume shared candidate interface.
- [ ] Importer task architecture split between album and singleton flows.
## Risks
- Subtle behavior drift in recommendation thresholds/order.
- Plugin hooks depending on old internals.
- Transition churn while importer task hierarchy is reshaped.
## Validation
- Existing autotagger/importer test suite passes.
- Targeted tests verify equivalent behavior for album and singleton candidate resolution.
- No regression in manual search/manual ID flow.
- Importer task tests verify album and singleton flows through distinct task types.
Contributor guide
Research direction
Start by reading the existing album and singleton matching, candidate lookup, and importer/session flows described in the issue, then trace how their responsibilities overlap. Review the autotagger/importer test suite and targeted album and singleton resolution tests before changing architecture. Done means both flows use the shared abstractions, distinct importer task types work, and existing behavior including manual search and manual ID flow remains covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100