Entity & Relation Resolution
Relevant source files
The following files were used as context for generating this wiki page:
Entity & Relation Resolution is a critical phase in the Agentic GraphRAG pipeline that ensures the knowledge graph contains canonical, non-redundant information. It identifies and merges duplicate medical entities (e.g., "metformin" vs. "Glucophage") and relation types that refer to the same real-world concepts. This process runs after initial extraction and aggregation, providing a cleaned graph structure for subsequent community detection and retrieval operations.
Sources: README.md:120-128, am_diag/graph_construction/resolve/resolver.py:18-24
Resolution Architecture
The resolution system employs a two-stage approach combining deterministic pre-filtering with advanced LLM-based deduplication. The EntityEdgeResolver class manages this workflow for both entities and relation types (edges).
Resolution Workflow
- Stage 1 (Deterministic): Uses semantic hashing and near-exact variant matching to collapse obvious duplicates without LLM overhead.
- Stage 2 (Clustering & LLM): Residual items are vectorized and grouped into clusters. Within each cluster, an LLM assisted by BM25 and cosine similarity retrieval identifies complex duplicates and selects a canonical alias.
- Application: The resulting alias maps are applied to the graph data models to update names, aliases, and IDs.
The following diagram illustrates the high-level data flow through the resolution components:
Stage 1: Deterministic Deduplication
Stage 1 relies on the DeterministicDeduplicator to handle exact and near-exact variants. This stage uses techniques such as SemHash and MinHash-LSH to pre-filter items, significantly reducing the token load for subsequent LLM processing. If LLM resolution is disabled in the configuration, the system relies entirely on this stage.
Sources: am_diag/graph_construction/resolve/resolver.py:73-77, README.md:120-125
Stage 2: Clustering and LLM Deduplication
For complex cases that survive deterministic filtering, the system enters Stage 2.
Embedding and Clustering
Remaining items are embedded using an Embedder and grouped into clusters using a k-means based approach. The cluster_items function ensures clusters stay within a configurable size (e.g., resolution_cluster_size) to maintain context window efficiency for the LLM.
Sources: am_diag/graph_construction/resolve/cluster.py:10-25, am_diag/graph_construction/resolve/resolver.py:80-87
LLM Deduplication Logic
The LLMDeduplicator processes each cluster concurrently. For every item in a cluster, it retrieves a candidate set of potentially similar items using a hybrid fusion of BM25 (lexical) and cosine (semantic) scores.
The LLM is then prompted with a ClusterDeduplicationVerdict request to:
- Identify EXACT duplicates based on clinical meaning.
- Select the single best canonical alias (e.g., generic INN for drugs, HGNC symbol for genes).
- Provide reasoning for the decision.
Resolution Data Models
Key data structures used during resolution facilitate the mapping between raw extracted text and canonical entities.
| Class | Description | Fields |
|---|---|---|
ResolvedAliasMap | Stores the final mapping from a canonical alias to its member strings. | alias_to_members: dict[str, list[str]] |
ItemCluster | Represents a group of items processed together for deduplication. | items: set[str], centroid: np.ndarray |
ClusterDeduplicationVerdict | The structured output from the LLM resolution function. | duplicates: list[str], alias: str, reasoning: str |
Sources: am_diag/common/data_models/cluster.py:10-25, am_diag/llm/baml_client/stream_types.py:30-34
Application of Alias Maps
The AliasApplier class performs the final mutation of the data. It transforms the original entities and relations into their resolved forms.
Entity Transformation
- Canonical Name: Sets the
canonical_namefield on the best-scoring entity in a group. - Aliases: Populates the
aliaseslist with all surface forms encountered in the text. - Provenance: Merges
chunk_idsandschema_propertiesacross all matched duplicates.
Relation Transformation
- ID Resolution: Updates the
head_idandtail_idfields to point to the UUIDs of the resolved canonical entities. - Deduplication: Filters out redundant relations between the same two canonical entities if they share the same relation type.
Sources: am_diag/graph_construction/resolve/apply.py:15-80, README.md:120-128
Configuration Options
Resolution behavior is controlled via the ExtractionPipelineConfig.
| Parameter | Type | Default | Description |
|---|---|---|---|
use_llm_resolution | bool | True | Enables Stage 2 (LLM-based) deduplication. |
resolution_cluster_size | int | 128 | Maximum number of items in a single LLM processing cluster. |
resolution_bm25_weight | float | 0.5 | Weight for lexical matching in candidate retrieval. |
resolution_embedding_weight | float | 0.5 | Weight for semantic matching in candidate retrieval. |
resolution_max_concurrent_llm_calls | int | 10 | Semaphore limit for parallel LLM API requests. |
Sources: am_diag/graph_construction/resolve/resolver.py:39-45, tests/am_diag/graph_construction/test_resolution.py:65-75
Summary
Entity & Relation Resolution transforms a noisy, redundant set of extracted triples into a coherent biomedical knowledge graph. By combining efficient deterministic filters with high-precision LLM reasoning within semantic clusters, the system maintains clinical accuracy while ensuring that related medical concepts are properly unified. This allows the Agentic RAG system to navigate the graph effectively, identifying thematic patterns and evidence across disparate source documents.
Sources: README.md:120-128, am_diag/graph_construction/resolve/resolver.py:18-35