matchbox-db 0.7.14.dev46__tar.gz → 0.7.14.dev90__tar.gz

matchbox_db-0.7.14.dev90/.github/dependabot.yml

@@ -0,0 +1,11 @@
+---
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: "weekly"

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/.github/workflows/ci.yml

@@ -13,13 +13,16 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
 
       - name: Install just
-        uses: extractions/setup-just@v2
+        uses: extractions/setup-crate@4993624604c307fbca528d28a3c8b60fa5ecc859 # v1.4.0
+        with:
+          repo: casey/just
+          version: 1.42.4
 
       - name: Format and lint
         run: just format
@@ -37,10 +40,10 @@ jobs:
           - "3.13"
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
@@ -60,7 +63,7 @@ jobs:
 
       - name: Dump docker logs
         if: failure()
-        uses: jwalton/gh-docker-logs@v2
+        uses: jwalton/gh-docker-logs@2741064ab9d7af54b0b1ffb6076cf64c16f0220e # v2.2.2
 
   scan-for-secrets:
     runs-on: ubuntu-latest
@@ -68,7 +71,7 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
 
@@ -90,10 +93,10 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
         with:
           python-version: "3.11"
 
@@ -109,12 +112,12 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
 
       - name: Install uv and Python
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
         with:
           python-version: "3.11"
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/.github/workflows/codeql.yml

@@ -33,17 +33,17 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Initialise CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@cf1bb45a277cb3c205638b2cd5c984db1c46a412 # v4.31.7
         with:
           languages: ${{ matrix.language }}
 
           # Details on CodeQL's query packs refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
-          queries: security-and-quality
+          queries: security-extended
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@cf1bb45a277cb3c205638b2cd5c984db1c46a412 # v4.31.7
         with:
           category: "/language:${{matrix.language}}"

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/.github/workflows/prerelease.yml

@@ -19,19 +19,19 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
 
       - name: Log in to GitHub packages Docker registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
         with: 
           python-version: "3.11"
 
@@ -47,14 +47,14 @@ jobs:
         run: uv build
 
       - name: Upload package artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: package-dist
           path: ./dist
 
       - name: Extract tag metadata for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
@@ -62,7 +62,7 @@ jobs:
             type=raw,value=development
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
         with:
           context: .
           file: src/matchbox/server/Dockerfile
@@ -78,10 +78,11 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Create development prerelease
-        uses: ncipollo/release-action@v1
+        uses: ncipollo/release-action@b7eabc95ff50cbeeedec83973935c8f306dfcd0b # v1.20.0
         with:
           tag: development
           name: Development
+          immutableCreate: true
           prerelease: true
           body: |
             This is a development build, usually from the latest main branch. 
@@ -101,10 +102,10 @@ jobs:
     
     steps:
       - name: Download package artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: package-dist
           path: ./dist
 
       - name: Publish package to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/.github/workflows/release.yml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           ref: main
           fetch-depth: 0
@@ -66,7 +66,7 @@ jobs:
           echo "Git tag: $git_tag"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
         with: 
           python-version: "3.11"
 
@@ -76,7 +76,7 @@ jobs:
         run: uv build
 
       - name: Upload package artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: package-dist
           path: ./dist
@@ -88,12 +88,12 @@ jobs:
         run: uv run mkdocs build
 
       - name: Upload documentation artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
         with:
           path: site/
 
       - name: Log in to GitHub packages Docker registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -101,7 +101,7 @@ jobs:
 
       - name: Extract tag metadata for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
@@ -109,7 +109,7 @@ jobs:
             type=raw,value=latest
 
       - name: Build Docker image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
         with:
           context: .
           file: src/matchbox/server/Dockerfile
@@ -126,7 +126,7 @@ jobs:
             > ${{ runner.temp }}/docker-image.tar
 
       - name: Upload Docker image artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: docker-image
           path: ${{ runner.temp }}/docker-image.tar
@@ -141,13 +141,13 @@ jobs:
     
     steps:
       - name: Download package artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: package-dist
           path: ./dist
 
       - name: Publish package to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
 
   deploy-docs:
     needs: build
@@ -164,7 +164,7 @@ jobs:
     steps:
       - name: Deploy documentation to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
 
   deploy-docker:
     needs: build
