sleap-nn 0.0.5__tar.gz → 0.1.0a0__tar.gz

sleap_nn-0.1.0a0/.claude/skills/investigation/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: investigation
+description: >
+  Scaffolds a structured investigation in scratch/ for empirical research and documentation.
+  Use when the user says "start an investigation" or wants to: trace code paths or data flow
+  ("trace from X to Y", "what touches X", "follow the wiring"), document system architecture
+  comprehensively ("document how the system works", "archeology"), investigate bugs
+  ("figure out why X happens"), explore technical feasibility ("can we do X?"), or explore
+  design options ("explore the API", "gather context", "design alternatives").
+  Creates dated folder with README. NOT for simple code questions or single-file searches.
+---
+
+# Set up an investigation
+
+## Instructions
+
+1. Create a folder in `{REPO_ROOT}/scratch/` with the format `{YYYY-MM-DD}-{descriptive-name}`.
+2. Create a `README.md` in this folder with: task description, background context, task checklist. Update with findings as you progress.
+3. Create scripts and data files as needed for empirical work.
+4. For complex investigations, split into sub-documents as patterns emerge.
+
+## Investigation Patterns
+
+These are common patterns, not rigid categories. Most investigations blend multiple patterns.
+
+**Tracing** - "trace from X to Y", "what touches X", "follow the wiring"
+- Follow call stack or data flow from a focal component to its connections
+- Can trace forward (X → where does it go?) or backward (what leads to X?)
+- Useful for: assessing impact of changes, understanding coupling
+
+**System Architecture Archeology** - "document how the system works", "archeology"
+- Comprehensive documentation of an entire system or flow for reusable reference
+- Start from entry points, trace through all layers, document relationships exhaustively
+- For complex systems, consider numbered sub-documents (01-cli.md, 02-data.md, etc.)
+
+**Bug Investigation** - "figure out why X happens", "this is broken"
+- Reproduce → trace root cause → propose fix
+- For cross-repo bugs, consider per-repo task breakdowns
+
+**Technical Exploration** - "can we do X?", "is this possible?", "figure out how to"
+- Feasibility testing with proof-of-concept scripts
+- Document what works AND what doesn't
+
+**Design Research** - "explore the API", "gather context", "design alternatives"
+- Understand systems and constraints before building
+- Compare alternatives, document trade-offs
+- Include visual artifacts (mockups, screenshots) when relevant
+- For iterative decisions, use numbered "Design Questions" (DQ1, DQ2...) to structure review
+
+## Best Practices
+
+- Use `uv` with inline dependencies for standalone scripts; for scripts importing local project code, use `python` directly (or `uv run python` if env not activated)
+- Use subagents for parallel exploration to save context
+- Write small scripts to explore APIs interactively
+- Generate figures/diagrams and reference inline in markdown
+- For web servers: `npx serve -p 8080 --cors --no-clipboard &`
+- For screenshots: use Playwright MCP for web, Qt's grab() for GUI
+- For external package API review: clone to `scratch/repos/` for direct source access
+
+## Important: Scratch is Gitignored
+
+The `scratch/` directory is in `.gitignore` and will NOT be committed.
+
+- NEVER delete anything from scratch - it doesn't need cleanup
+- When distilling findings into PRs, include all relevant info inline
+- Copy key findings, code, and data directly into PR descriptions
+- PRs must be self-contained; don't reference scratch files

{sleap_nn-0.0.5 → sleap_nn-0.1.0a0}/.github/workflows/ci.yml

@@ -13,6 +13,9 @@ jobs:
   lint:
     name: Lint
     runs-on: ubuntu-latest
+    env:
+      CUDA_VISIBLE_DEVICES: ""
+      USE_CUDA: "0"
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4
@@ -26,20 +29,24 @@ jobs:
         run: uv python install 3.13
 
       - name: Install dev dependencies and torch
-        run: uv sync --extra dev --extra torch-cpu
+        run: uv sync --extra torch-cpu
 
       - name: Run Black
-        run: uv run black --check sleap_nn tests
+        run: uv run --frozen --extra torch-cpu black --check sleap_nn tests
 
       - name: Run Ruff
-        run: uv run ruff check sleap_nn/
+        run: uv run --frozen --extra torch-cpu ruff check sleap_nn/
 
   tests:
     timeout-minutes: 30
+    env:
+      CUDA_VISIBLE_DEVICES: ""
+      USE_CUDA: "0"
+      UV_FROZEN: "1"
     strategy:
       fail-fast: false
       matrix:
