Metadata-Version: 2.4
Name: matchlab
Version: 0.1.0.dev5
Summary: A local-first library for building, running and evaluating entity resolution pipelines.
Author: Department for Business and Trade
Project-URL: Documentation, https://uktrade.github.io/matchlab/
Project-URL: Repository, https://github.com/uktrade/matchlab.git
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: adbc-driver-manager>=1.9.0
Requires-Dist: duckdb>=1.1.1
Requires-Dist: faker>=36.1.1
Requires-Dist: frozendict>=2.4.6
Requires-Dist: pandas>=2.3.3
Requires-Dist: platformdirs>=4.5.0
Requires-Dist: polars-hash>=0.5.3
Requires-Dist: polars>=1.32.3
Requires-Dist: pyarrow>=17.0.0
Requires-Dist: pydantic>=2.9.2
Requires-Dist: rich>=13.9.4
Requires-Dist: splink<4.1.0,>=4.0.5
Requires-Dist: sqlalchemy>=2.0.35
Requires-Dist: sqlglot[c]>=30.0.3
Requires-Dist: textual>=0.80
Dynamic: license-file

# matchlab

**A local-first library for building, running and evaluating entity resolution pipelines.**

Record matching is a chore. matchlab makes it a pipeline you can build, run, query and measure — on your machine, against your warehouse, with nothing to deploy.

```python
import matchlab as mb

companies = mb.read_database(
    name="crn",
    sql="select pk, company, town from companies",
    client=warehouse,
    key_field="pk",
)

entities = (
    companies.clean({"name": "lower(crn_company)"})
    .dedupe(
        model_class=mb.NaiveDeduper,
        model_settings={"unique_fields": ["name"]},
    )
    .resolve()
    .collect()
)

entities.lookup_key(from_source="crn", to_sources=["dh"], key="a1")
```

Read the [full documentation](https://uktrade.github.io/matchlab/).

## What it does

* **A lazy plan.** `Source(...).dedupe(...).resolve()` builds a tree of steps. Nothing runs until you `collect()`.
* **Content-addressed caching.** Re-collecting an unchanged plan does no work. Adding a step runs only that step.
* **Materialised resolver output.** A collected resolver writes a complete `(root, leaf, key, source)` table, so lookups are reads, not re-derivations.
* **Measurement as a first-class job.** Sample clusters, record judgements, score precision and recall, and compare methodologies on equal terms.

## What it doesn't do

No server, no accounts, no permissions, nothing to deploy. If you need a shared, governed matching service, matchlab is not that.

## Installation

```shell
pip install matchlab
```

## Coming from Matchbox?

matchlab is the successor to `matchbox-db`, with the server removed and the client API rebuilt. It's a hard break — see the [migration guide](https://uktrade.github.io/matchlab/migration/matchbox-to-matchlab/).

## Development

See our full development guide and coding standards on our [contribution guide](https://uktrade.github.io/matchlab/contributing/).
