1 ADR 0044 people generic class occurrence
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0044: People as Generic Class-Occurrence Domain + Separate People Worker

Status: accepted Date: 2026-06-04

Context

The People pipeline currently uses two separate systems:

  1. Legacy face detection pipeline (face_detection → face_annotations → face_embeddings → class_instance_occurrences): A separate, non-discovery path that produces face annotations with bounding boxes and embeddings, then feeds them into the generic identity layer.

  2. Generic discovery platform (discovery_results → class_instances): The target architecture per ADR 0020, where all domains use the same pipeline.

The legacy face detection pipeline exists because when it was built, the generic discovery platform didn't support region markers (bounding boxes) or embeddings. Now that the platform has matured, the separation is arbitrary:

  • plants_image uses class_occurrence with whole_image_classifier — a worker classifies the whole image and submits results through the discovery pipeline.
  • people uses face_detection as a completely separate capability that bypasses the discovery pipeline entirely, even though face detection is conceptually just another class_occurrence domain where the "class" is "person" and the worker also produces bounding boxes and embeddings.

This creates several problems:

  • Two parallel systems for the same conceptual operation (detecting things in photos)
  • The ML worker carries face detection code that could be in a dedicated people worker
  • New domains that need region markers (plant detection, pet detection, object detection) would each need to build their own separate pipeline instead of reusing the discovery platform
  • The face_annotations and face_embeddings tables are tightly coupled to the face detection pipeline, making it hard to generalize

Decision

1. People becomes a generic class_occurrence domain

The people domain moves from the legacy face detection pipeline to the generic discovery platform:

Current:

face_detection job → face_annotations → class_instance_occurrences (manually linked)
owner_face_recognition job → face_embeddings → class_instances (manually linked)

Target:

discovery_people job → discovery_candidate (with bounding box + embedding payload)
  → Core validates against allowedClasses (person)
  → Core stores discovery_results
  → Class-instance promotion: discovery_results → class_instances (generic lifecycle)

The discovery result payload for people includes:

{
  "domainKey": "people",
  "schemaVersion": 1,
  "candidates": [
    {
      "classKey": "person",
      "confidence": 0.92,
      "scope": "region",
      "boundingBox": {"x": 0.1, "y": 0.2, "width": 0.3, "height": 0.4},
      "embedding": [0.01, 0.02, ...],
      "inferenceStrategy": "face_detector"
    }
  ]
}

2. Region markers and embeddings become first-class discovery concepts

The discovery platform gains support for:

  • scope: "region" — result includes a bounding box (x, y, width, height normalized to 0-1)
  • embedding — optional float array for similarity matching (face recognition, duplicate detection)

These are not face-specific — any domain can use region markers (plant detection, pet detection, object detection) or embeddings (visual similarity, duplicate detection).

3. Separate People Worker

A new workers/people/ worker replaces the face detection capabilities in the ML worker:

ML Worker (current) People Worker (target)
face_detection discovery_people with inferenceStrategy: "face_detector"
owner_face_recognition discovery_people with inferenceStrategy: "face_recognizer"

The ML worker retains only generic ML capabilities:

  • semantic_embedding
  • visual_concept_detection
  • album_shape_proposal_train
  • album_shape_proposal_score

4. Backward compatibility

During migration:

  • The face_annotations and face_embeddings tables remain readable but are no longer written to by the new pipeline
  • The legacy face_detection and owner_face_recognition capabilities remain available but are deprecated
  • The People Worker can run alongside the ML worker during transition
  • Once the People Worker is verified, the legacy capabilities are removed from the ML worker

Migration Path

Phase 1: People Worker (this ADR)

  • Create workers/people/ with discovery_people capability
  • Worker detects faces → submits discovery_candidate with bounding box + embedding
  • Core stores in discovery_results (existing generic table)
  • Existing face_annotations→class_instance_occurrences path continues to work

Phase 2: Discovery → Class-Instance Promotion

  • Generic promotion logic: discovery_results with classKey=person → class_instances
  • Replaces the manual linking in PeopleService
  • Auto-accept, merge/split, sharing all work through generic discovery lifecycle

Phase 3: Legacy Cleanup

  • Remove face_detection and owner_face_recognition from ML worker
  • Deprecate face_annotations and face_embeddings tables
  • All People data flows through generic discovery pipeline

Consequences

  • The discovery platform becomes the single pipeline for all recognition domains (plants, people, future pets/objects)
  • Region markers and embeddings are reusable for any domain, not just faces
  • The ML worker is simplified — it only handles generic ML tasks
  • The People Worker is domain-specific and can evolve independently
  • Existing People functionality is preserved during migration through backward-compatible coexistence