autonomous-ai Face Enroll
Manage faces for the device's face recognition system. Faces live under /root/local/users/<label>/. All enrolled persons are treated as friends — distinguished from stranger_* IDs the camera hasn't been told about yet.
Flow router — pick ONE per user message
| Flow | When | Detail |
|---|---|---|
| A — Self-enroll with a photo | User sends a photo of themselves + intro ("remember my face", "this is me"). | reference/self-enroll-photo.md |
| B — Self-enroll via camera capture | User asks to be remembered without sending a photo, on voice or Telegram text (assumes user is near the device). Examples: "remember my face", "I'm Gray", "capture and enroll me". Web chat without a photo → ask for a selfie (Flow A) instead. | reference/self-enroll-camera.md |
| C — Familiar-stranger prompt | Current sensing message contains HAL's hint (familiar stranger ... — seen N times, ask user if they want to remember this face; image saved at <path>), OR the user is replying to your previous prompt about that stranger. |
reference/familiar-stranger.md |
| M — Maintenance | "who do you recognize?", "forget my face", "reset faces". | reference/maintenance.md |
Disambiguation hints:
- Photo attached (
mediaPaths/[image: ...]) → Flow A. - No photo + HAL familiar-stranger hint in current message → Flow C.
- No photo + no hint, user wants to be remembered → Flow B.
- The user is naming a face you previously asked about (Flow C in progress) → continue Flow C.
- Pure read/delete intent → Flow M.
Common rules (apply across all enroll flows)
- Self-enrollment only. The person being enrolled must be the one identifying themselves: sender of the message in Flows A/B, the camera-person responding to the prompt in Flow C. Refuse third-party enrollment ("add my friend Bob").
- Confirm the name out loud before enrolling — Flows B and C only.
- Flow A: the user's own photo + intro IS the confirmation; don't ask redundantly.
- Flow B: read the name back in the same turn you snapshot ("Got it, saving you as Gray — hold still").
- Flow C: address the camera-person directly — "mind if I remember you? what's your name?" — and wait for the reply before calling
/face/enroll.
- Always confirm enrollment afterwards — tell the user the name was registered once
/face/enrollreturnsok. - Use lowercase labels — normalize names to lowercase. Use the SAME label as
speaker-recognizerfor the same person so/root/local/users/<label>/is shared. - Telegram identity rules:
- Flow A (photo on Telegram): include
telegram_username+telegram_id(required for DM targeting). - Flow A (photo on web chat): omit Telegram fields.
- Flow B (voice): omit. Flow B (Telegram text): include.
- Flow C: always omit — the camera-person isn't on Telegram (any Telegram metadata in context belongs to someone else, e.g. the owner overhearing).
- Flow A (photo on Telegram): include
- One photo per
/face/enrollcall. Multiple photos → call once per photo. - Never write files directly to
/root/local/users/. Always go through the HTTP API. - Don't expose technical details — say "I'll remember your face" not "base64-encoding the JPEG".
Tools (curl reference)
All HTTP calls go to http://127.0.0.1:5001.
# Enroll
curl -s -X POST http://127.0.0.1:5001/face/enroll \
-H "Content-Type: application/json" \
-d "{\"image_base64\": \"$(base64 -w0 /path/to/photo.jpg)\", \"label\": \"chloe\", \"telegram_username\": \"chloe_92\", \"telegram_id\": \"123456789\"}"
# Status
curl -s http://127.0.0.1:5001/face/status
# Remove one
curl -s -X POST http://127.0.0.1:5001/face/remove \
-H "Content-Type: application/json" \
-d '{"label": "chloe"}'
# Reset all
curl -s -X POST http://127.0.0.1:5001/face/reset
# Snapshot (for Flow B)
curl -s "http://127.0.0.1:5001/camera/snapshot?save=true"
Photo source by channel
| Channel | Where to read the path |
|---|---|
| Telegram (with photo) | mediaPaths in conversation context |
| Web chat (with image) | [image: /path/to/file] tag in message text |
| Voice / Telegram-text (Flow B) | path returned by GET /camera/snapshot?save=true |
| Familiar-stranger (Flow C) | <path> parsed from the HAL hint in the sensing message |
Error handling
- 503 from any face endpoint → recognizer is down (sensing not started). Tell the user face recognition is offline.
- 400 "image cannot be decoded" → bad base64 / corrupt file. Apologize, ask user to re-send (Flow A) or retry capture (Flow B).
- 400 "no face detected" → no face in the image. Apologize and either ask the user to face the camera (Flow B retry) or ask for a clearer photo (Flow A).
- 404 on
/face/remove→ that label isn't enrolled. Tell the user.