Cleanup/lean package

.github/workflows/code-quality-main.yaml

@@ -13,10 +13,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

.github/workflows/code-quality-pr.yaml

@@ -16,10 +16,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

.github/workflows/test.yml

@@ -18,14 +18,14 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up conda env (spatial-pinned)
         uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: spatial
           environment-file: environment.ci-spatial.yaml
-          auto-activate-base: false
+          auto-activate: false
           mamba-version: "*"
           channels: pyg,pytorch,conda-forge,defaults
           channel-priority: flexible
@@ -61,14 +61,14 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up conda env (spatial-pinned)
         uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: spatial
           environment-file: environment.ci-spatial.yaml
-          auto-activate-base: false
+          auto-activate: false
           mamba-version: "*"
           channels: pyg,pytorch,conda-forge,defaults
           channel-priority: flexible
@@ -77,7 +77,40 @@ jobs:
         shell: bash -el {0}
         run: |
           pip install pytest-cov[toml]
-          pytest --cov src
+          pytest --cov grass_mil
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v5
+
+  packaging:
+    name: Install from source and run the CLI
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      # A plain pip install, deliberately outside conda: this is the path a
+      # downstream user takes, and it is the one that silently rots when the
+      # package layout or the config tree moves.
+      - name: Install the package
+        run: pip install .
+
+      - name: Entrypoints resolve packaged configs from an unrelated directory
+        run: |
+          mkdir -p "${RUNNER_TEMP}/elsewhere"
+          cd "${RUNNER_TEMP}/elsewhere"
+          grass-mil-train --help
+          grass-mil-report --help
+          python -c "import grass_mil, grass_mil.configs; print(grass_mil.__file__)"
+
+      - name: Packaging contract tests
+        run: |
+          pip install pytest
+          pytest -v tests/test_packaging.py

Makefile

@@ -20,11 +20,8 @@ sync: ## Merge changes from main branch to your current branch
 	git pull
 	git pull origin main
 
-test: ## Run not slow tests
-	pytest -k "not slow"
-
-test-full: ## Run all tests
+test: ## Run the test suite
 	pytest
 
 train: ## Train the model
-	python src/train.py
+	grass-mil-train

README.md

@@ -14,10 +14,10 @@ Geometric deep learning framework for spatial omics data, built around a Hydra-c
 
 Core architecture:
 
-- Data pipeline: `src/data/` + `configs/data/`
-- Model/runtime pipeline: `src/models/` + `configs/model/` + `configs/task/`
-- Interpretability pipeline: `src/interpretability/` + `configs/interpretability/`
-- Entrypoints: `src/train.py`, `src/eval.py`
+- Data pipeline: `src/grass_mil/data/` + `configs/data/`
+- Model/runtime pipeline: `src/grass_mil/models/` + `configs/model/` + `configs/task/`
+- Interpretability pipeline: `src/grass_mil/interpretability/` + `configs/interpretability/`
+- Entrypoints: `src/grass_mil/train.py`, `src/grass_mil/eval.py`
 - Configuration system: `configs/` (Hydra groups)
 
 ## Interpretability
@@ -32,7 +32,7 @@ Core architecture:
 Quick run:
 
 ```bash
-python src/interpretability/report_cli.py \
+grass-mil-report \
   data.instance_table=/absolute/path/to/instance_table.csv \
   data.spatial_table=/absolute/path/to/spatial_table.csv
 ```
@@ -42,16 +42,30 @@ python src/interpretability/report_cli.py \
 ### 1) Install
 
 ```bash
-cd /Users/lovrorabuzin/Projects/grass-mil_unification/grass-mil
+git clone git@github.com:BoevaLab/grass-mil.git
+cd grass-mil
 python -m venv .venv
 source .venv/bin/activate
-pip install -r requirements.txt
+
+# Editable install for development; drop -e for a plain install.
+pip install -e .
+
+# Optional extras: interpretability plots, report rendering, spatial statistics,
+# and the h5ad/SingleCellExperiment readers.
+pip install -e ".[interpretability,report,spatial-stats,io]"
 ```
 
