refactor: optimize to single averaged vector, remove unused models, and rename delete route

- Use Cases (attendees.py): Modified EncodeAttendeeUseCase to average 9 augmented encodings using numpy.mean(axis=0) and return a single List[float]. Updated SortAttendeeUseCase to receive and pass the single attendee_encoding.
- Repository: Simplified find_matches to accept encoding: List[float] and perform a direct pgvector <=> comparison. Removed the dead get_closest_matches_debug method entirely.
- Routers & Schemas (attendees.py, schemas.py): Updated FastAPI endpoints and DTOs to return/receive List[float] (single vector) instead of nested arrays.
- Domain: Removed the unused AttendeeProfile model that referenced List[List[float]].
- Events API: Renamed /delete-event-table route to /delete-event-data. Propagated the naming shift across the application by renaming DeleteEventTableUseCase to DeleteEventDataUseCase and updating the corresponding schemas and DI container.
- Chore: Added missing type hints to completed_tasks in background_tasks.py.
- Docs: Corrected Markdown formatting and updated data flow diagrams in workflows.md.

Author: Avneesh11905

main_api/application/dtos.py

@@ -29,7 +29,7 @@ class EncodedCountDTO:
 
 
 @dataclass
-class DeleteTableDTO:
+class DeleteDataDTO:
     success: bool
     message: Optional[str] = None
     table_name: Optional[str] = None

main_api/application/ports/repository.py

@@ -1,4 +1,4 @@
-from typing import List, Set, Dict, Any, Protocol
+from typing import List, Set, Protocol
 from application.dtos import EventEncodingDTO
 
 
@@ -21,13 +21,7 @@ async def delete_event_data(self, event_code: str) -> None:
     async def find_matches(
         self,
         event_code: str,
-        encodings: List[List[float]],
+        encoding: List[float],
         threshold: float,
-        min_matches: int,
     ) -> List[str]:
         pass
-
-    async def get_closest_matches_debug(
-        self, event_code: str, encodings: List[List[float]], limit: int = 5
-    ) -> List[Dict[str, Any]]:
-        pass

main_api/application/use_cases/attendees.py

@@ -1,3 +1,4 @@
+import numpy as np
 from typing import List
 import asyncio
 from application.ports.inference import IInferenceService
