Entity Linking

---
name: "entity-linking"
description: "Routes scispaCy candidate generation, knowledge-base loading, ANN
  index creation, and entity-linking workflows."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Entity Linking

Use this sub-skill when the task is about scispaCy's knowledge-base and entity-linking stack rather than the tokenizer or project-data workflows.

## Typical triggers

- Build or debug `scispacy_linker`.
- Build an ANN index for a custom knowledge base.
- Load UMLS, MeSH, GO, HPO, or RxNorm knowledge bases.
- Inspect `CandidateGenerator` results or linker thresholds.
- Work with `KnowledgeBase`, `UmlsKnowledgeBase`, or UMLS semantic type trees.
- Handle `cached_path` downloads or linker cache issues.

## What belongs here

- Candidate generation and ANN index construction.
- Built-in and custom knowledge-base loading.
- UMLS semantic type tree helpers.
- Linker factory configuration and abbreviation-aware linking.
- Cache and remote-artifact behavior for KB/index downloads.

## What does not belong here

- Tokenization, sentence segmentation, abbreviation extraction, or hyponym detection. Use `pipeline-components`.
- MedMentions/BIO readers, NER evaluation, and package/workflow scripts. Use `project-workflows`.
- Package installation and model catalog details. Read the root installation reference.

## First things to read or run

- `references/api-reference.md` for verified signatures, defaults, and output shapes.
- `references/workflows.md` for building custom linkers and querying candidates.
- `references/troubleshooting.md` for cache, threshold, and `nmslib` issues.
- `../../scripts/smoke_scispacy.py` for the tiny linker smoke used to validate the environment.
- `scripts/build_linker_index.py` when you want a bundled helper to build a linker index from a local KB.

## Fast workflow summary

1. Decide whether you need a built-in KB (`umls`, `mesh`, `go`, `hpo`, or `rxnorm`) or a custom KB file.
2. Load or construct the KB.
3. Build a candidate index with `create_tfidf_ann_index` or a bundled wrapper.
4. Create the linker with `EntityLinker` or `EntityLinker.from_kb`.
5. If you want abbreviation-aware linking, add the abbreviation detector first.

## Example route decisions

- If the request says "link biomedical mentions to UMLS", stay here.
- If the request says "build an index from a JSONL knowledge base", stay here.
- If the request says "count token frequencies from corpus text", switch to `project-workflows`.
- If the request says "change how text is tokenized", switch to `pipeline-components`.

## Verification mindset

For this sub-skill, the strongest validation is a tiny linker smoke:

- `KnowledgeBase` can load a tiny local KB.
- `create_tfidf_ann_index(None, kb)` can build a candidate index.
- `CandidateGenerator` returns at least one candidate for a simple mention.
- `scispacy_linker` can resolve abbreviations when the abbreviation detector is already in the pipeline.

If that smoke fails, read the troubleshooting reference before attempting a large KB build or a remote download.