-Set project root for Hydra path resolution:
+Installing exposes the CLI entrypoints (`grass-mil-train`, `grass-mil-eval`,
+`grass-mil-loocv`, `grass-mil-predict`, `grass-mil-report`). The Hydra config
+tree ships inside the package, so it resolves from any working directory.
+
+Hydra's `paths.root_dir` defaults to the `PROJECT_ROOT` environment variable
+when set (`rootutils` exports it automatically from the `.project-root` marker
+in a source checkout) and otherwise falls back to the current working
+directory. Set it explicitly to place `data/` and `logs/` elsewhere:
 
 ```bash
-export PROJECT_ROOT=/Users/lovrorabuzin/Projects/grass-mil_unification/grass-mil
+export PROJECT_ROOT=/path/to/your/workspace
 ```
 
 ### 2) Prepare New Data
@@ -67,16 +81,19 @@ Optional:
 - `region_id`
 - `polygons_path`
 
+For the full onboarding checklist and dataset schema details, see
+[`docs/dataset_preparation.md`](docs/dataset_preparation.md).
+
 ### 3) Run Default Supervised Pipeline
 
 ```bash
-python src/train.py task=finetune_mean model=supervised_module data=spatial_omics
+grass-mil-train task=finetune_mean model=supervised_module data=spatial_omics
 ```
 
 ### 4) Evaluate A Checkpoint
 
 ```bash
-python src/eval.py \
+grass-mil-eval \
   ckpt_path=/absolute/path/to/checkpoint.ckpt \
   task=finetune_mean \
   model=supervised_module \
@@ -86,23 +103,26 @@ python src/eval.py \
 ## Documentation Index
 
 - Full tracked-file map: [`docs/repository_map.md`](docs/repository_map.md)
+- Dataset onboarding and preparation checklist: [`docs/dataset_preparation.md`](docs/dataset_preparation.md)
 - End-to-end workflows (new data, SSL pretrain->finetune, model adjustments, inference): [`docs/workflows_train_infer.md`](docs/workflows_train_infer.md)
 - Inference utility suite (prediction artifacts, metrics, embeddings): [`docs/inference_utility_suite.md`](docs/inference_utility_suite.md)
 - Interpretability suite architecture and usage: [`docs/interpretability_suite.md`](docs/interpretability_suite.md)
 - Interpretability extension guide (plugins/new analyses): [`docs/interpretability_extension_guide.md`](docs/interpretability_extension_guide.md)
 - Exhaustive hyperparameter reference for repo configs: [`docs/hyperparameter_reference.md`](docs/hyperparameter_reference.md)
 - Capability modes and operational options: [`docs/capabilities_and_modes.md`](docs/capabilities_and_modes.md)
 - Existing model contracts: [`docs/model_component_contracts.md`](docs/model_component_contracts.md)
-- Existing legacy gap audit: [`docs/legacy_gap_audit.md`](docs/legacy_gap_audit.md)
+- Method fidelity map (method -> code -> test): [`docs/method_fidelity.md`](docs/method_fidelity.md)
+- Fidelity status and bugs found while closing gaps: [`docs/legacy_gap_audit.md`](docs/legacy_gap_audit.md)
 
 ## Supported Training/Inference Modes
 
 | Mode | Task Config | Model Config | Entrypoint | Primary Output |
 |---|---|---|---|---|
-| Supervised mean aggregation | `task=finetune_mean` | `model=supervised_module` | `src/train.py` | Region/sample-level logits via mean bag aggregation |
-| Supervised MIL attention | `task=finetune_mil` | `model=supervised_module` | `src/train.py` | Attention-weighted bag logits (+ optional MIL auxiliary terms) |
-| SSL pretraining (BGRL) | `task=pretrain_bgrl` | `model=bgrl_module` | `src/train.py` | BGRL-pretrained encoder checkpoint |
-| Checkpoint evaluation | any compatible task/model | matching training stack | `src/eval.py` | Test metrics from selected checkpoint |
+| Supervised mean aggregation | `task=finetune_mean` | `model=supervised_module` | `src/grass_mil/train.py` | Region/sample-level logits via mean bag aggregation |
+| Supervised MIL attention | `task=finetune_mil` | `model=supervised_module` | `src/grass_mil/train.py` | Per-class attention-weighted bag logits |
+| Cox survival with MIL | `task=finetune_survival` | `model=supervised_module` | `src/grass_mil/train.py` | Scalar log-hazard per bag, scored by c-index |
+| SSL pretraining (BGRL) | `task=pretrain_bgrl` | `model=bgrl_module` | `src/grass_mil/train.py` | BGRL-pretrained encoder checkpoint |
+| Checkpoint evaluation | any compatible task/model | matching training stack | `src/grass_mil/eval.py` | Test metrics from selected checkpoint |
 | Advanced prediction (Python API) | compatible with `SupervisedModule.predict_step` | `model=supervised_module` | `Trainer.predict(...)` | `bag_ids`, `bag_logits`, `row_region_ids`, `row_sample_ids`, optional `bag_targets`, optional `bag_attention`, optional `instance_*`, optional `embedding_*` |
 
 ## Required Inputs (Manifest Summary)
@@ -129,20 +149,20 @@ See full input contracts and file examples in [`docs/workflows_train_infer.md`](
 ### Switch aggregation regime
 
 ```bash
