mehta-lab
diff --git a/‎.github/workflows/test.yml‎
Lines changed: 5 additions & 4 deletions b/‎.github/workflows/test.yml‎
Lines changed: 5 additions & 4 deletions
diff --git a/‎.planning/MILESTONES.md‎
Lines changed: 20 additions & 0 deletions b/‎.planning/MILESTONES.md‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎.planning/PROJECT.md‎
Lines changed: 97 additions & 0 deletions b/‎.planning/PROJECT.md‎
Lines changed: 97 additions & 0 deletions
diff --git a/‎.planning/REQUIREMENTS.md‎
Lines changed: 183 additions & 0 deletions b/‎.planning/REQUIREMENTS.md‎
Lines changed: 183 additions & 0 deletions
@@ -12,13 +12,14 @@ concurrency:
 
 jobs:
   test:
-    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    name: Test (${{ matrix.package }}, Python ${{ matrix.python-version }}, ${{ matrix.os }})
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: true
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.11", "3.12", "3.13"]
+        package: [viscy-transforms, viscy-models]
 
     steps:
       - name: Checkout repository
@@ -33,11 +34,11 @@ jobs:
 
       - name: Install dependencies
         run: uv sync --frozen --all-extras --dev
-        working-directory: packages/viscy-transforms
+        working-directory: packages/${{ matrix.package }}
 
       - name: Run tests with coverage
-        run: uv run --frozen pytest --cov=viscy_transforms --cov-report=term-missing
-        working-directory: packages/viscy-transforms
+        run: uv run --frozen pytest --cov=src/ --cov-report=term-missing
+        working-directory: packages/${{ matrix.package }}
 
   check:
     name: All tests pass
 
