EntityResolveResponse

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The q parameter echoed back."
    },
    "context": {
      "type": [
        "string",
        "null"
      ],
      "description": "The context parameter echoed back."
    },
    "confidence": {
      "type": "string",
      "enum": [
        "exact",
        "single_fuzzy",
        "ambiguous",
        "fuzzy",
        "none"
      ],
      "description": "exact: one entity is named q (or the handle, id or alias), and no better-known person carries the name. single_fuzzy: the only entity returned, not an exact name. ambiguous: several exact matches, or an exact match next to a better-known person sharing the name (Jordan the brand vs Michael Jordan). fuzzy: only loose matches. none: no match."
    },
    "best": {
      "$ref": "#/components/schemas/ResolveCandidate"
    },
    "suggested": {
      "$ref": "#/components/schemas/ResolveSuggestion"
    },
    "ask": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "question": {
          "type": "string"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "label": {
                "type": "string",
                "description": "One line to show the user: name, type, description, appearance count."
              }
            },
            "required": [
              "id",
              "name",
              "type",
              "label"
            ]
          }
        }
      },
      "required": [
        "question",
        "options"
      ],
      "description": "Set when best and suggested are both null and several entities fit: show the options to the user, or check every option id against the data and answer per entity."
    },
    "candidates": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ResolveCandidate"
      },
      "description": "Entities considered: exact names first, then initials, whole-word, spelling and substring matches, each by appearance count."
    },
    "note": {
      "type": "string",
      "description": "One steering sentence for the agent reading this."
    }
  },
  "required": [
    "query",
    "context",
    "confidence",
    "best",
    "suggested",
    "ask",
    "candidates",
    "note"
  ],
  "example": {
    "query": "Sam",
    "context": null,
    "confidence": "ambiguous",
    "best": null,
    "suggested": {
      "id": "ent_124463",
      "name": "Sam Altman",
      "slug": "sam-altman",
      "type": "person",
      "appearance_count": 4399,
      "youtube_channel_id": null,
      "description": "CEO of OpenAI and former president of Y Combinator.",
      "page": "https://arcmira.com/person/sam-altman",
      "match": "word",
      "reason": "dominant",
      "evidence": "it has 4,399 appearances, 11x the next match (Sam Dunning, 397)",
      "assumed": true
    },
    "ask": null,
    "candidates": [
      {
        "id": "ent_123696",
        "name": "Sam",
        "slug": "sam",
        "type": "person",
        "appearance_count": 265,
        "youtube_channel_id": null,
        "description": "Common gender-neutral given name or nickname",
        "page": "https://arcmira.com/person/sam",
        "match": "exact"
      }
    ],
    "note": "No row is certain. suggested is Sam Altman (person) because it has 4,399 appearances, 11x the next match (Sam Dunning, 397). Use it and tell the user you assumed it."
  }
}