matchlab 0.1.0.dev1__py3-none-any.whl

matchlab/transformers/transform.py

@@ -0,0 +1,101 @@
+"""Transform, a plan node that reshapes one record step with a `Transformer`.
+
+`Transform` is to `Transformer` what `Model` is to a `Deduper`/`Linker`, the lazy plan
+node that wraps a serialisable methodology, folds its configuration into a cache key,
+and runs it on collect. Its single input is a `RecordStep`, so transforms chain, each
+its own cached artifact.
+"""
+
+from typing import ClassVar
+
+import polars as pl
+
+from matchlab.adapters import Adapter, Fingerprint
+from matchlab.core.kinds import StepKind
+from matchlab.recordstep import IdentifierRead, RecordStep
+from matchlab.specs import TransformSpec
+from matchlab.transformers.base import Transformer
+from matchlab.transformers.clean import Clean
+from matchlab.transformers.explode import Explode
+from matchlab.transformers.group import Group
+from matchlab.transformers.select import Select
+
+_TRANSFORMER_CLASSES: dict[str, type[Transformer]] = {}
+
+
+def add_transformer_class(transformer_class: type[Transformer]) -> None:
+    """Register a custom transformer so it can be named in a plan (and a document)."""
+    if not issubclass(transformer_class, Transformer):
+        raise ValueError("The argument is not a subclass of Transformer.")
+    _TRANSFORMER_CLASSES[transformer_class.__name__] = transformer_class
+
+
+for _builtin in (Select, Clean, Group, Explode):
+    add_transformer_class(_builtin)
+
+
+class Transform(RecordStep):
+    """A record step reshaped by one transformer."""
+
+    kind: ClassVar[StepKind] = StepKind.TRANSFORM
+
+    def __init__(
+        self,
+        upstream: RecordStep,
+        transformer: Transformer | type[Transformer] | str,
+        transformer_settings: dict | None = None,
+    ) -> None:
+        """Define a transform.
+
+        Args:
+            upstream: The record step to reshape.
+            transformer: A `Transformer` instance, or a subclass / its registered name
+                to build from `transformer_settings`.
+            transformer_settings: The configuration dict, when `transformer` is a class
+                or a name. Ignored when it is already an instance.
+        """
+        if isinstance(transformer, Transformer):
+            self.transformer = transformer
+        else:
+            transformer_class = (
+                _TRANSFORMER_CLASSES[transformer]
+                if isinstance(transformer, str)
+                else transformer
+            )
+            self.transformer = transformer_class(**(transformer_settings or {}))
+
+        self.transformer_class = type(self.transformer)
+        self._input = upstream
+        super().__init__(upstream=(upstream,))
+
+    # -- Step contract ----------------------------------------------------------------
+
+    def __str__(self) -> str:
+        """A transform is drawn with the transformer implementing it."""
+        return f"{self.kind}({self.transformer_class.__name__})"
+
+    @property
+    def spec(self) -> TransformSpec:
+        """The serialisable spec for this transform."""
+        return TransformSpec(
+            transformer_class=self.transformer_class.__name__,
+            transformer_settings=self.transformer.model_dump(mode="json"),
+        )
+
+    def _execute(self, adapter: Adapter, fp: Fingerprint) -> None:
+        reshaped = self.transformer.apply(self._input._read_cache(adapter))
+        adapter.store_transform(fp, reshaped)
+
+    # -- RecordStep contract ------------------------------------------------------
+
+    def _read_cache(self, adapter: Adapter) -> pl.DataFrame:
+        if self._fp is None:  # collect orders upstream first
+            raise RuntimeError(
+                "This transform has not been collected. Call collect() first."
+            )
+        return adapter.read_transform(self._fp)
+
+    @property
+    def _identifier_reads(self) -> tuple[IdentifierRead, ...]:
+        """A transform reads the same records as its input, so the reads delegate up."""
+        return self._input._identifier_reads

