Cross-Document Alias Resolution Prompt Template

This prompt is designed for investigation and intelligence workflows that require building a unified alias table from multiple unstructured documents. The primary job-to-be-done is to take a set of source documents and a target entity type, then produce a structured mapping of every alias variant to a canonical name. Each mapping must include source provenance, confidence scores, and explicit handling of edge cases such as transliteration differences, partial name matches, and conflicting identifiers. Use this prompt when your downstream system needs a single source of truth for entity references across reports, filings, or OSINT collections—particularly when those references are inconsistent, incomplete, or deliberately obscured.

The ideal user is an analyst or engineer who already has a corpus of documents and a known entity type to resolve, such as persons, organizations, or vessels. The prompt expects you to supply the raw text of each source document, a target entity type, and optionally a set of normalization rules or a preferred output schema. It is not designed for real-time streaming data, for entity types that require image-based recognition without accompanying text, or for scenarios where the canonical identity is already known and only simple string matching is required. Before using this prompt, ensure you have a clear definition of what constitutes a 'canonical' name in your domain—this definition will heavily influence the quality of the output.

Do not use this prompt when the source documents contain primarily visual or tabular data without extractable text, when the entity type is ambiguous or undefined, or when the cost of a false merge or missed link is unacceptable without human review. For high-stakes applications such as sanctions screening or criminal investigation, always pair this prompt with a human-in-the-loop review step and a separate validation harness that checks the output against a golden dataset of known alias pairs. The prompt produces structured JSON output by default, but you should validate that output against your downstream ingestion schema before allowing it to flow into operational systems.

This template is designed for investigation workflows where the same person, organization, or entity appears under different names across multiple documents. The prompt instructs the model to produce a structured alias table that maps every surface-form mention to a single canonical identifier, preserving the source document, the specific mention span, and a confidence level for each mapping. Use this when you have a corpus of reports, emails, or intelligence files and need a consolidated alias index before downstream entity resolution or graph construction.

textCopy
You are an alias resolution analyst. Your task is to read the provided documents and build a complete alias-to-canonical mapping for [ENTITY_TYPE].

## INPUT DOCUMENTS
[DOCUMENTS]

## ENTITY TYPE
[ENTITY_TYPE]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "canonical_entities": [
    {
      "canonical_id": "string (unique identifier you assign)",
      "canonical_name": "string (the preferred normalized name)",
      "aliases": [
        {
          "alias_text": "string (exact surface form from source)",
          "source_document_id": "string",
          "source_span": "string (surrounding context or location reference)",
          "confidence": "high|medium|low",
          "confidence_rationale": "string (brief explanation of evidence strength)"
        }
      ],
      "supporting_evidence": "string (summary of why these aliases refer to the same entity)",
      "conflicting_evidence": "string or null (any contradictory signals that suggest a possible split)"
    }
  ],
  "unresolved_mentions": [
    {
      "mention_text": "string",
      "source_document_id": "string",
      "source_span": "string",
      "reason_unresolved": "string (insufficient evidence, ambiguous reference, possible new entity)"
    }
  ]
}

## CONSTRAINTS
- Assign a unique canonical_id to each resolved entity. Do not merge entities unless there is clear evidence they are the same.
- For transliterated names or partial matches, set confidence to "medium" or "low" and explain your reasoning in confidence_rationale.
- If a mention could plausibly refer to more than one canonical entity, place it in unresolved_mentions rather than guessing.
- Preserve the exact surface form in alias_text. Do not normalize or correct it.
- If a document contains no entities of the specified type, return empty arrays for both canonical_entities and unresolved_mentions.

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Adapt this template by replacing the square-bracket placeholders before sending it to the model. [DOCUMENTS] should contain the full text of each source document, each prefixed with a unique identifier (e.g., [DOC_ID: report-001]). [ENTITY_TYPE] narrows the resolution scope—use values like person, organization, or location to prevent the model from attempting cross-type resolution. [EXAMPLES] is optional but strongly recommended: provide one or two few-shot examples showing correct alias grouping, confidence assignment, and unresolved handling for your domain. Set [RISK_LEVEL] to high if the alias table feeds a production system where false merges are costly; this should trigger additional validation and human review steps in your harness. After generating the output, validate that every alias_text appears verbatim in the source document it references, and that no two canonical entities share overlapping aliases unless explicitly justified by evidence.

The alias resolution prompt is not a standalone tool—it is a component inside a larger entity resolution pipeline. Before calling the model, your application must assemble the [DOCUMENTS] array from your document store, normalize each document's metadata (source ID, date, author), and inject any existing canonical entity records as [KNOWN_ENTITIES] to prevent the model from creating duplicate canonical forms for entities you have already resolved. The prompt expects documents to include a doc_id and text field at minimum; if your source system uses different field names, map them before injection rather than asking the model to adapt.

Validation and retry logic is critical because alias resolution output is ingested directly into entity databases. After receiving the model response, validate the JSON structure against a schema that enforces: (1) every canonical_name is non-empty, (2) every aliases array entry includes a source_doc_id that matches one of the input document IDs, (3) confidence values are numbers between 0.0 and 1.0, and (4) no canonical entity appears in two different resolution groups. If validation fails, implement a single retry with the validation error message appended to the prompt as a [PREVIOUS_ERRORS] block—do not retry more than twice without escalating to a human review queue. For high-stakes intelligence workflows, route all outputs with confidence below 0.7 or with conflict_flags present to a human analyst for adjudication before the alias table is updated.

Model choice and tool integration matter here. Use a model with strong structured output capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) and enable JSON mode or structured outputs if your provider supports it. If your resolution pipeline includes a vector search step for candidate entity matching, run that retrieval before calling this prompt and inject the top-K candidates as [CANDIDATE_MATCHES] so the model focuses on verification rather than exhaustive pairwise comparison. Log every resolution decision—including the input document IDs, the model version, the raw and validated output, and any human overrides—to an audit table keyed by a resolution_run_id. This audit trail is essential for debugging false merges, missed aliases, and confidence drift across model updates. Avoid calling this prompt on document batches larger than 20 documents at once; for larger corpora, chunk by time window or source group and merge results in a downstream reconciliation step.