@@ -175,7 +175,7 @@ jobs:
     
     steps:
       - name: Download Docker image artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: docker-image
           path: ${{ runner.temp }}
@@ -184,7 +184,7 @@ jobs:
         run: docker load --input ${{ runner.temp }}/docker-image.tar
 
       - name: Log in to GitHub packages Docker registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -201,8 +201,9 @@ jobs:
 
     steps:
       - name: Create tag and GitHub release
-        uses: ncipollo/release-action@v1
+        uses: ncipollo/release-action@b7eabc95ff50cbeeedec83973935c8f306dfcd0b # v1.20.0
         with:
           tag: ${{ needs.build.outputs.tag }}
           name: ${{ needs.build.outputs.tag }}
+          immutableCreate: true
           generateReleaseNotes: true

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
 
 # Mandatory internal hooks
 - repo: https://github.com/uktrade/github-standards
-  rev: v1.1.2  # update periodically with pre-commit autoupdate
+  rev: v1.2.0  # update periodically with pre-commit autoupdate
   hooks:
     - id: run-security-scan
       verbose: false

{matchbox_db-0.7.14.dev46/src/matchbox_db.egg-info → matchbox_db-0.7.14.dev90}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matchbox-db
-Version: 0.7.14.dev46
+Version: 0.7.14.dev90
 Summary: A framework for orchestrating and comparing data linking and deduplication methodologies.
 Author: Department for Business and Trade
 Project-URL: Documentation, https://uktrade.github.io/matchbox/
@@ -11,12 +11,14 @@ License-File: LICENSE
 Requires-Dist: click>=8.1.7
 Requires-Dist: cryptography>=44.0.2
 Requires-Dist: duckdb>=1.1.1
+Requires-Dist: email-validator>=2.3.0
 Requires-Dist: faker>=36.1.1
 Requires-Dist: frozendict>=2.4.6
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: pandas>=2.2.3
 Requires-Dist: polars-hash>=0.5.3
 Requires-Dist: polars>=1.32.3
+Requires-Dist: psutil>=7.1.3
 Requires-Dist: psycopg[binary,pool]>=3.2.6
 Requires-Dist: pyarrow>=17.0.0
 Requires-Dist: pydantic-settings>=2.5.2
@@ -29,7 +31,6 @@ Requires-Dist: sqlglot[rs]>=26.12.1
 Requires-Dist: tenacity>=9.1.2
 Requires-Dist: textual>=0.87.1
 Requires-Dist: typer>=0.15.0
-Requires-Dist: psutil>=7.1.3
 Provides-Extra: server
 Requires-Dist: adbc-driver-postgresql>=1.5.0; extra == "server"
 Requires-Dist: alembic>=1.15.2; extra == "server"

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/docs/client/evaluation.md

@@ -7,20 +7,36 @@ After running models to deduplicate and link your data, you’ll likely want to
 
 To calculate these, we need a **ground truth** - a set of correct matches created by people. This is called **validation data**.
 
+## Creating a sample set
+
+First, you need to create a local set of sample clusters that you want to evaluate. If you're evaluating a single model:
+
+```python
+dag = ... # your DAG, defined elsewhere 
+dag.resolve().as_dump().write_parquet("samples.pq")
+```
+
+Or, if you're comparing two models:
+
+```python
+dag = ... # your DAG, defined elsewhere
+
+resolved_model1 = dag.resolve("model1")
+resolved_model2 = dag.resolve("model2")
+# Forms clusters as the union of the clusters output by each model
+resolved_joint = resolved_model1.merge(resolved_model2)
+resolved_joint.as_dump().write_parquet("samples.pq")
+```
+
 ## Creating validation data
 
 Matchbox provides a terminal-based UI to help you create this validation data. Here's how it works:
 