matchlab-0.1.0.dev1.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: matchlab
+Version: 0.1.0.dev1
+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
+from matchlab import Source
+from matchlab.models.dedupers import NaiveDeduper
+
+companies = Source(
+    location=warehouse,
+    name="crn",
+    extract_transform="select pk, company, town from companies",
+    key_field="pk",
+)
+
+entities = (
+    companies.clean({"name": "lower(crn_company)"})
+    .dedupe(model_class=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/).

matchlab-0.1.0.dev1.dist-info/RECORD

@@ -0,0 +1,72 @@
+matchlab/__init__.py,sha256=GoBEpiGNfnxOxA3KXMWHaqZVjh4HnrATZayGv-wQeS4,1200
+matchlab/cli.py,sha256=Ka-clRCiPnxI5jmehjGCgdNyADcPFcnl3cuPI1rynYg,6209
+matchlab/document.py,sha256=6iWbZsiX9dm2TFHTTtu4WpKf8tjglrY4dKZcqB39Di0,13419
+matchlab/lineage.py,sha256=qJWPGpXVnuH8xQBZ-0L6PZjKg6b74xX9j6koY-N4Org,8870
+matchlab/locations.py,sha256=6zvXWBXaQFBbOhicsILqW0cLoY17e5Yow3xIBEtfwtw,13435
+matchlab/progress.py,sha256=t2PAj0YG2vAHguMFn9J0NL07R2K6wEnAkGELQpFNYNM,21330
+matchlab/recordstep.py,sha256=n2aEpePo4GqWxo2r37N6pJbF-DLGNQpqFHEoxFc-2-I,7380
+matchlab/sources.py,sha256=TdS4c2crd-pqeXATYE80TyG5B1oWgh0PzkSt_2fdpkE,12414
+matchlab/specs.py,sha256=zIWNIZ0YsWqAFh-19JFCYLQSgZwuM6vGoaJgEC5z5uM,4638
+matchlab/steps.py,sha256=91y9Klh25vyxdRtWP4bj-4fXSmX41tLX4sCqChUgSAg,12932
+matchlab/adapters/__init__.py,sha256=QN8tGB0LJtLtxtEaq1aFZD_XHAQiR_e2CUPGoVJj4gg,554
+matchlab/adapters/base.py,sha256=HEIrave447Rm26ZzZicPHgjeyJRJ9wa7DzhedryzANI,18738
+matchlab/adapters/duckdb.py,sha256=tsKlQo_nAJCU4ySHjhnbwL-MmbLVRIG1EPV9E_D-EiQ,28663
+matchlab/core/__init__.py,sha256=ftFTAWUmTIzJh01EkAvmJ8V4p2L33itVQ6t_JGxWzZg,68
+matchlab/core/dataframes.py,sha256=8dSUyjVbC09YFFMnjOdHXqROJtt5SXSYOONxxIl88gY,8018
+matchlab/core/dsu.py,sha256=nhOdQsVZw8AltxH0bBPaCp2YJQ7Y8h2zS7wDle9moVk,1946
+matchlab/core/exceptions.py,sha256=qHnc2s6bFPvUQBmJ9oOk02-9zx-fLUPmGVUG7rblZx0,1305
+matchlab/core/hash.py,sha256=E4jjov9asj-EGJxNTcsJP-J5h6Ju8pLLTQsmjBJqp2w,4714
+matchlab/core/kinds.py,sha256=LKzyFY1bTCIiQRTV0LiALeVWcPp4Ol1h2TvaSN_mV5Y,255
+matchlab/core/logging.py,sha256=LbdeEhyESwTTikD5pgZBKRInE0XRMSylmAZIv6VMOOk,8640
+matchlab/core/resolver_output.py,sha256=chm1CUJP09gZlszLdKHG0_V9WfQu5_DoumLeT85UmU8,7899
+matchlab/core/schemas.py,sha256=I5YjvMU8IsFLURM1AsLOxB7UjoYvVDlno2MQqNKnAZk,2638
+matchlab/core/sql.py,sha256=swcsYb9vgdxIUbwBeMOIY4j1epvRWkr3qjuKbJbP3HA,432
+matchlab/eval/__init__.py,sha256=Lb-Lm1FwHMD-0yB-WONdX58y0G4dDlo-Zz93OQMhTlo,233
+matchlab/eval/judgements.py,sha256=IZgWXH2-ltzlyfbzB8-COgKzNRg851c63Z7oKA4Ce7A,1450
+matchlab/eval/metrics.py,sha256=yQHpjzSBFLsMwMAPDiWNcUrPZx-OkTindY5Mb5BjInk,9747
+matchlab/eval/samples.py,sha256=ZXBvUJzLEG6KV_wTl4Q5BvliuJC4T1LOYwKM1zsUooA,16546
+matchlab/eval/tui/__init__.py,sha256=T77U0fWsMlAQnsUEVah0-tonP1M-4aW92fGExoJgFWg,2528
+matchlab/eval/tui/app.py,sha256=CFw43oO_kct0fDwl8iVKupFEOgPxCWqy6-3pPlJX0sg,15033
+matchlab/eval/tui/modals.py,sha256=WwfH82-_vTtS0G_xCjhig5f1N7BMMr35-WMA0GQPKBk,2692
+matchlab/eval/tui/styles.tcss,sha256=ioZ8trLoH0roS5LZDrXeo3IIzh4sA9Pi8hrEDF0dpBs,3220
+matchlab/eval/tui/widgets/__init__.py,sha256=AJsdcJTQy0LIOegAxSRFjCR-DW5jCodClYdPRKfXJsc,56
+matchlab/eval/tui/widgets/assignment.py,sha256=djYry92TIjSwOxPERyeBdM9imcu1ngd8zrDwHQ2TNQk,2316
+matchlab/eval/tui/widgets/styling.py,sha256=va69ALl74yjdgG4Wf7y0iEd5apJmIUoLf27WOv74K74,2346
+matchlab/eval/tui/widgets/table.py,sha256=gXXDXDgwFXpXrCv1Grw-gryT-RSl441tsTpr-GT3M6I,11043
+matchlab/models/__init__.py,sha256=cOfN9Um4r7XuBkC8dfTPRYefmQruxGm6kw6R9SJWvgw,225
+matchlab/models/comparison.py,sha256=ahx5CjsK-NNLdWiHW6JIqyXJLlQ1MQZ9-_XnrlneehI,2447
+matchlab/models/models.py,sha256=DgiGsqP9ps3c3mexZUzw5T9YwzNg-GusHMIoxGlzvT0,7588
+matchlab/models/dedupers/__init__.py,sha256=J7JZSAnA8C-qyarathk369unktvpBa2njJ2POslVx0k,121
+matchlab/models/dedupers/base.py,sha256=z_7AS-UfsiQXa_e14R-a_mD1aSeZrTtg4jgYpmDnBA0,1246
+matchlab/models/dedupers/naive.py,sha256=aHlSvwY6fbLjH4adEFFVbyVui3azm6gRKQ5amb-fibE,2432
+matchlab/models/linkers/__init__.py,sha256=qbj6hITLFBuONO0_fn3yPknTUAWjzWcFSQzIyi75Rmc,339
+matchlab/models/linkers/base.py,sha256=Xt7ninASXRsuE46FuGqp1kterqG8X9E7BhcifSqnlPM,1366
+matchlab/models/linkers/deterministic.py,sha256=yX1kEdxMmu8HYZst2eHLx-JqOQYM0sFedJLapwI7U0w,8956
+matchlab/models/linkers/splinklinker.py,sha256=jVMClcKBKSXNkLSrJQMF33J4CxdbwXPNilYIAk4vD3E,9949
+matchlab/models/linkers/weighteddeterministic.py,sha256=m8j1oGTbuOuvuALiZlt20dXhMKs8YfisXpekegaqr5A,4584
+matchlab/resolvers/__init__.py,sha256=G1lbpQK_NrKabHBR7rd25ou1KKLQqjmHAcAz8LaXUiY,256
+matchlab/resolvers/base.py,sha256=fYq8_tAeprq_dFVclhIGhb4DQWW8Rq_DRFB-CAg-qWc,2056
+matchlab/resolvers/components.py,sha256=h0EuH6jdQaplXhdWnWk3sk2-QtcKH4y_hH5EG1LxL98,2033
+matchlab/resolvers/resolvers.py,sha256=dmbaqsTfU6-qNksMDj_6QwuApN68f3VT26yluzawhPI,17605
+matchlab/testkit/__init__.py,sha256=7e3ynGwMoPDc8gIILa2FROyzxVMqXJa5bBt7qIQ1vos,4411
+matchlab/testkit/_generate.py,sha256=-ZeCrDJVWqmRRKDVmAtAm-xR61q1fblANDCRNM89vHk,8408
+matchlab/testkit/compare.py,sha256=y_6wYqTNemikn7SMG1BCovgm6_l3hvl5vu5d2dZzj5E,6513
+matchlab/testkit/entities.py,sha256=ho1VtZZIimaIIDFgH9kj3HHjRFluurgR9WMRB74yssI,10188
+matchlab/testkit/features.py,sha256=m-X0ItSwlyvX48hQAI8kQNmMA50s__wGnWsw2kqhLV8,4692
+matchlab/testkit/linked.py,sha256=pc1_LmfrL7Jku5yoOXWlnDosNYCQok4KBqDoN7l1nwU,19882
+matchlab/testkit/matchers.py,sha256=JgobKrMVW8wK-INxH4qBzWqoqJootnpC5SZDQ3lwJBU,9773
+matchlab/testkit/models.py,sha256=Ng0kysLxTuiglqO2bnaXljT_OHOLDi7_DSgNe0Dg4a4,6532
+matchlab/testkit/sources.py,sha256=fUL5SefxnOypHrOKiY7DoXDRIvn4tpd7QIF4nstZ9U8,11250
+matchlab/transformers/__init__.py,sha256=zNTpHycQKe6TRsjRDe9_7rbJpjNiVmbPZreOKtB9dhg,771
+matchlab/transformers/base.py,sha256=tW7oIzbAG4exXFcJ2iKKjTyc9t4AgfXF_TjxMR6SpkU,1483
+matchlab/transformers/clean.py,sha256=NvCfl7-KOL-7Wr0-DpKB40tnXhnfrvQvavMitr9N8eE,1992
+matchlab/transformers/explode.py,sha256=k8Q__0aFdntyGxkffu2KWSJmCVCu7ImvJtRt-32Q5j4,2934
+matchlab/transformers/group.py,sha256=SZ5iR646uuiwHyZusTTGfYcFi0dJAmWyXpw9FnY2mxI,2319
+matchlab/transformers/select.py,sha256=s3NmMgL5IS7ifeIhj5ABQJ46XULW6s_kQKASOq7G0sQ,1125
+matchlab/transformers/transform.py,sha256=ws6yS1Z9EZ4fuPB2zOKcNJXSo2Ku-bkKoTh8QpP_bMY,3916
+matchlab-0.1.0.dev1.dist-info/licenses/LICENSE,sha256=7fhYMrjTXiy7Sf-9lBtZHNc4IjHTcfqmGW0AcjFMJJo,1090
+matchlab-0.1.0.dev1.dist-info/METADATA,sha256=hzYyHGefEbnebD4gstmQZZo2nT9stGl93RIwCwmFcF8,3304
+matchlab-0.1.0.dev1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+matchlab-0.1.0.dev1.dist-info/entry_points.txt,sha256=giDdKIeNDxGNWrvoVuLA5mtQjwStupSwxDYmrRjM9Rs,47
+matchlab-0.1.0.dev1.dist-info/top_level.txt,sha256=1ZVLg12gZgkOUbN5CfX-KmLTbHGRbZqFEZPqrfRVN-Y,9
+matchlab-0.1.0.dev1.dist-info/RECORD,,

matchlab-0.1.0.dev1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

matchlab-0.1.0.dev1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+matchlab = matchlab.cli:main

matchlab-0.1.0.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Department for Business and Trade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matchlab-0.1.0.dev1.dist-info/top_level.txt

@@ -0,0 +1 @@
+matchlab