-        os: ["ubuntu", "windows", "mac", "self-hosted-gpu"]
+        os: ["ubuntu", "windows", "mac"]  # "self-hosted-gpu" temporarily disabled
         include:
           - os: ubuntu
             runs-on: ubuntu-latest
@@ -47,8 +54,8 @@ jobs:
             runs-on: windows-latest
           - os: mac
             runs-on: macos-14
-          - os: self-hosted-gpu
-            runs-on: [self-hosted, puma, gpu, 2xgpu]
+          # - os: self-hosted-gpu
+          #   runs-on: [self-hosted, puma, gpu, 2xgpu]
         python: [3.13]
 
     name: Tests (${{ matrix.os }}, Python ${{ matrix.python }})
@@ -69,21 +76,21 @@ jobs:
 
       - name: Install dev dependencies and torch (self-hosted GPU)
         if: matrix.os == 'self-hosted-gpu'
-        run: uv sync --python 3.13 --extra dev --extra torch-cuda128
+        run: uv sync --python 3.13 --extra torch-cuda128
 
       - name: Install dev dependencies and torch (non-self-hosted GPU)
         if: matrix.os != 'self-hosted-gpu'
-        run: uv sync --extra dev --extra torch-cpu
+        run: uv sync --extra torch-cpu
 
       - name: Print environment info
         run: |
           echo "=== UV Environment ==="
-          uv run python --version
-          uv run python -c "import sys; print('Python executable:', sys.executable)"
+          uv run --frozen --extra torch-cpu python --version
+          uv run --frozen --extra torch-cpu python -c "import sys; print('Python executable:', sys.executable)"
           echo "=== UV Environment NumPy Check ==="
-          uv run python -c "import numpy; print('NumPy version:', numpy.__version__); print('NumPy location:', numpy.__file__)" || echo "NumPy import failed in uv environment"
+          uv run --frozen --extra torch-cpu python -c "import numpy; print('NumPy version:', numpy.__version__); print('NumPy location:', numpy.__file__)" || echo "NumPy import failed in uv environment"
           echo "=== CUDA Availability Check ==="
-          uv run python -c "
+          uv run --frozen --extra torch-cpu python -c "
           import torch
           print(f'PyTorch version: {torch.__version__}')
           print(f'CUDA available: {torch.cuda.is_available()}')
@@ -95,24 +102,14 @@ jobs:
           else:
               print('CUDA is not available')
           " || echo "CUDA check failed"
-          echo "=== PIP EXECUTABLE COMPARISON ==="
-          uv run python -c "import subprocess; print('pip from uv run python:', subprocess.check_output(['pip', '--version']).decode().strip())" || echo "pip not found from python"
-          uv run pip --version || echo "uv run pip failed"
-          echo "=== UV pip list vs python -m pip list ==="
-          echo "--- uv run pip list ---"
-          uv run pip list | head -20
-          echo "--- uv run python -m pip list ---"
-          uv run python -m pip list | head -20
-          echo "=== UV ENVIRONMENT CHECK ==="
-          uv run python -c "import os; print('VIRTUAL_ENV:', os.environ.get('VIRTUAL_ENV', 'Not set'))"
           echo "=== Import Test ==="
-          uv run python -c "import torch; import lightning; import kornia; print('All imports successful')" || echo "Import test failed"
+          uv run --frozen --extra torch-cpu python -c "import torch; import lightning; import kornia; print('All imports successful')" || echo "Import test failed"
 
       - name: Check MPS backend (macOS only)
         if: runner.os == 'macOS'
         run: |
           echo "=== macOS MPS Backend Check ==="
-          uv run python -c "
+          uv run --frozen --extra torch-cpu python -c "
           import torch
           print(f'PyTorch version: {torch.__version__}')
           print(f'MPS available: {torch.backends.mps.is_available()}')
@@ -129,9 +126,9 @@ jobs:
       - name: Run pytest
         run: |
           echo "=== Final environment check before tests ==="
-          uv run python -c "import numpy, torch, lightning, kornia; print(f'All packages available: numpy={numpy.__version__}, torch={torch.__version__}')"
+          uv run --frozen --extra torch-cpu python -c "import numpy, torch, lightning, kornia; print(f'All packages available: numpy={numpy.__version__}, torch={torch.__version__}')"
           echo "=== Running pytest ==="
