sleap-connect 0.0.8__tar.gz

sleap_connect-0.0.8/.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_connect-0.0.8/.claude/skills/qt-testing/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: qt-testing
+description: Capture and visually inspect Qt GUI widgets using screenshots. Use when asked to verify GUI rendering, test widget appearance, check layouts, or visually inspect any PySide6/Qt component. Enables Claude to "see" Qt interfaces by capturing offscreen screenshots and analyzing them with vision.
+---
+
+# Qt GUI Testing
+
+Capture screenshots of Qt widgets for visual inspection without displaying windows on screen.
+
+## Quick Start
+
+```python
+# Capture any widget
+from scripts.qt_capture import capture_widget
+path = capture_widget(my_widget, "description_here")
+# Then read the screenshot with the Read tool
+```
+
+## Core Script
+
+Run `scripts/qt_capture.py` or import `capture_widget` from it:
+
+```bash
+# Standalone test
+uv run --with PySide6 python .claude/skills/qt-testing/scripts/qt_capture.py
+```
+
+## Output Location
+
+All screenshots save to: `scratch/.qt-screenshots/`
+
+Naming: `{YYYY-MM-DD.HH-MM-SS}_{description}.png`
+
+## Workflow
+
+1. Create/obtain the widget to test
+2. Call `capture_widget(widget, "description")`
+3. Read the saved screenshot with the Read tool
+4. Analyze with vision to verify correctness
+
+## Interaction Pattern
+
+To interact with widgets (click buttons, etc.):
+
+```python
+# Find widget at coordinates (from vision analysis)
+target = widget.childAt(x, y)
+
+# Trigger it directly (not mouse events)
+if hasattr(target, 'click'):
+    target.click()
+    QApplication.processEvents()
+
+# Capture result
+capture_widget(widget, "after_click")
+```
+
+## Example: Test a Dialog
+
+```python
+import sys
+from PySide6.QtWidgets import QApplication
+from sleap.gui.learning.dialog import TrainingEditorDialog
+
+# Add skill scripts to path
+sys.path.insert(0, ".claude/skills/qt-testing")
+from scripts.qt_capture import capture_widget, init_qt
+
+app = init_qt()
+dialog = TrainingEditorDialog()
+path = capture_widget(dialog, "training_dialog")
+dialog.close()
+print(f"Inspect: {path}")
+```
+
+## Key Points
+
+- Uses `Qt.WA_DontShowOnScreen` - no window popup
+- Renders identically to on-screen display (verified)
+- Call `processEvents()` after interactions before capture
+- Use `childAt(x, y)` to map vision coordinates to widgets
+- Direct method calls (`.click()`) work; simulated mouse events don't

