comparator-recommender 0.1.1__tar.gz

comparator_recommender-0.1.1/.github/release-drafter.yml

@@ -0,0 +1,31 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+commitish: main
+
+categories:
+  - title: Breaking Changes
+    labels: ['breaking']
+  - title: Features
+    labels: ['feature']
+  - title: Fixes
+    labels: ['fix']
+  - title: Dependencies
+    labels: ['dependencies']
+
+template: |
+  $CHANGES
+
+change-template: '- **$TITLE** (#$NUMBER) @$AUTHOR'
+
+version-resolver:
+  major:
+    labels: ['breaking']
+  minor:
+    labels: ['feature']
+  patch:
+    labels: ['fix', 'dependencies']
+  default: patch
+
+exclude-labels: ['chore']
+
+autolabeler: []

comparator_recommender-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,10 @@
+name: CI
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+jobs:
+  label-gate:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/label-gate.yml@main
+  build-test:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test.yml@main

comparator_recommender-0.1.1/.github/workflows/compatibility.yml

@@ -0,0 +1,65 @@
+name: Compatibility
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - .github/workflows/compatibility.yml
+      - pyproject.toml
+      - uv.lock
+      - src/**
+      - tests/**
+  push:
+    tags: ['v*']
+  repository_dispatch:
+    types: [groundworkers-compatibility]
+  workflow_dispatch:
+    inputs:
+      groundworkers_version:
+        description: Released Groundworkers version to test
+        required: true
+        default: 0.7.0
+      python_versions:
+        description: Comma-separated Python versions to test
+        required: true
+        default: 3.12,3.13
+  schedule:
+    - cron: "17 3 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    outputs:
+      include: ${{ steps.matrix.outputs.include }}
+    steps:
+      - id: matrix
+        env:
+          REQUESTED_GROUNDWORKERS: ${{ github.event.client_payload.groundworkers_version || inputs.groundworkers_version || '0.7.0' }}
+          REQUESTED_PYTHON_JSON: ${{ toJSON(github.event.client_payload.python_versions) }}
+          INPUT_PYTHON_VERSIONS: ${{ inputs.python_versions || '3.12,3.13' }}
+        run: |
+          python -c 'import json, os; raw=os.environ["REQUESTED_PYTHON_JSON"]; versions=json.loads(raw) if raw not in ("", "null") else [v.strip() for v in os.environ["INPUT_PYTHON_VERSIONS"].split(",") if v.strip()]; gw=os.environ["REQUESTED_GROUNDWORKERS"]; print("include=" + json.dumps({"include": [{"python": version, "groundworkers": gw} for version in versions]}, separators=(",", ":")))' >> "$GITHUB_OUTPUT"
+
+  compatibility:
+    needs: prepare
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.prepare.outputs.include) }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build --wheel --out-dir compatibility-dist
+      - run: uv venv --python "${{ matrix.python }}" .compatibility-venv
+      - run: uv pip install --python .compatibility-venv/bin/python "groundworkers==${{ matrix.groundworkers }}"
+      - run: uv pip install --python .compatibility-venv/bin/python compatibility-dist/*.whl "pytest>=9,<10"
+      - run: .compatibility-venv/bin/python -m pytest -q
+

comparator_recommender-0.1.1/.github/workflows/merge.yml

@@ -0,0 +1,13 @@
+name: Release Update
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+permissions:
+  contents: write
+  pull-requests: read
+jobs:
+  draft:
+    if: github.event.pull_request.merged == true
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/release-drafter.yml@main
+    secrets: inherit

comparator_recommender-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish
+on:
+  push:
+    tags: ['v*']
+jobs:
+  build:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/publish.yml@main
+  publish:
+    # Inline: PyPI OIDC checks job_workflow_ref, which must point to this file.
+    # Moving pypa/gh-action-pypi-publish into cava-devops would break the trusted publisher.
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/comparator-recommender
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: pypa/gh-action-pypi-publish@release/v1

comparator_recommender-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+.ty/
+__pycache__/
+*.py[cod]
+dist/
+data/
+.DS_Store

comparator_recommender-0.1.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: comparator-recommender
+Version: 0.1.1
+Summary: Groundworkers plugin for recommending comparator cohorts.
+Requires-Python: >=3.12
+Requires-Dist: groundworkers[tui]<1,>=0.7
+Requires-Dist: oa-configurator<3,>=2
+Requires-Dist: omop-emb<4,>=3
+Requires-Dist: omop-llm<2,>=1
+Requires-Dist: pandas>=3
+Requires-Dist: pgvector<1,>=0.5
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: sqlalchemy<3,>=2
+Description-Content-Type: text/markdown
+
+# Comparator Recommender
+
+This package is an installable Groundworkers plugin for finding target cohorts
+and recommending pairwise comparators from a precomputed comparator catalogue.
+
+It contributes two entry points:
+
+- `omop.config` exposes `ComparatorRecommenderConfig` to oa-configurator.
+- `groundworkers.plugins` exposes the plugin singleton to Groundworkers.
+
+The configuration schema selects a generic comparator database, optionally selects an embedding model for target lookup, and sets the default minimum database support threshold. Groundworkers builds the setup-console workflow directly from this schema without plugin-specific TUI code.
+
+The setup console also exposes the plugin's registered preparation steps:
+
+- `Load comparator source` asks for the cohort and pairwise-similarity CSVs and loads them into the catalogue.
+- `Create comparator embeddings` generates the stored vectors after the source is loaded.
+
+The CSV paths are run arguments, not persistent plugin configuration. Both steps use Groundworkers' durable maintenance-run surface, so progress and logs appear with the core graph and embedding preparation runs.
+
+Run the MWE against the published Groundworkers 0.7 stack:
+
+```console
+uv sync --group dev
+uv run pytest
+```
+
+The acceptance test selects an existing CDM database, leaves the optional
+embedding resources unconfigured, reviews the generated change, applies it, and
+verifies the resulting `[tools.comparator_recommender]` section.
+
+## Upgrading to the Groundworkers 0.7 stack
+
+This plugin requires `groundworkers[tui]>=0.7,<1`, `oa-configurator>=2,<3`
+and `omop-emb>=3,<4`. For CDM database entries, replace the former
+`schema_name` setting with `cdm_schema`; generic databases such as
+`comparator_db` still use `schema_name`. Remove schema settings from SQLite
+database entries. See the [Groundworkers upgrade guide](https://github.com/AustralianCancerDataNetwork/groundworkers/blob/main/docs/usage/upgrading-from-0.6.md)
+for the shared configuration changes.
+
+**The embedding-store migration script is not available yet.** It is tracked
+in [oa-configurator issue #40](https://github.com/AustralianCancerDataNetwork/oa-configurator/issues/40).
+Existing shared stores created before omop-emb 3.0 report `LEGACY_REGISTRY`.
+The [omop-emb legacy-registry guard and migration-command placeholder](https://github.com/AustralianCancerDataNetwork/omop-emb/blob/main/src/omop_emb/model_registry/model_registry_orm.py)
+remain the source of the planned migration command; follow the issue for its
+availability before attempting migration. This plugin does not migrate shared
+embedding stores.
+
+Comparator vectors live in `cs_cohort.embedding_vector` in the comparator
+database. The plugin uses omop-emb to generate vectors directly from the selected
+model, without opening the shared embedding-store registry. Upgrading the Python
+packages does not migrate or regenerate existing comparator vectors. Keep the
+same embedding model for creation and lookup; if changing models, explicitly
+rerun `Create comparator embeddings` after loading the source catalogue.
+
+## Architecture
+
+The package separates four responsibilities:
+
+- `config.py` declares operator-controlled settings and references to shared OA
+  resources.
+- `adapters.py` owns the resolved database connection and backend.
+- `models.py` reflects the two non-OMOP catalogue tables into SQLAlchemy mappings.
+- `backends/postgresql.py` uses SQLAlchemy `select`, pgvector expressions,
+  mapped row updates, and `Index` objects, with one isolated column migration
+  for older catalogue tables. Its backend initialization follows the
+  `omop-emb` lifecycle and ensures the pgvector extension before setup runs.
+- `services.py` owns input policy and recommendation defaults. It receives
+  ordinary Python values from adapters and contains no MCP code.
+- `tools.py` exposes service operations to agents. Tools should be thin wrappers,
+  not a second implementation of the analysis.
+
+`plugin.py` is the composition root: Groundworkers calls it once during startup
+to connect configuration to adapters and services, then asks it to register the
+tools. Business logic should not be implemented inside `build()`.
+
+The comparator catalogue is not an OMOP CDM table, so it should not be added to
+`omop-alchemy`'s model registry. The local reflected mapping follows the same
+SQLAlchemy model/query conventions while leaving the shared OMOP package focused
+on CDM semantics.

comparator_recommender-0.1.1/README.md

@@ -0,0 +1,79 @@
+# Comparator Recommender
+
+This package is an installable Groundworkers plugin for finding target cohorts
+and recommending pairwise comparators from a precomputed comparator catalogue.
+
+It contributes two entry points:
+
+- `omop.config` exposes `ComparatorRecommenderConfig` to oa-configurator.
+- `groundworkers.plugins` exposes the plugin singleton to Groundworkers.
+
+The configuration schema selects a generic comparator database, optionally selects an embedding model for target lookup, and sets the default minimum database support threshold. Groundworkers builds the setup-console workflow directly from this schema without plugin-specific TUI code.
+
+The setup console also exposes the plugin's registered preparation steps:
+
+- `Load comparator source` asks for the cohort and pairwise-similarity CSVs and loads them into the catalogue.
+- `Create comparator embeddings` generates the stored vectors after the source is loaded.
+
+The CSV paths are run arguments, not persistent plugin configuration. Both steps use Groundworkers' durable maintenance-run surface, so progress and logs appear with the core graph and embedding preparation runs.
+
+Run the MWE against the published Groundworkers 0.7 stack:
+
+```console
+uv sync --group dev
+uv run pytest
+```
+
+The acceptance test selects an existing CDM database, leaves the optional
+embedding resources unconfigured, reviews the generated change, applies it, and
+verifies the resulting `[tools.comparator_recommender]` section.
+
+## Upgrading to the Groundworkers 0.7 stack
+
+This plugin requires `groundworkers[tui]>=0.7,<1`, `oa-configurator>=2,<3`
+and `omop-emb>=3,<4`. For CDM database entries, replace the former
+`schema_name` setting with `cdm_schema`; generic databases such as
+`comparator_db` still use `schema_name`. Remove schema settings from SQLite
+database entries. See the [Groundworkers upgrade guide](https://github.com/AustralianCancerDataNetwork/groundworkers/blob/main/docs/usage/upgrading-from-0.6.md)
+for the shared configuration changes.
+
+**The embedding-store migration script is not available yet.** It is tracked
+in [oa-configurator issue #40](https://github.com/AustralianCancerDataNetwork/oa-configurator/issues/40).
+Existing shared stores created before omop-emb 3.0 report `LEGACY_REGISTRY`.
+The [omop-emb legacy-registry guard and migration-command placeholder](https://github.com/AustralianCancerDataNetwork/omop-emb/blob/main/src/omop_emb/model_registry/model_registry_orm.py)
+remain the source of the planned migration command; follow the issue for its
+availability before attempting migration. This plugin does not migrate shared
+embedding stores.
+
+Comparator vectors live in `cs_cohort.embedding_vector` in the comparator
+database. The plugin uses omop-emb to generate vectors directly from the selected
+model, without opening the shared embedding-store registry. Upgrading the Python
+packages does not migrate or regenerate existing comparator vectors. Keep the
+same embedding model for creation and lookup; if changing models, explicitly
+rerun `Create comparator embeddings` after loading the source catalogue.
+
+## Architecture
+
+The package separates four responsibilities:
+
+- `config.py` declares operator-controlled settings and references to shared OA
+  resources.
+- `adapters.py` owns the resolved database connection and backend.
+- `models.py` reflects the two non-OMOP catalogue tables into SQLAlchemy mappings.
+- `backends/postgresql.py` uses SQLAlchemy `select`, pgvector expressions,
+  mapped row updates, and `Index` objects, with one isolated column migration
+  for older catalogue tables. Its backend initialization follows the
+  `omop-emb` lifecycle and ensures the pgvector extension before setup runs.
+- `services.py` owns input policy and recommendation defaults. It receives
+  ordinary Python values from adapters and contains no MCP code.
+- `tools.py` exposes service operations to agents. Tools should be thin wrappers,
+  not a second implementation of the analysis.
+
+`plugin.py` is the composition root: Groundworkers calls it once during startup
+to connect configuration to adapters and services, then asks it to register the
+tools. Business logic should not be implemented inside `build()`.
+
+The comparator catalogue is not an OMOP CDM table, so it should not be added to
+`omop-alchemy`'s model registry. The local reflected mapping follows the same
+SQLAlchemy model/query conventions while leaving the shared OMOP package focused
+on CDM semantics.

comparator_recommender-0.1.1/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "comparator-recommender"
+version = "0.1.1"
+description = "Groundworkers plugin for recommending comparator cohorts."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "groundworkers[tui]>=0.7,<1",
+  "oa-configurator>=2,<3",
+  "omop-emb>=3,<4",
+  "omop-llm>=1,<2",
+  "pandas>=3",
+  "pgvector>=0.5,<1",
+  "pydantic>=2,<3",
+  "SQLAlchemy>=2,<3",
+]
+
+[project.entry-points."omop.config"]
+comparator_recommender = "comparator_recommender.config:ComparatorRecommenderConfig"
+
+[project.entry-points."groundworkers.plugins"]
+comparator_recommender = "comparator_recommender.plugin:plugin"
+
+[dependency-groups]
+dev = [
+  "groundskeeping>=0.9.1,<1",
+  "pytest>=9,<10",
+  "ruff>=0.4",
+  "ty>=0.0.59",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+constraint-dependencies = ["setuptools>=83.0.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/comparator_recommender"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "RUF"]
+
+[tool.ty.src]
+include = ["src"]

comparator_recommender-0.1.1/src/comparator_recommender/__init__.py

@@ -0,0 +1,10 @@
+"""Comparator Recommender plugin configuration MWE."""
+
+from comparator_recommender.config import ComparatorRecommenderConfig
+from comparator_recommender.plugin import ComparatorRecommenderPlugin, plugin
+
+__all__ = [
+    "ComparatorRecommenderConfig",
+    "ComparatorRecommenderPlugin",
+    "plugin",
+]

comparator_recommender-0.1.1/src/comparator_recommender/adapters.py

@@ -0,0 +1,57 @@
+"""Connections to the comparator catalogue and its embedding model."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from groundworkers.plugins import PluginReadinessResult
+from oa_configurator import ResolvedDatabase
+from omop_llm import ModelBackend
+
+from comparator_recommender.backends import (
+    ComparatorSelectorBackend,
+    PostgresComparatorSelectorBackend,
+)
+
+
+@dataclass(frozen=True)
+class ComparatorDataAdapter:
+    """Own the database-backed comparator operations."""
+
+    database: ResolvedDatabase
+    backend: ComparatorSelectorBackend
+
+    @classmethod
+    def build(
+        cls,
+        database: ResolvedDatabase,
+        model_backend_factory: Callable[[], ModelBackend] | None = None,
+        model_source: str | None = None,
+    ) -> "ComparatorDataAdapter":
+        return cls(
+            database=database,
+            backend=PostgresComparatorSelectorBackend(
+                engine=database.create_engine(register_claims=False),
+                schema=database.schema_name or "public",
+                model_backend_factory=model_backend_factory,
+                model_source=model_source,
+            ),
+        )
+
+    def find_target(self, name: str, top_n: int) -> list[tuple[int, str]]:
+        return self.backend.find_target(name, top_n)
+
+    def recommend_comparators(
+        self, target_id: int, top_n: int, min_databases: int
+    ) -> list[tuple[float, str]]:
+        return self.backend.recommend_comparators(target_id, top_n, min_databases)
+
+    def insert_data(self, cohort_table_path: str, similarity_table_path: str) -> None:
+        self.backend.insert_data(cohort_table_path, similarity_table_path)
+
+    def create_embedding_vectors(self) -> None:
+        self.backend.create_embedding_vectors()
+
+    def verify_readiness(self) -> PluginReadinessResult:
+        """Return the backend's read-only readiness report."""
+
+        return self.backend.verify_readiness()

comparator_recommender-0.1.1/src/comparator_recommender/backends/__init__.py

@@ -0,0 +1,6 @@
+"""Backend implementations for comparator catalogue storage."""
+
+from comparator_recommender.backends.base import ComparatorSelectorBackend
+from comparator_recommender.backends.postgresql import PostgresComparatorSelectorBackend
+
+__all__ = ["ComparatorSelectorBackend", "PostgresComparatorSelectorBackend"]

comparator_recommender-0.1.1/src/comparator_recommender/backends/base.py

@@ -0,0 +1,54 @@
+"""Storage-independent comparator backend contract."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+
+from groundworkers.plugins import PluginReadinessResult
+from omop_llm import ModelBackend
+from sqlalchemy import Engine
+
+
+class ComparatorSelectorBackend(ABC):
+    """Operations required by the comparator recommender service."""
+
+    def __init__(
+        self,
+        engine: Engine,
+        schema: str,
+        model_backend_factory: Callable[[], ModelBackend] | None = None,
+        model_source: str | None = None,
+    ) -> None:
+        if not schema.strip():
+            raise ValueError("schema must not be empty")
+        self.engine = engine
+        self.schema = schema
+        self.model_backend_factory = model_backend_factory
+        self.model_source = model_source
+
+    def pre_initialise_store(self) -> None:
+        """Prepare mutating setup prerequisites; the default is a no-op.
+
+        Backend construction and readiness checks are deliberately read-only.
+        Mutating setup operations call this hook explicitly when needed.
+        """
+
+    @abstractmethod
+    def find_target(self, name: str, top_n: int) -> list[tuple[int, str]]: ...
+
+    @abstractmethod
+    def recommend_comparators(
+        self, target_id: int, top_n: int, min_databases: int
+    ) -> list[tuple[float, str]]: ...
+
+    @abstractmethod
+    def insert_data(
+        self, cohort_table_path: str, similarity_table_path: str
+    ) -> None: ...
+
+    @abstractmethod
+    def create_embedding_vectors(self) -> None: ...
+
+    @abstractmethod
+    def verify_readiness(self) -> PluginReadinessResult: ...