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

ADR 0093: Generic Class Instance Occurrence Embeddings

Status: proposed Date: 2026-07-09

Context

People face recognition uses a face_embeddings table coupled to face_annotations. To support merge suggestions for all discovery domains (plants, future domains) we need a domain-agnostic embedding storage. The embedding storage must support variable dimensions (face embeddings differ from plant embeddings), per-domain model versioning, and efficient similarity search within a domain+class+owner scope.

Decision

Create a single generic table class_occurrence_embeddings that stores embeddings as JSONB float arrays. Domain+class+owner keying replaces the old face-specific FK. Each row links to a class_instance_occurrence, not directly to a class_instance, allowing multiple embeddings per occurrence (e.g., different models). Embedding dimensions are stored explicitly alongside model_name and model_version. The table uses a GIN index on the JSONB embedding column for potential pgvector migration later, and a B-tree index on (domain_key, class_key, owner_id) for efficient scoped queries. This replaces the face-only face_embeddings table path. Existing face_embeddings rows are NOT migrated — the table is dropped in Spec 034.

Consequences

['JSONB embedding storage is less efficient than dedicated vector columns — acceptable at current scale (<10K embeddings per domain per owner). Can migrate to pgvector extension if performance becomes an issue.', 'Generic table enables merge suggestions for any domain: plants, animals, objects — any domain with an embedding model can participate.', 'face_embeddings table remains live until Spec 034 drops it, but no new code writes to it.', 'Embedding model registry (model_name + model_version) enables per-domain model evolution without schema changes.', 'JSONB array allows variable-dimension embeddings across domains (e.g., 128-dim faces, 512-dim plants).']