sleap_connect-0.0.8/.claude/skills/qt-testing/scripts/qt_capture.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python
+"""Qt widget screenshot capture utility.
+
+Captures screenshots of Qt widgets without displaying them on screen.
+"""
+
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from PySide6.QtWidgets import QApplication, QWidget
+from PySide6.QtCore import Qt
+
+# Output directory
+OUTPUT_DIR = Path("scratch/.qt-screenshots")
+
+
+def init_qt() -> QApplication:
+    """Initialize Qt application (required once per process)."""
+    app = QApplication.instance()
+    if app is None:
+        app = QApplication(sys.argv)
+    return app
+
+
+def timestamp() -> str:
+    """Generate timestamp for filename."""
+    return datetime.now().strftime("%Y-%m-%d.%H-%M-%S")
+
+
+def capture_widget(
+    widget: QWidget,
+    description: str,
+    output_dir: Optional[Path] = None,
+) -> Path:
+    """
+    Capture a screenshot of a widget without displaying it on screen.
+
+    Args:
+        widget: The QWidget to capture
+        description: Short description for filename (use underscores, no spaces)
+        output_dir: Override output directory (default: scratch/.qt-screenshots)
+
+    Returns:
+        Path to saved screenshot
+    """
+    out = output_dir or OUTPUT_DIR
+    out.mkdir(parents=True, exist_ok=True)
+
+    # Configure for invisible rendering
+    widget.setAttribute(Qt.WA_DontShowOnScreen, True)
+    widget.show()
+    QApplication.processEvents()
+
+    # Capture
+    pixmap = widget.grab()
+    if pixmap.isNull():
+        raise RuntimeError("Failed to capture widget - pixmap is null")
+
+    # Save with timestamp
+    desc_clean = description.replace(" ", "_").replace("/", "-")
+    filename = f"{timestamp()}_{desc_clean}.png"
+    filepath = out / filename
+
+    if not pixmap.save(str(filepath)):
+        raise RuntimeError(f"Failed to save screenshot to {filepath}")
+
+    # Don't close - caller may want to interact further
+    widget.hide()
+
+    return filepath
+
+
+def capture_and_click(
+    widget: QWidget,
+    x: int,
+    y: int,
+    description: str,
+) -> tuple[Path, Optional[QWidget]]:
+    """
+    Click at coordinates and capture the result.
+
+    Args:
+        widget: Parent widget
+        x, y: Coordinates to click (in widget coordinate space)
+        description: Description for filename
+
+    Returns:
+        Tuple of (screenshot path, clicked widget or None)
+    """
+    widget.setAttribute(Qt.WA_DontShowOnScreen, True)
+    widget.show()
+    QApplication.processEvents()
+
+    # Find and click widget at coordinates
+    target = widget.childAt(x, y)
+    if target is not None:
+        if hasattr(target, "click"):
+            target.click()
+        elif hasattr(target, "toggle"):
+            target.toggle()
+        QApplication.processEvents()
+
+    # Capture result
+    path = capture_widget(widget, description)
+    return path, target
+
+
+# Self-test when run directly
+if __name__ == "__main__":
+    from PySide6.QtWidgets import QPushButton, QVBoxLayout, QLabel
+
+    app = init_qt()
+
+    # Create test widget
+    widget = QWidget()
+    widget.setWindowTitle("Qt Capture Test")
+    widget.setFixedSize(300, 150)
+
+    layout = QVBoxLayout(widget)
+    layout.addWidget(QLabel("Qt Capture Test Widget"))
+    btn = QPushButton("Test Button")
+    layout.addWidget(btn)
+
+    # Capture it
+    path = capture_widget(widget, "self_test")
+    print(f"Captured: {path}")
+
+    widget.close()
+    print("Self-test complete!")

sleap_connect-0.0.8/.dockerignore

@@ -0,0 +1,15 @@
+.git/
+tests/
+docs/
+scratch/
+*.pyc
+__pycache__/
+*.egg-info/
+.venv/
+.ruff_cache/
+.pytest_cache/
+*.log
+.env
+*.md
+!README.md
+openspec/

sleap_connect-0.0.8/.github/workflows/build.yml

@@ -0,0 +1,56 @@
+name: Build and publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Publish to TestPyPI instead of PyPI"
+        required: false
+        default: "false"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Publish to TestPyPI
+        if: ${{ github.event.inputs.testpypi == 'true' }}
+        run: uv publish --index testpypi --trusted-publishing always
+
+      - name: Publish to PyPI
+        if: ${{ github.event.inputs.testpypi != 'true' }}
+        run: uv publish --trusted-publishing always

sleap_connect-0.0.8/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "sleap_connect/**"
+      - "tests/**"
+      - ".github/workflows/ci.yml"
+      - "pyproject.toml"
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install dev dependencies
+        run: uv sync --extra dev
+
+      - name: Black
+        run: uv run black --check sleap_connect/
+
+      - name: Ruff
+        run: uv run ruff check sleap_connect/
+
+  tests:
+    name: Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install graphics libraries (Ubuntu)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgl1 \
+            libegl-mesa0 \
+            libgles2 \
+            libxcb-xinerama0 \
+            libxcb-icccm4 \
+            libxcb-image0 \
+            libxcb-keysyms1 \
+            libxcb-randr0 \
+            libxcb-render-util0 \
+            libxcb-xkb1 \
+            libxkbcommon-x11-0 \
+            x11-utils
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests (Ubuntu)
+        if: runner.os == 'Linux'
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: uv run pytest tests/ -v --timeout=60
+
+      - name: Run tests (macOS)
+        if: runner.os == 'macOS'
+        run: uv run pytest tests/ -v --timeout=60
+
+      - name: Run tests (Windows)
+        if: runner.os == 'Windows'
+        run: uv run pytest tests/ -v --timeout=60

sleap_connect-0.0.8/.github/workflows/codespell.yml

