ADR 0118 per face age & gender estimation (genderage_v2), birth year person profiles, conservative generation gap suggestion gate
Forgejo Actions edited this page 2026-11-01 07:14:57 +00:00
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

ADR 0118: Per-face age & gender estimation (MiVOLO v2, rev — supersedes genderage_v2 choice), birth-year person profiles, conservative generation-gap suggestion gate

Status: accepted Date: 2026-10-29 Supersedes: 0118 (2026-10-29 original: genderage_v2)

Context

CONTEXT: First-degree relatives (grandfather/grandson, father/son) are genuinely close in arcface embedding space — face geometry is heritable. Production incident 2026-10-29: Papa faces (grandfather) suggested as Holger (grandson) at distance 0.31-0.38, numerically inside the suggest band; visual identity clearly distinct. No embedding-threshold mechanism can separate relatives. InsightFace genderage_v2 (ONNX, 1.3 MB, same aligned 112x112 input as the shipped w600k arcface model) estimates age (MAE ~7.5 y per single face) and binary gender in one tiny inference. Age + capture timestamp implies birth year; a person's implied birth year aggregated over many faces concentrates well below 1 year of error (median over hundreds of faces, library spans 10+ years).

DECISION: V1 — Data collection (dark, additive): the people worker runs genderage_v2 on every aligned face crop during detect+embed and ships {ageEstimate (float years), gender ("male"|"female"|"unknown"), ageModelName, ageModelVersion} as ADDITIVE per-face fields on the ML result envelope. Core validates fail-open (fields optional; absent = old worker, no error) and persists them inside the face annotation discovery_results payload. No schema migration. A backfill job (owner_face_attribute_backfill) re-infers existing faces. V2 — Birth-year profiles (read-side only): per person, implied birth year per face = capture_timestamp.year − ageEstimate; profile = median + quartiles over accepted faces, computed API/worker-side on demand. Faces without capture timestamps or age are excluded; profiles below a minimum face count (default 3) are "unknown" and never gate. V3 — Generation-gap SUGGEST gate only (no grouping change): when scoring cluster_person_match candidates, if the candidate faces' median implied birth year lies OUTSIDE the target person's profile interval widened by the generation margin (default 15 years), the card is demoted to review-only (ambiguous=true) or suppressed from the suggest band; distance/confidence fields stay raw. This runs AFTER grouping — the density graph, HAC and contract versions (ADR 0104/0113) are untouched; no new clustering method; v1/v2/v3 stay byte-identical; the gate is an envelope+post-processing property with its own operator flag (discovery_domains generation_gate_enabled, default off) and CV-calibrated threshold. REJECTED ALTERNATIVE: cannot-link edges between generation-disjoint persons in the ADR 0113 density graph. Rejected on ADR 0116 evidence: graph/edge-set semantics changes alter grouping, candidate keys and churn and force a contract-version bump; the complaint class (wrong SUGGESTIONS for relatives) is fully addressed post-grouping at a fraction of the risk. Grouping changes remain future work if CV shows residual need.

HONEST LIMITS: MAE 7.5 y per single face — per-face age is a weak signal; only aggregated profiles gate, never single faces. Children drift the models (kids age fast, training bias) — gate margins must absorb this. Gender is binary per model and is collected but NOT used for gating initially. Gate margins are CV-measured on the owner library before enabling (ADR 0116 discipline); until then the flag stays off and nothing changes behaviorally.

REVISION 2026-10-31 (T006, A/B-driven): Measured on the operator's real library (owner-provided ground-truth birth years, EVALUATION ONLY), genderage_v2 exhibits severe regression-to-mean: a 9-year-old reads median 33 (+24y), a 67-year-old reads 40 (−27y), a 103-year-old reads 43 — absolute implied birth years are unusable for the V3 gate. A 3-model A/B over 211 sampled faces per the same crops compared genderage_v2, MiVOLO v2 (official PyTorch and a self-exported ONNX) and FaceAge ClientScan (DINOv3 ViT-L fp16): MiVOLO v2 median reads land within ±8.5y for adults/elderly and ±4y for the child; FaceAge was marginally more accurate but 5x the RAM (612MB fp16 vs 117MB) and ~30% slower per face — MiVOLO v2 selected. The self-exported ONNX (opset 18, fixed batch=1, both heads) was verified bit-identical to the official PyTorch model on the A/B corpus (max Δage 3.8e-05y, gender identical). Genderage's gender argmax convention is flipped in MiVOLO (0=male,1=female) — covered by tests. License: MiVOLO v2 weights released on HF by the first author labeled Apache-2.0 (GitHub repo shows a contradictory CC-BY-NC-SA setup.py marker, open issue #59/#62); Memories bundles nothing — operator-placed artifact via MEMORIES_FACE_AGE_MODEL_PATH, same fail-open mechanics as before. V3 gate calibration now proceeds against MiVOLO-based reads (self-referential bands optional; absolute reads are plausible again).

REVISION 2026-10-31 (second revision, S068T008 — demotion replaced by PARTITION/SUPPRESS per owner decision): ambiguous review-only cards delegate the review work back to the owner, so they are not useful; the owner wants high-quality suggestions only. The V3 mint-time gate over targeted cluster_person_match cards no longer DEMOTES. Instead: (1) PARTITIONER — a mixed candidate (some faces inside, some outside the target's widened interval) is minted with ONLY the fitting faces; the violating faces stay OUT of the card (unlabeled in the pool, available for future correct cards) and the minted card is a normal, non-ambiguous card; a face WITHOUT a usable birth year (no capture year or no numeric ageEstimate) is INERT and always stays — missing data never shrinks cards; the per-face decision replaces the card-median (each face's implied birth year is compared individually against the interval, inclusive edges). (2) SUPPRESSOR — a fully-inconsistent candidate (all usable faces violate, nothing inert to keep) is NOT minted at all (INFO-log skip, same shape as the rejected-targeted-pair suppression): this unblocks correct replacement cards instead of blocking them via the spec-047 pending-overlap guard (the William→Alice stale-card class). The gate runs BEFORE the mint-time pending-overlap guard so the guard sees partitioned refs. (3) The end-of-run backlog arm keeps its median-based semantics but loses the sticky-demotion exemption — there is no demotion anymore, so no pending card carries a legitimate review stamp to spare. The margin stays the one global constant (15.0 years) and the fail-open contract is unchanged: any exception = no gating. Migration note: the generation_gate_enabled flag was OFF in production when this shipped (verified 2026-10-31, all discovery_domains rows false), so no live demoted cards exist and no data migration is needed. CALIBRATION (T006 A/B, owner library, owner-provided ground-truth birth years, EVALUATION ONLY): owner-library person medians land within ±6 years of truth across the sampled age range (child ~5–7y, adults, elderly) after the MiVOLO v2 swap — enough headroom for the 15-year generation margin to separate relatives without eating correct suggestions.