---
title: People and relationships
summary: The faces GroundSlate knows, the names on them, and how the people are related, so an agent can tell who is who.
eyebrow: Capabilities
accent: wave
order: 5
outcome: people
---

## People and faces

| Tool | What it does |
| --- | --- |
| `detect_people` | Find the distinct people in a video and match them against your face catalog |
| `recognize_media` | Run face recognition on a file downloaded with `fetch_asset`, which arrives with recognition off |
| `enroll_face` | Add another reference face (a new angle or light) to a known person to improve recognition |
| `name_person` | Name a person, or correct their name |
| `rename_person` | Correct a person's name everywhere at once: shot descriptions, the Summary tab and search results update instantly, with no re-analysis |
| `add_person` | Add a named person to the catalog |
| `get_person` | One person's full record by id (`p394`): name, title, note, sex, how many videos they appear in, and the list of appearances |
| `list_people` | Every known person, named or not, with how often and where they appear |
| `person_candidates` | Ranked named people someone might actually be, for "this is someone else, who?" |
| `person_faces` | See a person's faces as cropped pictures. For where a face sits in the frame, use `people_sheet` |
| `person_locations` | See where a person's footage was filmed, by GPS |
| `person_members` | See which face sources were merged into a person, as in "Faces in this record" |
| `confirm_people` | Confirm the people in a video, which `index_video` waits for |
| `confirmation_queue` | People recognition was not sure about, strongest suggestion first |
| `merge_people` | Merge two entries that are the same person |
| `merge_people_bulk` | Merge many entries into one person in a single call, for someone split across many Unknowns after indexing |
| `consolidate_faces` | For each named person, gather up the Unknown cards that are really them |
| `recluster_identities` | Reset and regroup the face catalog, splitting a wrongly merged group back into separate people |
| `recluster_residue` | Find clips whose shots still name someone who, after `recluster_identities(apply=True)`, is no longer in them |
| `rebuild_exemplars` | Move known people onto a new recognition model without re-indexing |
| `rebuild_face` | Recreate a person's missing face picture without re-scanning the clip, for a person showing a blank silhouette |
| `claim_clip_face` | Assign an Unknown face in one clip to a known person |
| `ghost_clip_face` | Hide an Unknown face in one clip (Ghost, in Review faces) |
| `list_ghosts` | Ghosted or forgotten people who can be restored, as on the People page's Ghosts tab |
| `not_a_face` | Mark a detection as not a face at all (jeans, food, a blur). Ghost hides a real person; this says there was never a person |
| `keep_apart` | Record that two people are not the same person, permanently |
| `forget_person` | Remove a person from the catalog |
| `quarantine_person` | Mark a detection as not a person and move it to Quarantine, where it can be recovered |
| `restore_person` | Undo `forget_person` or the app's Ghost button and bring the full record back |
| `restore_quarantined` | Bring a quarantined detection back into the people catalog, for a real face that was wrongly rejected |
| `list_quarantine` | Detections judged not to be people (animals, statues, masks, bad crops), which can be recovered |
| `remove_appearance` | Remove one clip's wrong sightings from a person, by the clip's `video` path |
| `remove_person_tag` | Remove a person tag you added to a clip, the reverse of `tag_person` |
| `tag_person` | Tag a person as appearing in a video. `person` is an id (p3) or a name; a new name creates a new person |
| `set_person_info` | Add a title or role, notes, or `sex` to a person, for use in edits, lower thirds and graphics |
| `set_person_thumb` | Set a person's picture from an image file and lock it so indexing cannot replace it |
| `link_person_id` | Link a person to an account in another tool |
| `unlink_person_id` | Remove an account link from a person, by `provider` or `link_id` |
| `audit_people` | Report clips with broken face or analysis data. Read-only by default |
| `people_sheet` | Who is in a video, when, and where in the frame, with each face's box `[x0,y0,x1,y1]` (0 to 1) in `frames[].boxes[]` |
| `faces_status` | Whether the face engine (YuNet and SFace) is installed, how to set it up, and how many people are in the catalog |
| `set_face_min_score` | Set the minimum confidence for YuNet face detection (0.1 to 0.99) |
| `review_face_validity` | Recheck people already in the catalog to catch faces that were never human (animals, statues, masks) |
| `unknown_review_queue` | The unnamed faces waiting for a name, strongest probable match first, each with the named people it might be and why. Read-only |
| `compare_detectors` | Compare YuNet with Apple Vision on the same frames of your own clips |
| `set_apple_vision_detector` | Turn Apple Vision face detection on or off (off by default) |
| `vision_detector_status` | Whether Apple Vision face detection is available on your Mac and switched on |
| `reconcile_image_people` | Match the faces in one indexed photo to your people catalog, as `detect_people` does for video |
| `reconcile_images_sweep` | Match faces in many photos to your people catalog, a limited batch at a time |
| `image_enrichment_audit` | List indexed images that have not been analyzed yet. Read-only |
| `plan_image_enrichment` | Preview an image analysis run without running it. Read-only |
| `execute_image_enrichment` | Analyze photos that have not been analyzed yet, a limited batch at a time |

## Relationships and context

| Tool | What it does |
| --- | --- |
| `add_relationship` | Record how two people are related, by their `pN` ids, so you can later ask "who are my clients" or "who is in Zane's family" |
| `remove_relationship` | Remove the relationships between two people: all of them, or only the type named in `kind` |
| `list_relationships` | Relationships for one person (by `pN` id), or all of them |
| `list_relationship_types` | Every relationship type, with how many relationships use it |
| `rename_relationship_type` | Rename a relationship type |
| `merge_relationship_types` | Merge two relationship types that mean the same thing, such as "client" and "My clients". Duplicates collapse to one and `from_type_id` is removed |
| `remove_relationship_type` | Delete a relationship type |
| `family_of` | A person's full family (parents, children, siblings, grandparents, aunts and uncles, nieces and nephews, cousins), worked out from the parent, child and sibling links you recorded |
| `relationship_digest` | Every relationship written out in plain text, grouped by person, using names where known and `pN` ids where not |
| `suggest_connections` | People probably related to someone but not yet linked, ranked by family links and shared surnames. For example, a parent's spouse may be a mother |
| `suggest_reciprocal` | The matching relationship the other way round, using the catalog's sex field (an uncle's nephew or niece, a son's father or mother), or null when there isn't one |
| `create_circle` | Create a circle: a named group, such as a workplace, whose members are connected by belonging to it. Once enough of its people have footage, it also gets a Library collection of everything they are in |
| `add_to_circle` | Add people to a circle, many `pN` ids at once |
| `remove_from_circle` | Take people out of a circle, many `pN` ids at once |
| `update_circle` | Change a circle's `name`, `kind`, `member_label` or `note`, or one member's `role` and dates |
| `list_circles` | Every circle, or only one person's circles (`person_id`), with kind and member count |
| `get_circle` | One circle by `rcN` id, with each member's name, role and dates |
| `merge_circles` | Merge two circles for the same place. Members join; the merged circle is removed |
| `delete_circle` | Delete a circle by `rcN` id |
| `suggest_circles` | Suggest circles from relationships you already recorded, such as everyone linked as coworkers or classmates |
| `suggest_entities` | Search suggestions as you type: matching people, places, cameras, events, projects and text, each with its clip count, most specific first |
| `get_context` | Where you are and what the AI models are being told. A cheap, good first call in any session |
| `set_vision_context` | Set text added to the start of every vision model prompt (`index_video`, `analyze_style`, `track_subject`) |
| `set_reasoning_context` | Set text added to the start of every reasoning model prompt (summaries and insights) |