@@ -0,0 +1,20 @@
+# Milestones: VisCy Modularization
+
+## v1.0 — Transforms & Monorepo Skeleton
+
+**Shipped:** 2026-01-29
+**Phases:** 1–5 (4 executed, 1 deferred)
+
+**What shipped:**
+- uv workspace scaffolding with `packages/` directory
+- `viscy-transforms` package extracted with src layout
+- Clean import paths: `from viscy_transforms import X`
+- hatchling + uv-dynamic-versioning build system
+- All 16 transform modules migrated with full test suite
+- CI/CD: 9-job test matrix (3 OS x 3 Python) + lint workflow
+- prek hooks with ruff formatting
+
+**Deferred:**
+- Phase 4: Documentation (Zensical + GitHub Pages)
+
+**Last phase:** 5
@@ -0,0 +1,97 @@
+# VisCy Modularization
+
+## What This Is
+
+Restructuring VisCy from a monolithic package into a uv workspace monorepo. This enables reusing transforms, dataloaders, and models in downstream projects without requiring the entire VisCy package as a dependency. The second milestone extracts `viscy-models` as an independent package containing all 8 network architectures as pure nn.Modules, organized by function (unet/, vae/, contrastive/) with shared components factored into a `components/` module.
+
+## Core Value
+
+**Independent, reusable subpackages with clean import paths.** Users can `pip install viscy-models` and use `from viscy_models import UNeXt2` without pulling in the entire VisCy ecosystem.
+
+## Current Milestone: v1.1 Models
+
+**Goal:** Extract all network architectures into `viscy-models` as pure nn.Modules with comprehensive test coverage.
+
+**Target features:**
+- `viscy-models` package with 8 architectures organized by function (unet/, vae/, contrastive/)
+- Shared components extracted to `components/` (stems, heads, decoder blocks)
+- Full test coverage: migrate existing + write new for UNeXt2, ContrastiveEncoder, BetaVAE
+- Independent of viscy-transforms and lightning (torch/timm/monai deps only)
+- State dict key compatibility preserved for checkpoint loading
+
+## Requirements
+
+### Validated
+
+- ✓ uv workspace scaffolding with `packages/` directory structure — v1.0
+- ✓ `viscy-transforms` package extracted with src layout — v1.0
+- ✓ Import path: `from viscy_transforms import X` (clean break) — v1.0
+- ✓ hatchling build backend with uv-dynamic-versioning — v1.0
+- ✓ All existing transform tests passing in new structure — v1.0
+- ✓ CI updated for monorepo structure — v1.0
+
+### Active
+
+- [ ] `viscy-models` package with src layout and function-based organization
+- [ ] All 8 architectures migrated: UNeXt2, FCMAE, ContrastiveEncoder, ResNet3dEncoder, BetaVae25D, BetaVaeMonai, Unet2d, Unet25d
+- [ ] Shared components extracted to `components/` (stems, heads, blocks)
+- [ ] Full test coverage: existing tests migrated + new tests for untested models
+- [ ] Import path: `from viscy_models import UNeXt2` (clean break)
+- [ ] State dict key compatibility preserved
+- [ ] CI includes viscy-models in test matrix
+
+### Out of Scope
+
+- Hydra/BaseModel registry infrastructure — deferred to future `viscy-hydra` package
+- BaseModelMeta metaclass — deferred to future `viscy-hydra` package
+- Extracting data packages (viscy-data) — future milestone
+- Application-level LightningModules — move to applications/ in future milestone
+- Backward-compatible imports — not maintaining
+- Documentation (Zensical + GitHub Pages) — deferred from v1.0
+
+## Context
+
+**Design doc:** https://github.com/mehta-lab/VisCy/issues/353
+
+**Reference implementations:**
+- flowbench BaseModel: `/home/eduardo.hirata/repos/flowbench/src/models/base_model.py` (future reference for viscy-hydra)
+- lightning-hydra-template: https://github.com/ashleve/lightning-hydra-template (future reference)
+- iohub pyproject.toml: modern hatchling + uv-dynamic-versioning pattern
+
+**Current state (post v1.0):**
+- uv workspace with `viscy-transforms` at `packages/viscy-transforms/`
+- Root `viscy` umbrella package with dynamic versioning
+- Models in monolithic `viscy/unet/networks/` and `viscy/representation/`
+- 14+ shared components in unext2.py used by fcmae, contrastive, vae
+- No tests for UNeXt2, ContrastiveEncoder, or BetaVAE
+
+**Architecture vision:**
+- `viscy-models`: Pure nn.Module architectures (this milestone)
+- `viscy-hydra`: BaseModel, BaseModelMeta, Hydra config utilities (future milestone)
+- Applications (Cytoland, DynaCLR): LightningModules composing models with training logic (future milestone)
+
+## Constraints
+
+- **Package naming**: `viscy-models` (hyphen) as package name, `viscy_models` (underscore) as import
+- **Python version**: >=3.11 (matching current VisCy)
+- **Build system**: hatchling with uv-dynamic-versioning (following viscy-transforms pattern)
+- **Layout**: src layout required (`packages/viscy-models/src/viscy_models/`)
+- **Independence**: viscy-models must NOT depend on viscy-transforms or lightning
+- **Dependencies**: torch, timm, monai, numpy only
+- **Tooling**: uv only, no pip/setuptools for package management
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Clean break on imports | Simpler architecture, no re-export complexity | ✓ Good |
+| hatchling over setuptools | Modern, faster, better uv integration | ✓ Good |
+| src layout | Prevents import confusion during development | ✓ Good |
+| Tests inside packages | Isolated testing, `uv run --package` workflow | ✓ Good |
+| Pure nn.Module in viscy-models | No Lightning/Hydra coupling; maximum reusability | — Pending |
+| Hydra infra in separate package | Keeps model package lightweight; Hydra optional for consumers | — Pending |
+| Function-based grouping (unet/, vae/, contrastive/) | Clean organization for 8+ models with shared components | — Pending |
+| viscy-models independent of viscy-transforms | Keep packages loosely coupled | — Pending |
+
+---
+*Last updated: 2026-02-12 after requirements definition*
@@ -0,0 +1,183 @@
+# Requirements: VisCy Modularization
+
+**Defined:** 2025-01-27
+**Core Value:** Independent, reusable subpackages with clean import paths
+
+## v1.0 Requirements (Complete)
+
+### Workspace Foundation
+
+- [x] **WORK-00**: Clean slate setup - wipe repo keeping only LICENSE, CITATION.cff, .gitignore
+- [x] **WORK-01**: Virtual workspace root with `[tool.uv.workspace]` and `members = ["packages/*"]`
+- [x] **WORK-02**: Shared lockfile (`uv.lock`) at repository root
+- [x] **WORK-03**: Python version floor (>=3.11) enforced in root pyproject.toml
+- [x] **WORK-04**: Pre-commit hooks configured (ruff, ty) for local development
+- [x] **WORK-05**: Shared pytest configuration in root pyproject.toml
+
+### Package Structure
+
+- [x] **PKG-01**: src layout for viscy-transforms (`packages/viscy-transforms/src/viscy_transforms/`)
+- [x] **PKG-02**: Package pyproject.toml with hatchling build backend
+- [x] **PKG-03**: uv-dynamic-versioning configured for git-based versioning
+- [x] **PKG-04**: Package README.md with installation and usage instructions
+
+### Code Migration
+
+- [x] **MIG-01**: All transform modules migrated from `viscy/transforms/` to package
+- [x] **MIG-02**: All transform tests migrated from `tests/transforms/` to `packages/viscy-transforms/tests/`
+- [x] **MIG-03**: Import path updated to `from viscy_transforms import X`
+- [x] **MIG-04**: All migrated tests passing with `uv run --package viscy-transforms pytest`
+- [x] **MIG-05**: Original `viscy/transforms/` directory removed
+
+### CI/CD
+
+- [x] **CI-01**: GitHub Actions workflow for testing viscy-transforms package
+- [x] **CI-03**: Matrix testing across Python 3.11, 3.12, 3.13
+- [x] **CI-04**: Linting via prek (uvx prek) in CI workflows
+
+## v1.1 Requirements
+
+Requirements for milestone v1.1 (Models). Each maps to roadmap phases.
+
+### Models -- Package Infrastructure
+
+- [x] **MPKG-01**: Package directory `packages/viscy-models/` with src layout (`src/viscy_models/`)
+- [x] **MPKG-02**: pyproject.toml with hatchling, uv-dynamic-versioning, torch/timm/monai/numpy dependencies
+- [x] **MPKG-03**: `uv sync --package viscy-models` succeeds in workspace
+- [x] **MPKG-04**: `components/` module with stems.py, heads.py, blocks.py extracted from shared code
+
+### Models -- UNet Architectures
+
+- [x] **UNET-01**: UNeXt2 migrated to `unet/unext2.py` with shared component imports updated
+- [x] **UNET-02**: FullyConvolutionalMAE migrated to `unet/fcmae.py`
+- [x] **UNET-03**: Unet2d migrated to `unet/unet2d.py` (renamed from PascalCase)
+- [x] **UNET-04**: Unet25d migrated to `unet/unet25d.py` (renamed from PascalCase)
+- [x] **UNET-05**: ConvBlock2D/3D migrated to `unet/_layers/` (renamed from PascalCase)
+- [x] **UNET-06**: Forward-pass tests for UNeXt2 (NEW -- currently missing)
+- [x] **UNET-07**: FCMAE tests migrated from existing test suite
+- [x] **UNET-08**: Unet2d/Unet25d tests migrated and converted from unittest to pytest
+
+### Models -- Variational Autoencoders
+
+- [x] **VAE-01**: BetaVae25D migrated to `vae/beta_vae_25d.py`
+- [x] **VAE-02**: BetaVaeMonai migrated to `vae/beta_vae_monai.py`
+- [x] **VAE-03**: Forward-pass tests for both VAE models (NEW -- currently missing)
+
+### Models -- Contrastive Learning
+
+- [x] **CONT-01**: ContrastiveEncoder migrated to `contrastive/encoder.py`
+- [x] **CONT-02**: ResNet3dEncoder migrated to `contrastive/resnet3d.py`
+- [x] **CONT-03**: Forward-pass tests for contrastive models (NEW -- currently missing)
+
+### Models -- Public API & CI
+
+- [x] **API-01**: `from viscy_models import UNeXt2` works for all 8 model classes
+- [x] **API-02**: `uv run --package viscy-models pytest` passes all tests
+- [x] **API-03**: CI test matrix updated to include viscy-models
+- [x] **API-04**: Root pyproject.toml updated with viscy-models workspace dependency
+
+### Models -- Compatibility
+
+- [x] **COMPAT-01**: State dict keys preserved identically for all migrated models
+- [x] **COMPAT-02**: Mutable default arguments fixed to tuples in model constructors
+
+## Future Requirements
+
+Deferred to future milestones. Tracked but not in current roadmap.
+
+### Hydra Integration (future viscy-hydra package)
+
+- **HYDRA-01**: BaseModelMeta metaclass or `__init_subclass__` registry for model discovery
+- **HYDRA-02**: BaseModel(LightningModule) base class with auto Hydra instantiation
+- **HYDRA-03**: Hydra ConfigStore integration (optional dependency)
+- **HYDRA-04**: `get_model("unext2")` factory function for name-based lookup
+
+### Applications (future milestone)
+
+- **APP-01**: applications/DynaCLR with ContrastiveModule LightningModule
+- **APP-02**: applications/Cytoland with VSUNet/FcmaeUNet LightningModules
+
+### Documentation (deferred from v1.0)
+
+- **DOC-01**: Zensical configuration (`zensical.toml`) at repository root
+- **DOC-02**: Documentation site structure with navigation
+- **DOC-03**: API reference auto-generated from docstrings
+- **DOC-04**: GitHub Pages deployment
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Hydra/BaseModel registry in viscy-models | Deferred to separate viscy-hydra package |
+| LightningModule wrappers | Training logic stays in applications/ |
+| Backward-compatible imports | Clean break approach |
+| viscy-data extraction | Separate milestone |
+| Documentation (Zensical) | Deferred from v1.0 |
+| ONNX/TorchScript export | VAE models return SimpleNamespace, incompatible |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+### v1.0 Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| WORK-00 | Phase 1 | Complete |
+| WORK-01 | Phase 1 | Complete |
+| WORK-02 | Phase 1 | Complete |
+| WORK-03 | Phase 1 | Complete |
+| WORK-04 | Phase 1 | Complete |
+| WORK-05 | Phase 1 | Complete |
+| PKG-01 | Phase 2 | Complete |
+| PKG-02 | Phase 2 | Complete |
+| PKG-03 | Phase 2 | Complete |
+| PKG-04 | Phase 2 | Complete |
+| MIG-01 | Phase 3 | Complete |
+| MIG-02 | Phase 3 | Complete |
+| MIG-03 | Phase 3 | Complete |
+| MIG-04 | Phase 3 | Complete |
+| MIG-05 | Phase 3 | Complete |
+| CI-01 | Phase 5 | Complete |
+| CI-03 | Phase 5 | Complete |
+| CI-04 | Phase 5 | Complete |
+
+### v1.1 Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| MPKG-01 | Phase 6 | Complete |
+| MPKG-02 | Phase 6 | Complete |
+| MPKG-03 | Phase 6 | Complete |
+| MPKG-04 | Phase 6 | Complete |
+| UNET-05 | Phase 6 | Complete |
+| COMPAT-02 | Phases 7-9 | Complete |
+| UNET-01 | Phase 7 | Complete |
+| UNET-02 | Phase 7 | Complete |
+| UNET-06 | Phase 7 | Complete |
+| UNET-07 | Phase 7 | Complete |
+| CONT-01 | Phase 8 | Complete |
+| CONT-02 | Phase 8 | Complete |
+| CONT-03 | Phase 8 | Complete |
+| VAE-01 | Phase 8 | Complete |
+| VAE-02 | Phase 8 | Complete |
+| VAE-03 | Phase 8 | Complete |
+| UNET-03 | Phase 9 | Complete |
+| UNET-04 | Phase 9 | Complete |
+| UNET-08 | Phase 9 | Complete |
+| API-01 | Phase 10 | Complete |
+| API-02 | Phase 10 | Complete |
+| API-03 | Phase 10 | Complete |
+| API-04 | Phase 10 | Complete |
+| COMPAT-01 | Phase 10 | Complete |
+
+**Coverage:**
+- v1.0 requirements: 18 total, 18 mapped (complete)
+- v1.1 requirements: 24 total, 24 mapped
+- Unmapped: 0
+
+---
+*Requirements defined: 2025-01-27*
+*Last updated: 2026-02-12 after v1.1 roadmap creation*