feat: Add excluded face management and filtering capabilities in Identify component

This commit introduces functionality to manage excluded faces within the Identify component. A new state variable is added to toggle the inclusion of excluded faces in the displayed results. The API is updated to support setting and retrieving the excluded status of faces, including a new endpoint for toggling the excluded state. The UI is enhanced with a checkbox for users to include or exclude blocked faces from identification, improving user experience. Additionally, the database schema is updated to include an 'excluded' column in the faces table, ensuring proper data handling. Documentation has been updated to reflect these changes.

src/web/api/faces.py

@@ -121,6 +121,7 @@ def get_unidentified_faces(
     tag_names: str | None = Query(None, description="Comma-separated tag names for filtering"),
     match_all: bool = Query(False, description="Match all tags (for tag filtering)"),
     photo_ids: str | None = Query(None, description="Comma-separated photo IDs for filtering"),
+    include_excluded: bool = Query(False, description="Include excluded faces in results"),
     db: Session = Depends(get_db),
 ) -> UnidentifiedFacesResponse:
     """Get unidentified faces with filters and pagination."""
@@ -172,6 +173,7 @@ def get_unidentified_faces(
         tag_names=tag_names_list,
         match_all=match_all,
         photo_ids=photo_ids_list,
+        include_excluded=include_excluded,
     )
 
     items = [
@@ -182,6 +184,7 @@ def get_unidentified_faces(
             face_confidence=float(getattr(f, "face_confidence", 0.0)),
             location=f.location,
             pose_mode=getattr(f, "pose_mode", None) or "frontal",
+            excluded=getattr(f, "excluded", False),
         )
         for f in faces
     ]
@@ -431,6 +434,23 @@ def get_face_crop(face_id: int, db: Session = Depends(get_db)) -> Response:
         )
 
 
+@router.put("/{face_id}/excluded", response_model=dict)
+def toggle_face_excluded(
+    face_id: int,
+    excluded: bool = Query(..., description="Set excluded status"),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Toggle excluded status for a face."""
+    face = db.query(Face).filter(Face.id == face_id).first()
+    if not face:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Face {face_id} not found")
+    
+    face.excluded = excluded
+    db.commit()
+    
+    return {"face_id": face_id, "excluded": excluded, "message": f"Face {'excluded' if excluded else 'included'} successfully"}
+
+
 @router.post("/{face_id}/unmatch", response_model=FaceUnmatchResponse)
 def unmatch_face(face_id: int, db: Session = Depends(get_db)) -> FaceUnmatchResponse:
     """Unmatch a face from its person (set person_id to NULL)."""

src/web/app.py

@@ -370,6 +370,50 @@ def ensure_photo_media_type_column(inspector) -> None:
         print("✅ Added media_type column to photos table")
 
 
+def ensure_face_excluded_column(inspector) -> None:
+    """Ensure faces table contains excluded column."""
+    if "faces" not in inspector.get_table_names():
+        print("ℹ️  Faces table does not exist yet - will be created with excluded column")
+        return
+
+    columns = {column["name"] for column in inspector.get_columns("faces")}
+    if "excluded" in columns:
+        print("ℹ️  excluded column already exists in faces table")
+        return
+    
+    print("🔄 Adding excluded column to faces table...")
+
+    dialect = engine.dialect.name
+
+    with engine.connect() as connection:
+        with connection.begin():
+            if dialect == "postgresql":
+                # PostgreSQL: Add column with default value
+                connection.execute(
+                    text("ALTER TABLE faces ADD COLUMN IF NOT EXISTS excluded BOOLEAN DEFAULT FALSE NOT NULL")
+                )
+                # Create index
+                try:
+                    connection.execute(
+                        text("CREATE INDEX IF NOT EXISTS idx_faces_excluded ON faces(excluded)")
+                    )
+                except Exception:
+                    pass  # Index might already exist
+            else:
+                # SQLite
+                connection.execute(
+                    text("ALTER TABLE faces ADD COLUMN excluded BOOLEAN DEFAULT 0 NOT NULL")
+                )
+                # Create index
+                try:
+                    connection.execute(
+                        text("CREATE INDEX idx_faces_excluded ON faces(excluded)")
+                    )
+                except Exception:
+                    pass  # Index might already exist
+    print("✅ Added excluded column to faces table")
+
+
 def ensure_photo_person_linkage_table(inspector) -> None:
     """Ensure photo_person_linkage table exists for direct video-person associations."""
     if "photo_person_linkage" in inspector.get_table_names():
@@ -482,6 +526,7 @@ async def lifespan(app: FastAPI):
         ensure_user_role_column(inspector)
         ensure_photo_media_type_column(inspector)
         ensure_photo_person_linkage_table(inspector)
+        ensure_face_excluded_column(inspector)
         ensure_role_permissions_table(inspector)
     except Exception as exc:
         print(f"❌ Database initialization failed: {exc}")

src/web/db/models.py

@@ -112,6 +112,7 @@ class Face(Base):
     roll_angle = Column(Numeric, nullable=True)
     landmarks = Column(Text, nullable=True)  # JSON string of facial landmarks
     identified_by_user_id = Column(Integer, ForeignKey("users.id"), nullable=True, index=True)
+    excluded = Column(Boolean, default=False, nullable=False, index=True)  # Exclude from identification
 
     photo = relationship("Photo", back_populates="faces")
     person = relationship("Person", back_populates="faces")
@@ -125,6 +126,7 @@ class Face(Base):
         Index("idx_faces_quality", "quality_score"),
         Index("idx_faces_pose_mode", "pose_mode"),
         Index("idx_faces_identified_by", "identified_by_user_id"),
+        Index("idx_faces_excluded", "excluded"),
     )
 
 

src/web/schemas/faces.py

@@ -51,6 +51,7 @@ class FaceItem(BaseModel):
     face_confidence: float
     location: str
     pose_mode: Optional[str] = Field("frontal", description="Pose classification (frontal, profile_left, etc.)")
+    excluded: bool = Field(False, description="Whether this face is excluded from identification")
 
 
 class UnidentifiedFacesQuery(BaseModel):

src/web/services/face_service.py

@@ -1223,6 +1223,7 @@ def list_unidentified_faces(
     tag_names: Optional[List[str]] = None,
     match_all: bool = False,
     photo_ids: Optional[List[int]] = None,
+    include_excluded: bool = False,
 ) -> Tuple[List[Face], int]:
     """Return paginated unidentified faces with filters.
 
@@ -1239,6 +1240,10 @@ def list_unidentified_faces(
     # Base query: faces with no person
     query = db.query(Face).join(Photo, Face.photo_id == Photo.id).filter(Face.person_id.is_(None))
     
+    # Filter by excluded status (exclude excluded faces by default)
+    if not include_excluded:
+        query = query.filter(Face.excluded == False)
+    
     # Tag filtering
     if tag_names:
         # Find tag IDs (case-insensitive)