matchbox-db 0.7.14.dev51__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.dev51 → 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.dev51 → 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.dev51 → 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.dev51 → 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.dev51 → 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.dev51/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.dev51
+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/
@@ -18,6 +18,7 @@ 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

{matchbox_db-0.7.14.dev51 → 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.dev51 → 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.dev51 → matchbox_db-0.7.14.dev90}/pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
     "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",
@@ -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.dev51 → 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,
@@ -65,7 +65,7 @@ from matchbox.common.exceptions import (
     MatchboxUserNotFoundError,
 )
 from matchbox.common.hash import hash_to_base64
-from matchbox.common.logging import logger, profile
+from matchbox.common.logging import logger, profile_time
 
 URLEncodeHandledType = str | int | float | bytes | StrEnum
 
@@ -422,7 +422,7 @@ def update_resolution(
     return ResourceOperationStatus.model_validate(res.json())
 
 
-@profile(kwarg="path")
+@profile_time(kwarg="path")
 @http_retry
 def get_resolution(path: ResolutionPath) -> Resolution | None:
     """Get a resolution from Matchbox."""
@@ -435,7 +435,7 @@ def get_resolution(path: ResolutionPath) -> Resolution | None:
     return Resolution.model_validate(res.json())
 
 
-@profile(kwarg="path")
+@profile_time(kwarg="path")
 @http_retry
 def set_data(path: ResolutionPath, data: pl.DataFrame | Table) -> None:
     """Upload source hashes or model results to server."""
@@ -482,7 +482,7 @@ def get_resolution_stage(path: ResolutionPath) -> UploadStage:
     return upload_info.stage
 
 
-@profile(kwarg="path")
+@profile_time(kwarg="path")
 @http_retry
 def get_results(path: ModelResolutionPath) -> Table:
     """Get model results from Matchbox."""
@@ -533,16 +533,6 @@ def sample_for_eval(n: int, resolution: ModelResolutionPath, user_name: str) ->
     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."""
@@ -554,10 +544,10 @@ def send_eval_judgement(judgement: Judgement) -> None:
 
 
 @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.dev51 → matchbox_db-0.7.14.dev90}/src/matchbox/client/cli/eval/app.py

@@ -19,7 +19,7 @@ from matchbox.client.cli.eval.widgets.styling import get_group_style
 from matchbox.client.cli.eval.widgets.table import ComparisonDisplayTable
 from matchbox.client.dags import DAG
 from matchbox.client.eval import EvaluationItem, create_judgement, get_samples
-from matchbox.common.dtos import ModelResolutionName, ModelResolutionPath
+from matchbox.common.dtos import ModelResolutionPath
 from matchbox.common.exceptions import MatchboxClientSettingsException
 
 logger = logging.getLogger(__name__)
@@ -110,6 +110,8 @@ class EntityResolutionApp(App):
     resolution: ModelResolutionPath
     user_name: str
     dag: DAG
+    session_tag: str | None
+    sample_file: str | None
     show_help: bool
 
     queue: EvaluationQueue
@@ -117,10 +119,12 @@ class EntityResolutionApp(App):
 
     def __init__(
         self,
-        resolution: ModelResolutionName,
         user: str,
         num_samples: int = 5,
+        resolution: ModelResolutionPath | None = None,
         dag: DAG | None = None,
+        session_tag: str | None = None,
+        sample_file: str | None = None,
         show_help: bool = False,
         scroll_debounce_delay: float | None = 0.3,
     ) -> None:
@@ -131,20 +135,30 @@ class EntityResolutionApp(App):
             num_samples: Number of clusters to sample for evaluation
             user: Username for authentication (overrides settings)
             dag: Pre-loaded DAG with warehouse location attached
+            session_tag: String to use for tagging judgements
+            sample_file: Path to pre-compiled sample file.
+                If set, ignores resolutions.
             show_help: Whether to show help on start
             scroll_debounce_delay: Delay before updating column headers after scroll.
                 Set to None to disable debouncing (useful for tests).
         """
         super().__init__()
 
-        self.queue = EvaluationQueue()
-        self.sample_limit = num_samples
+        if not (resolution or sample_file):
+            raise ValueError("Either a resolution or a sample file must be set")
+
+        self.resolution = resolution
         self.user_name = user
+        self.sample_limit = num_samples
         self.dag = dag
-        self.resolution = dag.get_model(resolution).resolution_path
+        self.session_tag = session_tag
+        self.sample_file = sample_file
+
         self.show_help = show_help
         self._scroll_debounce_delay = scroll_debounce_delay
 
+        self.queue = EvaluationQueue()
+
     # Lifecycle methods
     def compose(self) -> ComposeResult:
         """Compose the main application UI."""
@@ -323,9 +337,10 @@ class EntityResolutionApp(App):
         try:
             new_samples_dict = get_samples(
                 n=needed,
-                resolution=self.resolution.name,
+                resolution=self.resolution.name if self.resolution else None,
                 user_name=self.user_name,
                 dag=self.dag,
+                sample_file=self.sample_file,
             )
         except Exception as e:  # noqa: BLE001
             logger.warning(f"Failed to fetch samples: {type(e).__name__}: {e}")
@@ -371,7 +386,10 @@ class EntityResolutionApp(App):
             if self.user_name is None:
                 raise RuntimeError("User name is not set")
             judgement = create_judgement(
-                current.item, current.assignments, self.user_name
+                item=current.item,
+                assignments=current.assignments,
+                user_name=self.user_name,
+                tag=self.session_tag,
             )
             _handler.send_eval_judgement(judgement)
         except Exception as exc:

{matchbox_db-0.7.14.dev51 → matchbox_db-0.7.14.dev90}/src/matchbox/client/cli/eval/run.py

@@ -51,6 +51,22 @@ def evaluate(
             help="Log file path to redirect all logging output (keeps UI clean)",
         ),
     ] = None,
+    sample_file: Annotated[
+        str | None,
+        typer.Option(
+            "--file",
+            "-f",
+            help="Pre-compiled sample file. If set, ignores resolutions parameters.",
+        ),
+    ] = None,
+    session_tag: Annotated[
+        str | None,
+        typer.Option(
+            "--tag",
+            "-t",
+            help="String to use to tag judgements sent to the server.",
+        ),
+    ] = None,
 ) -> None:
     """Start the interactive entity resolution evaluation tool.
 
@@ -88,9 +104,11 @@ def evaluate(
     try:
         # Create app with loaded DAG (not warehouse string)
         app = EntityResolutionApp(
-            resolution=model.resolution_path.name,
+            resolution=model.resolution_path,
             user=user,
             dag=dag,
+            session_tag=session_tag,
+            sample_file=sample_file,
             show_help=True,
         )
         app.run()