-1. **Launch the evaluation tool** using `matchbox eval --collection <collection_name> --user <your_username>`
-    a. You can also set your username with the `MB__CLIENT__USER` environment variable.
-    b. Define `MB__CLIENT__DEFAULT_WAREHOUSE` (or use `--warehouse <connection_string>`) so the CLI can reach your warehouse.
-    c. If your DAG isn't complete, include `--resolution <resolution_name>` to pick a specific run.
-2. Matchbox will **download clusters** for you to review. It avoids clusters you've already judged and focuses on ones the model is unsure about.
-3. In the terminal interface, you'll review each cluster:
-   * Use keyboard commands like `b+1,3,5` to assign rows 1, 3, and 5 to group B
-   * Press `space` to send your judgements to Matchbox
-   * Skip to the next item without reviewing with `→` (right arrow)
-   * Press `?` or `F1` for help with commands
+1. **Launch the evaluation tool** using `matchbox eval --collection <collection_name> --user <your_username> --file <path_to_samples>`
+    - Define `MB__CLIENT__DEFAULT_WAREHOUSE` (or use `--warehouse <connection_string>`) so the CLI can reach your warehouse.
+    - Use `--tag <session_tag>` to tag your judgements so they can be filtered later
+2. Matchbox will **load clusters** from your warehouse, for you to review.  
+3. In the terminal interface, you will review each cluster.  
 
 Once enough users have reviewed clusters, this data can be used to evaluate model performance.
 
