feat: semisupervised-v2 — constrained average-linkage grouping (ADR 0104) #1035
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/semisupervised-v2-average-linkage"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What
Implements ADR 0104 (accepted 2026-10-05): a new opt-in clustering method
semisupervised-v2— constrained standard HAC average linkage replaces v1's greedy complete-linkage clique growth.semisupervised-v1stays byte-unchanged; the default method staysconstrained-dbscan. Zero behavior change unless an owner switches their people domain tosemisupervised-v2(admin UI → discovery domain → clustering method).Design invariants (from ADR 0104)
clusteringContractVersionstays 1 for both methods; no DB migration; same candidate shapes, same ADR 0103 qualityScore, same A/B/C gates.Implementation
Worker (
workers/people):hac_linkage.py(new): reference HAC partition (experiment-validated semantics: global best-first merge, mean of ALL cross-pairs, smallest-index tie break, full matrix, hard member cap) + productionpartition_hac_components— exact connected-component decomposition of the threshold graph (all cross-component pairs exceed the threshold, so the reference could never merge across components). Fail closed: a component above the member cap (512 deployed / 768 in dev checkouts with the experiment harness) aborts the run withComponentTooLargeError— no silent degradation (tracked as ISSUE-100; D4 scalable-exact algorithm is future work).clustering.py: emission block extracted verbatim into shared_emit_group_candidates; v1 refactored onto it with behavior identical (all golden tests untouched and passing);_semisupervised_v2_candidatesreuses the entire v1 outer loop (model-pair partitioning, run-global face ownership, dedup) and swaps only group formation. Candidates stampedclusteringMethod=semisupervised-v2, version 1.main.py: v2 rides the v1 contract-version gate (v1+v2 @ version 1); explicit v2 job with wrong/missing version still fails the job.Core (
apps/api): v2 routes to the same semisupervised processing mode; envelope validation matches the payload's expected method (v1 or v2) against the same version; enqueue snapshotsclusteringContractVersion=1+maxDistancefor both; method allowlist extended.Web (
apps/web):semisupervised-v2option in the admin clustering-method select; the distance control shows for either semisupervised method.Verification
:apps:api:testfull suite green; web vitest 65 passed; svelte-check 0 errorsclustering_max_distance(default 0.35) — recalibration is deliberately out of scope (ADR 0104 D2)Meta
accepted(user approval in session)