-          uv run pytest --cov=sleap_nn --cov-report=xml --durations=-1 tests/
+          uv run --frozen --extra torch-cpu pytest --cov=sleap_nn --cov-report=xml --durations=-1 tests/
 
       - name: Upload coverage
         uses: codecov/codecov-action@v5

{sleap_nn-0.0.5 → sleap_nn-0.1.0a0}/.github/workflows/docs.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --extra dev --extra torch-cpu --extra docs
+          uv sync --extra torch-cpu --group docs
 
       - name: Print environment info
         run: |
@@ -45,13 +45,20 @@ jobs:
             git config --global user.name "github-actions[bot]"
             git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
-      - name: Build and upload docs (release)
-        if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
+      - name: Build and upload docs (stable release)
+        if: ${{ github.event_name == 'release' && github.event.action == 'published' && !github.event.release.prerelease }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
             uv run mike deploy --update-aliases --allow-empty --push "${{ github.event.release.tag_name }}" latest
 
+      - name: Build and upload docs (pre-release)
+        if: ${{ github.event_name == 'release' && github.event.action == 'published' && github.event.release.prerelease }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+            uv run mike deploy --allow-empty --push "${{ github.event.release.tag_name }}"
+
       - name: Build and upload docs (dev)
         if: ${{ github.event_name == 'push' }}
         env:

{sleap_nn-0.0.5 → sleap_nn-0.1.0a0}/.gitignore

@@ -128,9 +128,6 @@ ENV/
 env.bak/
 venv.bak/
 
-# uv lock files
-uv.lock
-
 # Spyder project settings
 .spyderproject
 .spyproject
@@ -176,4 +173,10 @@ wandb/
 .DS_Store
 
 # Development scratch folder
-scratch/
+scratch/
+
+# Trained models
+models/
+
+# Test config files
+test_*.yaml

{sleap_nn-0.0.5 → sleap_nn-0.1.0a0}/CLAUDE.md

@@ -2,6 +2,13 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+sleap-nn is a PyTorch-based neural network backend for animal pose estimation.
+
+## Notes
+- We use `uv` for environment management and packaging.
+- We use `sleap-io` (https://github.com/talmolab/sleap-io) as the I/O backend for `.slp` files, which are HDF5-based containers for labels and sometimes embedded image data (typically ending with `.pkg.slp`). Refer to https://raw.githubusercontent.com/talmolab/sleap-io/refs/heads/main/docs/examples.md for usage examples when you need to do I/O with SLP files.
+- This package (`sleap-nn`) is used as the neural network training backend to SLEAP, which is primarily used through its frontend package `sleap` (https://github.com/talmolab/sleap).
+
 ## Common Development Commands
 
 ### Testing
@@ -15,15 +22,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - Check formatting: `black --check sleap_nn tests`
 - Run linter: `ruff check sleap_nn/`
 
-### Environment Setup
-- GPU (Windows/Linux): `mamba env create -f environment.yml`
-- CPU (Windows/Linux/Intel Mac): `mamba env create -f environment_cpu.yml`
-- Apple Silicon (M1/M2 Mac): `mamba env create -f environment_osx-arm64.yml`
-- Activate environment: `mamba activate sleap-nn`
-
 ## Architecture Overview
 
-sleap-nn is a PyTorch-based neural network backend for animal pose estimation. The codebase follows a modular architecture:
+The codebase follows a modular architecture:
 
 ### Core Components
 
@@ -68,14 +69,3 @@ Configurations are managed via Hydra and can be specified in YAML files (see `do
 - Inference: `sleap_nn/predict.py` - Run inference on trained models
 - CLI: `sleap_nn/cli.py` - Command-line interface (currently minimal)
 - Evaluation: `sleap_nn/evaluation.py` - Model evaluation utilities
-
-### Model Types
-
-The system supports multiple model architectures for pose estimation:
-- Single Instance: One animal per frame
-- Centered Instance: Crop-based single instance
-- Centroid: Animal center detection
-- Top-Down: Centroid → Instance detection
-- Bottom-Up: Multi-instance with PAFs
-
-Each model type has corresponding head modules, data processing, and inference pipelines.

{sleap_nn-0.0.5 → sleap_nn-0.1.0a0}/CONTRIBUTING.md

@@ -24,27 +24,33 @@ Thank you for your interest in contributing to sleap-nn! This guide will help yo
 2. **Install sleap-nn dependencies based on your platform**\
 
    - Sync all dependencies based on your correct wheel using `uv sync`. `uv sync` creates a `.venv` (virtual environment) inside your current working directory. This environment is only active within that directory and can't be directly accessed from outside. To use all installed packages, you must run commands with `uv run` (e.g., `uv run sleap-nn train ...` or `uv run pytest ...`).
-     - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
+     - **Windows/Linux with NVIDIA GPU (CUDA 13.0):**
+
+      ```bash
+      uv sync --extra torch-cuda130
+      ```
+
+     - **Windows/Linux with NVIDIA GPU (CUDA 12.8):**
 
       ```bash
-      uv sync --extra dev --extra torch-cuda118
+      uv sync --extra torch-cuda128
       ```
 
-      - **Windows/Linux with NVIDIA GPU (CUDA 12.8):**
+     - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
 
       ```bash
-      uv sync --extra dev --extra torch-cuda128
+      uv sync --extra torch-cuda118
       ```
-     
-     - **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):** 
+
+     - **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):**
      Note: Even if torch-cpu is used on macOS, the MPS backend will be available.
-     ```bash
-      uv sync --extra dev --extra torch-cpu
+      ```bash
+      uv sync --extra torch-cpu
       ```
 > **Upgrading All Dependencies**
 > To ensure you have the latest versions of all dependencies, use the `--upgrade` flag with `uv sync`:
 > ```bash
-> uv sync --extra dev --upgrade
+> uv sync --upgrade
 > ```
 > This will upgrade all installed packages in your environment to the latest available versions compatible with your `pyproject.toml`.
 
@@ -124,7 +130,7 @@ cd sleap-nn
 
 2. Install `sleap-nn` with docs dependencies:
    ```bash
-   uv sync --extra docs --extra dev --extra torch-cpu
+   uv sync --group docs --extra torch-cpu
    ```
 
 3. Build and tag a new documentation version:

{sleap_nn-0.0.5 → sleap_nn-0.1.0a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sleap-nn
-Version: 0.0.5
+Version: 0.1.0a0
 Summary: Neural network backend for training and inference for animal pose estimation.
 Author-email: Divya Seshadri Murali <dimurali@salk.edu>, Elizabeth Berrigan <eberrigan@salk.edu>, Vincent Tu <vitu@ucsd.edu>, Liezl Maree <lmaree@salk.edu>, David Samy <davidasamy@gmail.com>, Talmo Pereira <talmo@salk.edu>
 License: BSD-3-Clause
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.14,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: sleap-io>=0.5.7
+Requires-Dist: sleap-io<0.7.0,>=0.6.0
 Requires-Dist: numpy
 Requires-Dist: lightning
 Requires-Dist: kornia
@@ -34,35 +34,19 @@ Requires-Dist: jupyterlab
 Requires-Dist: pyzmq
 Provides-Extra: torch
 Requires-Dist: torch; extra == "torch"
-Requires-Dist: torchvision<0.24.0,>=0.20.0; extra == "torch"
+Requires-Dist: torchvision>=0.20.0; extra == "torch"
 Provides-Extra: torch-cpu
 Requires-Dist: torch; extra == "torch-cpu"
-Requires-Dist: torchvision<0.24.0,>=0.20.0; extra == "torch-cpu"
+Requires-Dist: torchvision>=0.20.0; extra == "torch-cpu"
 Provides-Extra: torch-cuda118
 Requires-Dist: torch; extra == "torch-cuda118"
-Requires-Dist: torchvision<0.24.0,>=0.20.0; extra == "torch-cuda118"
+Requires-Dist: torchvision>=0.20.0; extra == "torch-cuda118"
 Provides-Extra: torch-cuda128
 Requires-Dist: torch; extra == "torch-cuda128"
-Requires-Dist: torchvision<0.24.0,>=0.20.0; extra == "torch-cuda128"
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: pydocstyle; extra == "dev"
-Requires-Dist: toml; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Requires-Dist: ipython; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: mkdocs; extra == "docs"
-Requires-Dist: mkdocs-material; extra == "docs"
-Requires-Dist: mkdocs-jupyter; extra == "docs"
-Requires-Dist: mike; extra == "docs"
-Requires-Dist: mkdocstrings[python]; extra == "docs"
-Requires-Dist: mkdocs-gen-files; extra == "docs"
-Requires-Dist: mkdocs-literate-nav; extra == "docs"
-Requires-Dist: mkdocs-section-index; extra == "docs"
+Requires-Dist: torchvision>=0.20.0; extra == "torch-cuda128"
+Provides-Extra: torch-cuda130
+Requires-Dist: torch; extra == "torch-cuda130"
+Requires-Dist: torchvision>=0.20.0; extra == "torch-cuda130"
 Dynamic: license-file
 
 # sleap-nn
@@ -120,22 +104,28 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 > Replace `...` with the rest of your install command as needed.
 
 - Sync all dependencies based on your correct wheel using `uv sync`. `uv sync` creates a `.venv` (virtual environment) inside your current working directory. This environment is only active within that directory and can't be directly accessed from outside. To use all installed packages, you must run commands with `uv run` (e.g., `uv run sleap-nn train ...` or `uv run pytest ...`).
-   - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
+   - **Windows/Linux with NVIDIA GPU (CUDA 13.0):**
 
    ```bash
-   uv sync --extra dev --extra torch-cuda118
+   uv sync --extra torch-cuda130
    ```
 
    - **Windows/Linux with NVIDIA GPU (CUDA 12.8):**
 
    ```bash
-   uv sync --extra dev --extra torch-cuda128
+   uv sync --extra torch-cuda128
    ```
-   
-   - **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):** 
+
+   - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
+
+   ```bash
+   uv sync --extra torch-cuda118
+   ```
+
+   - **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):**
    Note: Even if torch-cpu is used on macOS, the MPS backend will be available.
    ```bash
-   uv sync --extra dev --extra torch-cpu
+   uv sync --extra torch-cpu
    ```
 
 4. **Run tests**  
@@ -152,6 +142,6 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 > **Upgrading All Dependencies**
 > To ensure you have the latest versions of all dependencies, use the `--upgrade` flag with `uv sync`:
 > ```bash
-> uv sync --extra dev --upgrade
+> uv sync --upgrade
 > ```
 > This will upgrade all installed packages in your environment to the latest available versions compatible with your `pyproject.toml`.

{sleap_nn-0.0.5 → sleap_nn-0.1.0a0}/README.md

@@ -53,22 +53,28 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 > Replace `...` with the rest of your install command as needed.
 
 - Sync all dependencies based on your correct wheel using `uv sync`. `uv sync` creates a `.venv` (virtual environment) inside your current working directory. This environment is only active within that directory and can't be directly accessed from outside. To use all installed packages, you must run commands with `uv run` (e.g., `uv run sleap-nn train ...` or `uv run pytest ...`).
-   - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
+   - **Windows/Linux with NVIDIA GPU (CUDA 13.0):**
 
    ```bash
-   uv sync --extra dev --extra torch-cuda118
+   uv sync --extra torch-cuda130
    ```
 
    - **Windows/Linux with NVIDIA GPU (CUDA 12.8):**
 
    ```bash
-   uv sync --extra dev --extra torch-cuda128
+   uv sync --extra torch-cuda128
    ```
-   
-   - **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):** 
+
+   - **Windows/Linux with NVIDIA GPU (CUDA 11.8):**
+
+   ```bash
+   uv sync --extra torch-cuda118
+   ```
+
+   - **macOS with Apple Silicon (M1, M2, M3, M4) or CPU-only (no GPU or unsupported GPU):**
    Note: Even if torch-cpu is used on macOS, the MPS backend will be available.
    ```bash
-   uv sync --extra dev --extra torch-cpu
+   uv sync --extra torch-cpu
    ```
 
 4. **Run tests**  
@@ -85,6 +91,6 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 > **Upgrading All Dependencies**
 > To ensure you have the latest versions of all dependencies, use the `--upgrade` flag with `uv sync`:
 > ```bash
-> uv sync --extra dev --upgrade
+> uv sync --upgrade
 > ```
 > This will upgrade all installed packages in your environment to the latest available versions compatible with your `pyproject.toml`.

{sleap_nn-0.0.5 → sleap_nn-0.1.0a0}/codecov.yml

@@ -10,9 +10,11 @@ coverage:
         threshold: 2%  # Less leeway with backend code.
         paths:
           - "sleap_nn/"
+        informational: true  # Don't fail PRs on coverage
     patch:  #  Only measures lines adjusted in the pull request.
       default: false
       package:
         target: 95%  # All backend code should be tested...
         paths:
-          - "sleap_nn/"
+          - "sleap_nn/"
+        informational: true  # Don't fail PRs on coverage