@@ -0,0 +1,29 @@
+# Codespell configuration is within pyproject.toml
+---
+name: Codespell
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  codespell:
+    name: Check for spelling errors
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Annotate locations with typos
+        uses: codespell-project/codespell-problem-matcher@v1
+      - name: Codespell
+        uses: codespell-project/actions-codespell@v2
+        with:
+          skip: ".git*,*.css,openspec"
+          ignore_words_list: "doesnt,bistream"
+          check_hidden: true

sleap_connect-0.0.8/.github/workflows/worker_production.yml

@@ -0,0 +1,68 @@
+name: Build and Push sleap-rtc-worker (Production Workflow)
+
+# Legacy worker image (the room-based `sleap-rtc worker`, installed from PyPI,
+# not built from this repo). Manual only: it used to rebuild on every feature
+# branch push and overwrite the published tags. To be removed with the legacy
+# code (talmolab/sleap-connect#113).
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Get Git SHA
+        id: get_sha
+        run: echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Check disk space (before cleanup)
+        run: df -h
+
+      # Free up ~25-30GB of disk space by removing unused tools
+      # Optimized to remove only essential unused components
+      - name: Free Disk Space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
+        with:
+          tool-cache: false
+          android: true          # ~10GB saved
+          dotnet: true           # ~5GB saved
+          haskell: false         # Skip, minimal savings
+          large-packages: true   # ~8GB saved
+          docker-images: true    # ~5GB saved, important for Docker builds
+          swap-storage: false    # Skip, usually not needed
+
+      - name: Check disk space (after cleanup)
+        run: df -h
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: docker-container
+
+      - name: Authenticate to GitHub Container Registry
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
+
+      # Build and push with layer caching for faster subsequent builds
+      # First build: ~7-12 min, Cached builds: ~2-5 min (50-70% faster)
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./sleap_connect/worker
+          file: ./sleap_connect/worker/Dockerfile
+          platforms: linux/amd64
+          push: true
+          # Enable GitHub Actions cache for Docker layers
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/sleap-rtc-worker:latest
+            ghcr.io/${{ github.repository_owner }}/sleap-rtc-worker:linux-amd64
+            ghcr.io/${{ github.repository_owner }}/sleap-rtc-worker:linux-amd64-sleap-cuda
+            ghcr.io/${{ github.repository_owner }}/sleap-rtc-worker:linux-amd64-${{ steps.get_sha.outputs.sha }}
+
+      - name: Check disk space (after build)
+        if: always()
+        run: df -h	

sleap_connect-0.0.8/.github/workflows/worker_test.yml

@@ -0,0 +1,67 @@
+name: Build and Push sleap-rtc-worker (Test Workflow)
+
+# Legacy worker image (the room-based `sleap-rtc worker`, installed from PyPI,
+# not built from this repo). Manual only: it used to rebuild on every feature
+# branch push and overwrite the published tags. To be removed with the legacy
+# code (talmolab/sleap-connect#113).
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Get Git SHA
+        id: get_sha
+        run: echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Check disk space (before cleanup)
+        run: df -h
+
+      # Free up ~25-30GB of disk space by removing unused tools
+      # Optimized to remove only essential unused components
+      - name: Free Disk Space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
+        with:
+          tool-cache: false
+          android: true          # ~10GB saved
+          dotnet: true           # ~5GB saved
+          haskell: false         # Skip, minimal savings
+          large-packages: true   # ~8GB saved
+          docker-images: true    # ~5GB saved, important for Docker builds
+          swap-storage: false    # Skip, usually not needed
+
+      - name: Check disk space (after cleanup)
+        run: df -h
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: docker-container
+
+      - name: Authenticate to GitHub Container Registry
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
+
+      # Build and push with layer caching for faster subsequent builds
+      # First build: ~7-12 min, Cached builds: ~2-5 min (50-70% faster)
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./sleap_connect/worker/Dockerfile.test
+          platforms: linux/amd64
+          push: true
+          # Enable GitHub Actions cache for Docker layers
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/sleap-rtc-worker:linux-amd64-test
+            ghcr.io/${{ github.repository_owner }}/sleap-rtc-worker:linux-amd64-sleap-cuda-test
+            ghcr.io/${{ github.repository_owner }}/sleap-rtc-worker:linux-amd64-${{ steps.get_sha.outputs.sha }}-test
+
+      - name: Check disk space (after build)
+        if: always()
+        run: df -h