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:

Extract image path from user input or recent logs (look for patterns like Resolved relative path: "media/inbound/images/xxx.jpg")
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:

Query face analysis message with image path: MEDIA:/path/to/query.jpg
List of matching images with similarity scores
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"

Extract query image path from logs (or use most recent image from media/inbound/images)
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
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