restructure codebase

.github/workflows/docs.yaml

@@ -38,9 +38,6 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e ".[testing,docs]"
 
-      - name: Run docs smoke test
-        run: python -m pytest -q -o addopts= -p no:cov tests/test_docs.py
-
       - name: Build Sphinx site
         run: python -m sphinx -W -b html docs docs/_build/html
 

docs/documentation.md

@@ -2,6 +2,17 @@
 
 ## 2026-04-18
 
+- Split `slide2vec.inference` into workflow-scoped internal runtime helpers under `slide2vec.runtime` (`batching`, `hierarchical`, `progress_bridge`, `serialization`, `types`) while keeping `slide2vec.inference` as the stable orchestration entrypoint.
+- Removed remaining pass-through wrappers from `slide2vec.inference` (tiling/embedding/distributed helpers) and switched workers/tests to import `slide2vec.runtime.*` directly, with simplified runtime helper signatures replacing callback/class injection patterns.
+- Removed the leftover distributed orchestration pass-through layer in `slide2vec.inference` (`_distributed_coordination_dir`, `_run_torchrun_worker`, `_reset_progress_event_logs`) so torchrun/progress coordination now calls `slide2vec.runtime.distributed` directly.
+- Dropped the temporary preview-key compatibility branch in `runtime.tiling.build_preview_config`; preview config now uses the canonical `tissue_contour_color` input only.
+- Added architecture guardrail tests that keep workflow helpers bounded (soft target around 400 lines, enforced ceiling 500) and prevent `slide2vec/inference.py` from regressing toward the previous monolith size.
+- Extracted distributed torchrun orchestration, shard merge/loading, and rank-assignment helpers into `slide2vec.runtime.distributed`, with inference-level compatibility shims preserved for existing tests and monkeypatch patterns.
+- Moved artifact collection/loading and process-list embedding status updates into `slide2vec.runtime.persistence` so the pipeline orchestration flow in `slide2vec.inference` stays focused on control flow.
+- Extracted pure tiling and embedding metadata/writer helpers into `slide2vec.runtime.tiling` and `slide2vec.runtime.embedding`, keeping inference-level wrappers so existing monkeypatch-based regression tests remain stable.
+- Moved root-level internal helpers (`runtime_types.py`, `model_settings.py`, `registry.py`, `resources.py`) into clearer homes: `slide2vec.runtime.*` and `slide2vec.configs.resources`, and added a guardrail test that keeps the root package module list intentionally minimal.
+- Trimmed secondary/low-signal tests (docs build, packaging metadata smoke, collator timing micro-tests, and heavyweight output-consistency smoke) to keep the test suite focused on high-signal core regression coverage.
+
 - Aligned slide2vec with hs2p 4.0.0's unified tiling/sampling contract by preserving the new `annotation` column in process lists and translating preview configs to hs2p's `save_mask_preview` / `save_tiling_preview` / `tissue_contour_color` fields.
 
 - Split the live tiling UI into a coordinates-extraction bar plus a separate preview-generation bar, and moved the final tiling summary into a dedicated `tiling.summary` event so it prints once at the very end.

slide2vec/api.py

@@ -20,9 +20,9 @@
     resolve_preprocessing_defaults,
 )
 from slide2vec.encoders.validation import validate_encoder_config
-from slide2vec.model_settings import canonicalize_model_name, normalize_precision_name
+from slide2vec.runtime.model_settings import canonicalize_model_name, normalize_precision_name
 from slide2vec.progress import emit_progress
-from slide2vec.runtime_types import LoadedModel
+from slide2vec.runtime.types import LoadedModel
 from slide2vec.utils.utils import cpu_worker_limit, slurm_cpu_limit
 
 PathLike = str | Path

slide2vec/configs/__init__.py

@@ -1,4 +1,4 @@
-from slide2vec.resources import load_config
+from slide2vec.configs.resources import load_config
 
 
 default_config = load_config("default")

slide2vec/resources.py → slide2vec/configs/resources.py

@@ -1,7 +1,7 @@
+from contextlib import contextmanager
 from importlib.resources import as_file, files
 from pathlib import Path
 from typing import Iterator
-from contextlib import contextmanager
 
 
 def config_resource(*parts: str):
@@ -24,3 +24,4 @@ def config_path(*parts: str) -> Iterator[Path]:
     resource = config_resource(*parts)
     with as_file(resource) as resolved:
         yield resolved
+

slide2vec/distributed/direct_embed_worker.py

@@ -26,11 +26,10 @@ def main(argv=None) -> int:
         _compute_tile_embeddings_for_slide,
         _is_hierarchical_preprocessing,
         _resolve_hierarchical_geometry,
-        deserialize_execution,
-        deserialize_preprocessing,
         load_successful_tiled_slides,
     )
     from slide2vec.progress import JsonlProgressReporter, activate_progress_reporter
+    from slide2vec.runtime.serialization import deserialize_execution, deserialize_preprocessing
 
     parser = get_args_parser(add_help=True)
     args = parser.parse_args(argv)

slide2vec/distributed/pipeline_worker.py

@@ -3,7 +3,7 @@
 import json
 from pathlib import Path
 
-from slide2vec.inference import _assign_slides_to_ranks
+from slide2vec.runtime.distributed import assign_slides_to_ranks
 
 
 def get_args_parser(add_help: bool = True) -> argparse.ArgumentParser:
@@ -21,11 +21,10 @@ def main(argv=None) -> int:
     from slide2vec.inference import (
         _compute_embedded_slides,
         _persist_embedded_slide,
-        deserialize_execution,
-        deserialize_preprocessing,
         load_successful_tiled_slides,
     )
     from slide2vec.progress import JsonlProgressReporter, activate_progress_reporter
+    from slide2vec.runtime.serialization import deserialize_execution, deserialize_preprocessing
 
     parser = get_args_parser(add_help=True)
     args = parser.parse_args(argv)
@@ -48,7 +47,7 @@ def main(argv=None) -> int:
         preprocessing = deserialize_preprocessing(request["preprocessing"])
         execution = deserialize_execution(request["execution"])
         slide_records, tiling_results = load_successful_tiled_slides(output_dir)
-        assignments = _assign_slides_to_ranks(slide_records, tiling_results, num_gpus=world_size)
+        assignments = assign_slides_to_ranks(slide_records, tiling_results, num_gpus=world_size)
         assigned_ids = assignments.get(global_rank, [])
         if not assigned_ids:
             return 0

slide2vec/encoders/registry.py

@@ -2,7 +2,7 @@
 
 from typing import Any
 
-from slide2vec.registry import Registry
+from slide2vec.runtime.registry import Registry
 
 encoder_registry = Registry("encoders")
 

slide2vec/encoders/validation.py

@@ -8,7 +8,7 @@
     resolve_encoder_output,
     resolve_preprocessing_requirements,
 )
-from slide2vec.model_settings import normalize_precision_name
+from slide2vec.runtime.model_settings import normalize_precision_name
 
 logger = logging.getLogger("slide2vec")