# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Face Client Largepersongroups API
  version: 1.0.0
extends: openapi/microsoft-azure-largepersongroups-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons'].get
  update:
    x-apievangelist-phrasing:
      intent: List the people in a large person group
      effect: read
      questions:
      - Who is enrolled in my large person group for face recognition?
      - Can I page through persons in a large group a batch at a time?
      instructions:
      - text: List the persons in large person group {largePersonGroupId}.
        slots:
          largePersonGroupId: path.largePersonGroupId
      - text: Show {top} persons from large group {largePersonGroupId} after person {start}.
        slots:
          top: query.top
          largePersonGroupId: path.largePersonGroupId
          start: query.start
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new person to a large person group
      effect: write
      questions:
      - How do I enroll a new person in a large person group before adding their faces?
      - Can I attach custom user data when I create a person?
      instructions:
      - text: Create a person named {name} in large person group {largePersonGroupId}.
        slots:
          name: requestBody.name
          largePersonGroupId: path.largePersonGroupId
      - text: Enroll {name} in large group {largePersonGroupId} with user data {userData}.
        slots:
          name: requestBody.name
          largePersonGroupId: path.largePersonGroupId
          userData: requestBody.userData
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons/{personId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a person in a large person group
      effect: read
      questions:
      - Which registered faces belong to a particular person in my large group?
      - What name and user data are stored for one enrolled person?
      instructions:
      - text: Get person {personId} in large person group {largePersonGroupId}.
        slots:
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      - text: Show the persisted face IDs of person {personId} in group {largePersonGroupId}.
        slots:
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons/{personId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a person from a large person group
      effect: destructive
      questions:
      - How do I un-enroll someone from a large person group?
      - Does deleting a person also delete their registered face features?
      instructions:
      - text: Delete person {personId} from large person group {largePersonGroupId}.
        slots:
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      - text: Remove {personId} and all their faces from group {largePersonGroupId}.
        slots:
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons/{personId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or relabel a person in a large group
      effect: write
      questions:
      - Can I fix a typo in an enrolled person's name?
      - How do I change the user data stored on a person record?
      instructions:
      - text: Rename person {personId} in large person group {largePersonGroupId} to {name}.
        slots:
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
          name: requestBody.name
      - text: Set user data of person {personId} in group {largePersonGroupId} to {userData}.
        slots:
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
          userData: requestBody.userData
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a registered face of a person
      effect: read
      questions:
      - What user data is attached to one of a person's registered faces?
      - Can I look up a single persisted face by its ID?
      instructions:
      - text: Get face {persistedFaceId} of person {personId} in large person group {largePersonGroupId}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      - text: Show details of persisted face {persistedFaceId} for {personId} in group {largePersonGroupId}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a registered face from a person
      effect: destructive
      questions:
      - How do I remove a bad photo from someone's enrolled faces?
      - Are face deletions for the same person processed one at a time?
      instructions:
      - text: Delete face {persistedFaceId} from person {personId} in large person group {largePersonGroupId}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      - text: Remove persisted face {persistedFaceId} of {personId} in group {largePersonGroupId}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update the user data on a registered face
      effect: write
      questions:
      - Can I tag one of a person's saved faces with a note?
      - What can I change about a persisted face after it is added?
      instructions:
      - text: Set user data of face {persistedFaceId} on person {personId} in large group {largePersonGroupId} to {userData}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
          userData: requestBody.userData
      - text: Relabel persisted face {persistedFaceId} of {personId} in group {largePersonGroupId}.
        slots:
          persistedFaceId: path.persistedFaceId
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a large person group's details
      effect: read
      questions:
      - What recognition model does my large person group use?
      - Where can I see a large group's name and user data?
      instructions:
      - text: Get large person group {largePersonGroupId}.
        slots:
          largePersonGroupId: path.largePersonGroupId
      - text: Show large group {largePersonGroupId} including its recognition model when {returnRecognitionModel}.
        slots:
          largePersonGroupId: path.largePersonGroupId
          returnRecognitionModel: query.returnRecognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a large person group
      effect: write
      questions:
      - How do I create a face recognition group that holds up to a million people?
      - Can I choose the recognition model when I create a large person group?
      instructions:
      - text: Create large person group {largePersonGroupId} named {name}.
        slots:
          largePersonGroupId: path.largePersonGroupId
          name: requestBody.name
      - text: Create large group {largePersonGroupId} called {name} using recognition model {recognitionModel}.
        slots:
          largePersonGroupId: path.largePersonGroupId
          name: requestBody.name
          recognitionModel: requestBody.recognitionModel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a large person group
      effect: destructive
      questions:
      - How do I wipe out an entire large person group and all its faces?
      - Does removing a large group delete every person's face features too?
      instructions:
      - text: Delete large person group {largePersonGroupId}.
        slots:
          largePersonGroupId: path.largePersonGroupId
      - text: Remove the whole large group {largePersonGroupId} with all enrolled people.
        slots:
          largePersonGroupId: path.largePersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or relabel a large person group
      effect: write
      questions:
      - Can I change the display name of a large person group?
      - How do I update the user data on a large group without touching other fields?
      instructions:
      - text: Rename large person group {largePersonGroupId} to {name}.
        slots:
          largePersonGroupId: path.largePersonGroupId
          name: requestBody.name
      - text: Set user data of large group {largePersonGroupId} to {userData}.
        slots:
          largePersonGroupId: path.largePersonGroupId
          userData: requestBody.userData
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/training'].get
  update:
    x-apievangelist-phrasing:
      intent: Check training status of a large person group
      effect: read
      questions:
      - Has training finished on my large person group yet?
      - Is the large group still training or did it fail?
      instructions:
      - text: Check the training status of large person group {largePersonGroupId}.
        slots:
          largePersonGroupId: path.largePersonGroupId
      - text: Tell me whether large group {largePersonGroupId} has finished training.
        slots:
          largePersonGroupId: path.largePersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups'].get
  update:
    x-apievangelist-phrasing:
      intent: List all large person groups
      effect: read
      questions:
      - Which large person groups have I created?
      - Can I list large groups starting after a given group ID?
      instructions:
      - text: List my large person groups.
      - text: Show {top} large person groups after {start}.
        slots:
          top: query.top
          start: query.start
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/train'].post
  update:
    x-apievangelist-phrasing:
      intent: Train a large person group
      effect: write
      questions:
      - How do I retrain a large person group after adding new faces?
      - Does queuing training start it right away?
      instructions:
      - text: Train large person group {largePersonGroupId}.
        slots:
          largePersonGroupId: path.largePersonGroupId
      - text: Queue a training run for large group {largePersonGroupId} now that faces are added.
        slots:
          largePersonGroupId: path.largePersonGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a face image to a person in a large group
      effect: write
      questions:
      - How do I register a photo of someone's face to their person record?
      - What if the image has several faces — can I pick one with a rectangle?
      - Is the uploaded image itself stored by the face service?
      instructions:
      - text: Add a face to person {personId} in large person group {largePersonGroupId}.
        slots:
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
      - text: Add the face at {targetFace} to {personId} in large group {largePersonGroupId} using detection model {detectionModel}.
        slots:
          targetFace: query.targetFace
          personId: path.personId
          largePersonGroupId: path.largePersonGroupId
          detectionModel: query.detectionModel
      method: generated
      generated: '2026-09-26'