@@ -21,7 +22,7 @@ def __init__(
         self.inference_service = inference_service
         self.augmenter = augmenter
 
-    async def execute(self, attendee_images_base64: List[str]) -> List[List[float]]:
+    async def execute(self, attendee_images_base64: List[str]) -> List[float]:
         if len(attendee_images_base64) != 3:
             raise InvalidReferenceImagesError(
                 "Must provide exactly 3 attendee images (front, left, right)."
@@ -43,20 +44,19 @@ async def execute(self, attendee_images_base64: List[str]) -> List[List[float]]:
                 "Could not detect clear faces in the provided and augmented reference images."
             )
 
-        return embeddings_list
+        avg_embedding = np.mean(embeddings_list, axis=0).tolist()
+        return avg_embedding
 
 
 class SortAttendeeUseCase:
     def __init__(self, uow: IUnitOfWork):
         self.uow = uow
 
     async def execute(
-        self, event_code: str, attendee_encodings: List[List[float]]
+        self, event_code: str, attendee_encoding: List[float]
     ) -> AttendeeSortDTO:
-        if len(attendee_encodings) == 0:
-            raise InvalidReferenceImagesError(
-                "Must provide at least one attendee encoding."
-            )
+        if not attendee_encoding:
+            raise InvalidReferenceImagesError("Must provide a valid attendee encoding.")
 
         async with self.uow as uow:
             has_data = await uow.event_repo.check_event_has_data(event_code)
@@ -67,9 +67,8 @@ async def execute(
 
             matched_paths = await uow.event_repo.find_matches(
                 event_code,
-                attendee_encodings,
+                attendee_encoding,
                 settings.SIMILARITY_THRESHOLD,
-                settings.MIN_MATCHES,
             )
 
         if not matched_paths:

main_api/application/use_cases/background_tasks.py

@@ -158,7 +158,8 @@ async def execute(
             task_ids.append(tid)
 
         import asyncio
-        completed_tasks = set()
+
+        completed_tasks: set[str] = set()
         while len(completed_tasks) < len(task_ids):
             for tid in task_ids:
                 if tid not in completed_tasks:
@@ -168,8 +169,12 @@ async def execute(
 
             processed_batches = len(completed_tasks)
             processed_images = min(processed_batches * batch_size, total_images)
-            pct = int((processed_images / total_images) * 100) if total_images > 0 else 100
-            
+            pct = (
+                int((processed_images / total_images) * 100)
+                if total_images > 0
+                else 100
+            )
+
             update_state_cb(
                 "PROCESSING",
                 {

main_api/application/use_cases/events.py

@@ -1,6 +1,6 @@
 from application.ports.queue import ITaskQueueService
 from application.ports.uow import IUnitOfWork
-from application.dtos import EncodedCountDTO, DeleteTableDTO
+from application.dtos import EncodedCountDTO, DeleteDataDTO
 
 
 class StartEventEncodingUseCase:
@@ -40,15 +40,15 @@ async def execute(self, event_code: str) -> EncodedCountDTO:
             return EncodedCountDTO(encoded_count=count, table_exists=True)
 
 
-class DeleteEventTableUseCase:
+class DeleteEventDataUseCase:
     def __init__(self, queue_service: ITaskQueueService):
         self.queue_service = queue_service
 
     async def execute(
         self, event_code: str, event_id: str | None = None
-    ) -> DeleteTableDTO:
+    ) -> DeleteDataDTO:
         self.queue_service.enqueue_delete_event(event_code, event_id)
-        return DeleteTableDTO(
+        return DeleteDataDTO(
             success=True,
             message=f"Enqueued deletion task for event '{event_code}'.",
         )

main_api/domain/models.py

@@ -15,11 +15,6 @@ class MatchResult:
     best_distance: float
 
 
-@dataclass
-class AttendeeProfile:
-    encodings: List[List[float]]
-
-
 @dataclass
 class Event:
     folder_path: str

main_api/infrastructure/database/repository.py

@@ -8,15 +8,11 @@
     delete,
     func,
     literal_column,
-    values,
-    column,
-    Integer,
-    String,
     cast,
     Float,
 )
 from pgvector.sqlalchemy import Vector
-from typing import List, Set, Dict, Any
+from typing import List, Set
 import dataclasses
 
 
@@ -64,72 +60,23 @@ async def delete_event_data(self, event_code: str) -> None:
     async def find_matches(
         self,
         event_code: str,
-        encodings: List[List[float]],
+        encoding: List[float],
         threshold: float,
-        min_matches: int,
     ) -> List[str]:
-        ref_encodings = (
-            values(
-                column("id", Integer), column("embedding", String), name="ref_encodings"
-            )
-            .data([(i + 1, str(emb)) for i, emb in enumerate(encodings)])
-            .cte("ref_encodings")
-        )
-
         distance_op = EventEncodingModel.embedding.op("<=>", return_type=Float())(
-            cast(ref_encodings.c.embedding, Vector(512))
+            cast(str(encoding), Vector(512))
         )
 
         stmt = (
             select(
                 EventEncodingModel.image_path,
-                func.count(ref_encodings.c.id).label("match_count"),
                 func.min(distance_op).label("best_distance"),
             )
-            .join(ref_encodings, literal_column("true"))
             .where(EventEncodingModel.event_code == event_code, distance_op < threshold)
             .group_by(EventEncodingModel.image_path)
-            .having(func.count(ref_encodings.c.id) >= min_matches)
-            .order_by(
-                literal_column("match_count").desc(),
-                literal_column("best_distance").asc(),
-            )
+            .order_by(literal_column("best_distance").asc())
         )
 
         result = await self.session.execute(stmt)
         rows = result.all()
         return [row[0] for row in rows]
-
-    async def get_closest_matches_debug(
-        self, event_code: str, encodings: List[List[float]], limit: int = 5
-    ) -> List[Dict[str, Any]]:
-        ref_encodings = (
-            values(
-                column("id", Integer), column("embedding", String), name="ref_encodings"
-            )
-            .data([(i + 1, str(emb)) for i, emb in enumerate(encodings)])
-            .cte("ref_encodings")
-        )
-
-        distance_op = EventEncodingModel.embedding.op("<=>", return_type=Float())(
-            cast(ref_encodings.c.embedding, Vector(512))
-        )
-
-        stmt = (
-            select(
-                EventEncodingModel.image_path,
-                func.count(ref_encodings.c.id).label("match_count"),
-                func.min(distance_op).label("best_distance"),
-            )
-            .join(ref_encodings, literal_column("true"))
-            .where(EventEncodingModel.event_code == event_code)
-            .group_by(EventEncodingModel.image_path)
-            .order_by(literal_column("best_distance").asc())
-            .limit(limit)
-        )
-
-        result = await self.session.execute(stmt)
-        return [
-            {"image_path": row[0], "match_count": row[1], "best_distance": row[2]}
-            for row in result.all()
-        ]

main_api/infrastructure/di_container.py

@@ -3,7 +3,7 @@
     StartEventEncodingUseCase,
     CheckEncodingStatusUseCase,
     GetEncodedCountUseCase,
-    DeleteEventTableUseCase,
+    DeleteEventDataUseCase,
 )
 from application.use_cases.attendees import (
     EncodeAttendeeUseCase,
@@ -84,8 +84,8 @@ class Container(containers.DeclarativeContainer):
 
     get_encoded_count_use_case = providers.Factory(GetEncodedCountUseCase, uow=uow)
 
-    delete_event_table_use_case = providers.Factory(
-        DeleteEventTableUseCase, queue_service=queue_service
+    delete_event_data_use_case = providers.Factory(
+        DeleteEventDataUseCase, queue_service=queue_service
     )
 
     encode_attendee_use_case = providers.Factory(

main_api/infrastructure/storage/minio_service.py

@@ -76,7 +76,11 @@ async def create_zip_from_images(
     ) -> None:
         session = self._get_session()
         total = len(image_paths)
-        s3_config = Config(signature_version="s3v4", max_pool_connections=10, retries={"max_attempts": 0})
+        s3_config = Config(
+            signature_version="s3v4",
+            max_pool_connections=10,
+            retries={"max_attempts": 0},
+        )
 
         with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
             tmp_path = tmp.name

main_api/presentation/api/routers/attendees.py

@@ -29,10 +29,10 @@ async def encode_attendee(
         Provide[Container.encode_attendee_use_case]
     ),
 ):
-    embeddings_list = await use_case.execute(request.attendee_images_base64)
+    encoding = await use_case.execute(request.attendee_images_base64)
     return EncodeAttendeeResponse(
-        message=f"Successfully generated {len(embeddings_list)} encodings from 3 reference images.",
-        encodings=embeddings_list,
+        message="Successfully generated 1 averaged encoding from 3 reference images.",
+        encoding=encoding,
     )
 
 
@@ -42,7 +42,7 @@ async def sort_event_attendee(
     request: SortAttendeeRequest,
     use_case: SortAttendeeUseCase = Depends(Provide[Container.sort_attendee_use_case]),
 ):
-    dto = await use_case.execute(request.event_code, request.attendee_encodings)
+    dto = await use_case.execute(request.event_code, request.attendee_encoding)
     return AttendeeSortResponse(**dataclasses.asdict(dto))