-python src/train.py task=finetune_mean model=supervised_module
-python src/train.py task=finetune_mil model=supervised_module
+grass-mil-train task=finetune_mean model=supervised_module
+grass-mil-train task=finetune_mil model=supervised_module
 ```
 
 ### Run SSL pretraining
 
 ```bash
-python src/train.py task=pretrain_bgrl model=bgrl_module
+grass-mil-train task=pretrain_bgrl model=bgrl_module
 ```
 
 ### Change backbone
 
 ```bash
-python src/train.py task=finetune_mil model=supervised_module \
+grass-mil-train task=finetune_mil model=supervised_module \
   model.encoder.conv_type=gine \
   model.encoder.use_edge_attr=true \
   model.encoder.edge_attr_dim=2
@@ -151,13 +171,13 @@ python src/train.py task=finetune_mil model=supervised_module \
 ### Force data re-precompute
 
 ```bash
-python src/train.py data.force_precompute=true
+grass-mil-train data.force_precompute=true
 ```
 
 ### Resume training
 
 ```bash
-python src/train.py ckpt_path=/absolute/path/to/last.ckpt
+grass-mil-train ckpt_path=/absolute/path/to/last.ckpt
 ```
 
 ## Where Outputs Go
@@ -176,9 +196,20 @@ Data precompute outputs:
 
 ## Known Gaps / Non-Goals
 
-Current repository behavior intentionally excludes:
+`grass-mil` implements the method, and only the method. It is deliberately not
+a reproduction harness for any particular study, so the following live outside
+this repository:
+
+1. Cohort-specific experiment configs and dataset preprocessing.
+2. Non-GNN baselines (cell-type composition models, frozen-encoder probes) and
+   the benchmark tables that compare against them.
+3. Cross-validation campaign harnesses, hyperparameter sweep recipes, and
+   experiment-tracking orchestration.
+
+The one deliberate exception is the interpretability suite, which is
+first-class here because the method's attribution claim is part of the method.
 
-1. Curated first-class hyperparameter sweep recipes in `configs/hparams_search/`.
-2. Turnkey dataset-specific benchmark packs beyond the generic Hydra/config contracts.
+For what is implemented and the tests that hold it in place, see
+[`docs/method_fidelity.md`](docs/method_fidelity.md).
 
 All currently supported capabilities are documented in [`docs/workflows_train_infer.md`](docs/workflows_train_infer.md), [`docs/hyperparameter_reference.md`](docs/hyperparameter_reference.md), and [`docs/capabilities_and_modes.md`](docs/capabilities_and_modes.md).