denselinkage 1.0.0b1

Record linkage with dense blocking using text embeddings and LLM matching

denselinkage

Record linkage with dense blocking using text embeddings and LLM matching.

Status — beta. The dependency-free core is implemented and runs: link / dedupe / match_pairs, connected-components clustering, and the linkage / blocking / clustering metrics — all on numpy + pandas. The heavy extras (FAISS, sentence-transformers, LangChain) are experimental this release: their adapters are declared but raise NotImplementedError.

Usage

from denselinkage import DenseLinker, Source, TemplateSerializer
from denselinkage.core.results import LabeledPairs
from denselinkage.metrics import linkage_metrics

linker = DenseLinker.with_defaults()  # picks a sensible embedder/index/matcher
left  = Source(df_a, id_column="id_a", serializer=TemplateSerializer("Name: {name}, City: {city}"))
right = Source(df_b, id_column="id_b", serializer=TemplateSerializer(
    "Name: {name}, City: {city}", column_mapping={"company_name": "name", "headquarters": "city"}))

result  = linker.link(left, right)               # one call, no fit/predict, no mutation
metrics = linkage_metrics(result, gold=LabeledPairs.from_pairs([("A1", "B1")]))
result.to_frame()  # left_id, right_id, match, confidence, reason, similarity

Deduplicate one dataset with linker.dedupe(src); reuse an index with idx = linker.index(left); idx.query(right). See examples/ — 00_quickstart.py is the shortest path, 01_end_to_end_linkage.py shows full component control.

Install

pip install denselinkage                       # core (numpy, pandas)
pip install "denselinkage[faiss]"              # + FAISS vector index
pip install "denselinkage[sentence-transformers]"
pip install "denselinkage[langchain]"          # + LLM matcher
pip install "denselinkage[all]"

The [faiss], [sentence-transformers], and [langchain] extras are reserved but experimental this release — their adapters raise NotImplementedError; the dependency-free core runs without them.

Development

Requires uv.

uv sync --dev
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest

See CONTRIBUTING.md for details. CI runs lint, format, strict mypy, and tests on Python 3.10–3.13.

Changelog

See CHANGELOG.md.

License

MIT © 2026 Alvaro