Philip Guzman
1.1 KiB
Explainable Matching Engine
Problem
Missing references need ranked candidate files, but a filename-only yes/no check cannot explain ambiguity or cloud-provider conflict names.
Architecture
The read-only matching engine indexes normalized filenames and scores only related candidates. Every score contains evidence for filename, extension, and parent folder. Exact filenames earn 60 points, normalized names 55, numeric conflict-name matches 50, extensions 10, and parent folders 20.
The displayed percentage is an evidence score, not a statistical probability. Metadata, duration, hashes, and fingerprints can add stronger evidence later.
Edge Cases
- Unicode and case differences.
- OneDrive-style names such as
Track 2.mp3. - Duplicate candidates in different folders.
- Legitimate numbered song titles, which remain candidates but are never repaired.
- Unrelated names, which are not emitted as candidates.
Verification
Tests cover exact, normalized, conflict-suffix, ambiguous, and unrelated filenames. Candidate ordering is deterministic. The engine never changes a track or reference.