Face Search

Search for similar faces in image directories using SophNet's face detection API.

Processing Mode

STRICT SERIAL PROCESSING ONLY - This skill must execute in a single, sequential operation:

• NO sub-tasks - Never spawn background sessions or use sessions_spawn
• NO task splitting - Process all images in one continuous run
• NO parallel execution - All face detection and comparison must be done serially
• Complete the entire search workflow before returning results to the user

Prerequisites

• Python packages: numpy, requests, sophnet-tools

Usage

When a user wants to search for faces:

1. Extract image path from user input or recent logs (look for patterns like Resolved relative path: "media/inbound/images/xxx.jpg")
2. Run the search using uv from /tmp to avoid workspace pyproject.toml conflicts:

uv run --with numpy --with requests --with sophnet-tools \
  python {baseDir}/scripts/face_search.py \
  --image_path /absolute/path/to/query.jpg \
  --search_image_path /absolute/path/to/search/folder \
  --threshold 0.4

Parameters

• --image_path: Query image containing the face to search for (required)
• --search_image_path: Directory to search for similar faces (required)
• --det-thr: Face detection threshold (default: 0.5)
• --threshold: Similarity threshold for matching (default: 0.4, range: 0.0-1.0)

Output

The script outputs:

1. Query face analysis message with image path: MEDIA:/path/to/query.jpg
2. List of matching images with similarity scores
3. Each result shows: MEDIA:/absolute/path/to/result.jpg

After the search completes, format the output as follows:

输入图片：
/path/to/query.jpg

搜索到 N 个相似人脸：
/absolute/path/to/result1.jpg (相似度: XX%)
/absolute/path/to/result2.png (相似度: XX%)
/absolute/path/to/result3.jpg (相似度: XX%)

Important:

• Always show absolute paths in the final list
• No image previews are displayed - only text results with similarity scores and paths
• Extract absolute paths from the script's MEDIA: output lines

Path Extraction

When users provide images through chat, look for log patterns like:

Resolved relative path: "media/inbound/images/xxx.jpg" -> "/absolute/path/to/workspace/media/inbound/images/xxx.jpg"

Extract the absolute path (right side of ->) for use with the script.

Example Workflow

User: "Find photos with this person in my vacation folder"

1. Extract query image path from logs (or use most recent image from media/inbound/images)
2. Run: uv run --with numpy --with requests --with sophnet-tools python /path/to/face_search.py --image_path /path/to/query.jpg --search_image_path /path/to/vacation --threshold 0.4
3. Display the results:
   • Show text results with similarity scores and absolute paths
   • Format like:

     /path/to/result1.jpg (相似度: 57.61%)
     /path/to/result2.jpg (相似度: 54.94%)
     

Notes

• Always use absolute paths for reliability
• Lower threshold (e.g., 0.3) finds more matches but may include false positives
• Higher threshold (e.g., 0.7) is more strict but may miss some matches
• The script caches embeddings as JSON files to speed up repeated searches

⚠️ FORBIDDEN OPERATIONS

Do NOT:

• Spawn sub-agent sessions (sessions_spawn)
• Run multiple parallel face searches
• Split the task into separate operations
• Use background processes for face search

ONLY:

• Run the face_search.py script once with all required parameters
• Process all results in sequence
• Return complete results to the user in a single response