@@ -80,11 +96,11 @@ model = source.query().deduper(
 results = model.run()
 ```
 
-Download validation data:
+Download validation data, filtering by tag:
 
 ```python
 from matchbox.client.eval import EvalData
-eval_data = EvalData()
+eval_data = EvalData(tag="companies__15_02_2025")
 ```
 
 Check precision and recall at a specific threshold:
@@ -93,17 +109,6 @@ Check precision and recall at a specific threshold:
 precision, recall = eval_data.precision_recall(results, threshold=0.5)
 ```
 
-Compare multiple model resolutions:
-
-```python
-from matchbox.client.eval import compare_models, ModelResolutionPath
-
-comparison = compare_models([
-    ModelResolutionPath(collection="companies", run=1, name="deduper"),
-    ModelResolutionPath(collection="companies", run=2, name="deduper"),
-])
-```
-
 !!! tip "Deterministic models"
     Some types of model (like the `NaiveDeduper` used in the example) only output 1s for the matches they make, hence **threshold truth tuning doesn't apply**:
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/docs/contributing.md

@@ -166,3 +166,22 @@ We commit as frequently as possible. We keep our commits as atomic as possible.
 ### AI
 
 In order to help reviewers prioritise their time appropriately, we expect any use of AI to be declared in your PR comment.
+
+### Actions
+
+In order to avoid supply chain attacks, we [pin all actions in workflows](https://codeql.github.com/codeql-query-help/actions/actions-unpinned-tag/).
+
+When upgrading actions, we expect PR comments to confirm that the new commit is safe. You need to cover:
+
+* That the commit's `action.yml` only uses pinned child actions, if it has children
+* That there are no critical security concerns raised in the issues
+
+See [#395](https://github.com/uktrade/matchbox/pull/395) for an example of the due diligence we expect.
+
+We suggest using tools like [`wayneashleyberry/gh-act`](https://github.com/wayneashleyberry/gh-act) to help manage this, allowing you to perform the upgrade in a single line:
+
+```shell
+gh act update --pin
+```
+
+You will still need to independently verify that the new pins are safe.

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/pyproject.toml

@@ -10,12 +10,14 @@ dependencies = [
     "click>=8.1.7",
     "cryptography>=44.0.2",
     "duckdb>=1.1.1",
+    "email-validator>=2.3.0",
     "faker>=36.1.1",
     "frozendict>=2.4.6",
     "httpx>=0.28.0",
     "pandas>=2.2.3",
     "polars-hash>=0.5.3",
     "polars>=1.32.3",
+    "psutil>=7.1.3",
     "psycopg[binary, pool]>=3.2.6",
     "pyarrow>=17.0.0",
     "pydantic-settings>=2.5.2",
@@ -28,7 +30,6 @@ dependencies = [
     "tenacity>=9.1.2",
     "textual>=0.87.1",
     "typer>=0.15.0",
-    "psutil>=7.1.3"
 ]
 
 [project.optional-dependencies]
@@ -89,7 +90,8 @@ default-groups = ["dev", "typing"]
 package = true
 upgrade-package = ["ruff"]
 constraint-dependencies = [
-    "urllib3>=2.5.0",
+    "urllib3>=2.6.0",
+    "werkzeug>=3.1.4",
     "setuptools-scm>=9.2.0"
 ]
 

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/src/matchbox/client/_handler.py

@@ -50,7 +50,7 @@ from matchbox.common.dtos import (
     UploadStage,
     User,
 )
-from matchbox.common.eval import Judgement, ModelComparison
+from matchbox.common.eval import Judgement
 from matchbox.common.exceptions import (
     MatchboxCollectionNotFoundError,
     MatchboxDataNotFound,
@@ -189,7 +189,7 @@ def login(user_name: str) -> int:
     """Log into Matchbox and return the user ID."""
     logger.debug(f"Log in attempt for {user_name}")
     response = CLIENT.post("/auth/login", json=User(user_name=user_name).model_dump())
-    return User.model_validate(response.json()).user_id
+    return User.model_validate(response.json()).user_name
 
 
 @http_retry
@@ -515,7 +515,7 @@ def delete_resolution(
 
 
 @http_retry
-def sample_for_eval(n: int, resolution: ModelResolutionPath, user_id: int) -> Table:
+def sample_for_eval(n: int, resolution: ModelResolutionPath, user_name: str) -> Table:
     """Sample model results for evaluation."""
     res = CLIENT.get(
         "/eval/samples",
@@ -525,7 +525,7 @@ def sample_for_eval(n: int, resolution: ModelResolutionPath, user_id: int) -> Ta
                 "collection": resolution.collection,
                 "run_id": resolution.run,
                 "resolution": resolution.name,
-                "user_id": user_id,
+                "user_name": user_name,
             }
         ),
     )
@@ -533,31 +533,21 @@ def sample_for_eval(n: int, resolution: ModelResolutionPath, user_id: int) -> Ta
     return read_table(BytesIO(res.content))
 
 
-@http_retry
-def compare_models(
-    resolutions: list[ModelResolutionPath],
-) -> ModelComparison:
-    """Get a model comparison for a set of model resolutions."""
-    res = CLIENT.post("/eval/compare", json=[r.model_dump() for r in resolutions])
-    scores = {resolution: tuple(pr) for resolution, pr in res.json().items()}
-    return scores
-
-
 @http_retry
 def send_eval_judgement(judgement: Judgement) -> None:
     """Send judgements to the server."""
     logger.debug(
         f"Submitting judgement {judgement.shown}:{judgement.endorsed} "
-        f"for {judgement.user_id}"
+        f"for {judgement.user_name}"
     )
     CLIENT.post("/eval/judgements", json=judgement.model_dump())
 
 
 @http_retry
-def download_eval_data() -> tuple[Table, Table]:
+def download_eval_data(tag: str | None = None) -> tuple[Table, Table]:
     """Download all judgements from the server."""
     logger.debug("Retrieving all judgements.")
-    res = CLIENT.get("/eval/judgements")
+    res = CLIENT.get("/eval/judgements", params=url_params({"tag": tag}))
 
     zip_bytes = BytesIO(res.content)
     with zipfile.ZipFile(zip_bytes, "r") as zip_file:
@@ -592,8 +582,7 @@ def count_backend_items(
     log_prefix = "Backend count"
     logger.debug("Counting", prefix=log_prefix)
 
-    params = {"entity": entity} if entity else {}
-    res = CLIENT.get("/database/count", params=url_params(params))
+    res = CLIENT.get("/database/count", params=url_params({"entity": entity}))
 
     counts = res.json()
     logger.debug(f"Counts: {counts}", prefix=log_prefix)

{matchbox_db-0.7.14.dev46 → matchbox_db-0.7.14.dev90}/src/matchbox/client/_settings.py

@@ -42,7 +42,7 @@ class ClientSettings(BaseSettings):
             # Decode header and payload
             header = json.loads(base64.urlsafe_b64decode(parts[0] + "=="))
             payload = json.loads(base64.urlsafe_b64decode(parts[1] + "=="))
-        except Exception as e:  # noqa: BLE0001
+        except Exception as e:  # noqa: BLE001
             raise ValueError("Invalid JWT.") from e
 
         # Basic header checks