modal-uv 0.2.0__tar.gz

modal_uv-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,167 @@
+name: Release
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        id: setup-uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+          # Keep one stable uv cache per OS/Python so first PR runs can restore
+          # the cache populated by main. uv's cache is content-addressed; stale
+          # entries are safe, and missing artifacts are fetched during sync.
+          cache-dependency-glob: ""
+          cache-suffix: modal-uv-ci
+          restore-cache: true
+          save-cache: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+
+      - name: Show uv cache status
+        run: |
+          echo "uv cache key: ${{ steps.setup-uv.outputs.cache-key }}"
+          echo "uv cache hit: ${{ steps.setup-uv.outputs.cache-hit }}"
+
+      - name: Install dependencies
+        run: uv sync --frozen --dev
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run ty check
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distributions
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+
+  release-gate:
+    name: Release gate
+    runs-on: ubuntu-latest
+    needs: checks
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+
+    outputs:
+      should_publish: ${{ steps.release.outputs.should_publish }}
+      version: ${{ steps.release.outputs.version }}
+      tag: ${{ steps.release.outputs.tag }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Detect version bump
+        id: release
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          version_at() {
+            local rev="$1"
+            python - "$rev" <<'PY'
+          import subprocess
+          import sys
+          import tomllib
+
+          rev = sys.argv[1]
+          data = subprocess.check_output(["git", "show", f"{rev}:pyproject.toml"])
+          print(tomllib.loads(data.decode())["project"]["version"])
+          PY
+          }
+
+          current_version="$(version_at HEAD)"
+          if ! git rev-parse --verify --quiet HEAD^ >/dev/null; then
+            echo "Initial commit has no parent; skipping publish."
+            echo "version=${current_version}" >> "$GITHUB_OUTPUT"
+            echo "tag=v${current_version}" >> "$GITHUB_OUTPUT"
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          previous_version="$(version_at HEAD^)"
+          tag="v${current_version}"
+
+          echo "version=${current_version}" >> "$GITHUB_OUTPUT"
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+
+          if [[ "${current_version}" == "${previous_version}" ]]; then
+            echo "Version unchanged (${current_version}); skipping publish."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git fetch --tags --quiet
+          if git rev-parse --verify --quiet "refs/tags/${tag}" >/dev/null; then
+            echo "Tag ${tag} already exists; skipping publish."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "Version changed ${previous_version} -> ${current_version}; publishing ${tag}."
+          echo "should_publish=true" >> "$GITHUB_OUTPUT"
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release-gate
+    if: needs.release-gate.outputs.should_publish == 'true'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/modal-uv
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Download distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create and push tag
+        env:
+          TAG: ${{ needs.release-gate.outputs.tag }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "${TAG}" -m "Release ${TAG}"
+          git push origin "${TAG}"

modal_uv-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.mypy/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.modal-uv/

modal_uv-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

modal_uv-0.2.0/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Purpose
+
+`modal-uv` exists to let coding agents and developers run ordinary `uv` workflows on Modal without turning every project into a Modal application.
+
+The tool is for moments when local development is convenient, but local hardware is not enough: GPU tests, model experiments, long-running jobs, or artifact-producing scripts should be runnable from the same repo, with the same `uv` command shape, and without manual deployment ceremony.
+
+## Philosophy
+
+- Preserve the local development loop. A project should stay a normal Python project first.
+- Make remote execution feel boring. Running on Modal should be a transport choice, not a rewrite.
+- Prefer explicit project configuration over hidden global state.
+- Keep generated/runtime state out of the source tree's meaningful files.
+- Optimize for coding agents as first-class users: commands should be discoverable, repeatable, and safe to diagnose.
+- Separate fast iteration from deployment. Source changes should sync directly; deployment should happen only when the runtime shape changes.
+- Treat Modal authentication as user-level infrastructure, not repo-local project state.
+
+## Problem It Solves
+
+Without `modal-uv`, using cloud GPUs from an existing repo usually means adding Modal-specific entrypoints, managing deploy commands manually, copying files around, or teaching each coding agent a custom workflow.
+
+`modal-uv` aims to provide one small bridge: keep the repo local, run the command remotely, sync only what changed, persist useful outputs in a Modal Volume, and return enough execution information for agents and humans to inspect logs or stop work.

modal_uv-0.2.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: modal-uv
+Version: 0.2.0
+Summary: Run uv commands on Modal.com with GPU and direct file sync
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: modal>=1.4.3
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: pydantic-settings[yaml]>=2.7.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: uvicorn>=0.34.0
+Description-Content-Type: text/markdown
+
+# modal-uv
+
+Run `uv` commands on Modal.com with GPU support, direct file sync, async execution IDs, logs, abort, and persistent Modal volumes.
+
+## Installation
+
+### Option 1: Coding Agent (Recommended)
+
+Paste this prompt to your coding agent (opencode, Claude Code, Gemini CLI, etc.):
+
+```
+Install modal-uv globally and set it up:
+1. Run: pip install modal-uv
+2. Run: modal-uv onboard
+   - This opens a browser for Modal OAuth authentication
+   - Complete the auth flow in the browser
+   - It also installs the use-modal-uv skill to detected coding agents
+3. In the project repo, run: modal-uv init
+   - This creates modal-uv.yaml with defaults if missing
+   - It creates .modal-uv/ for generated state and adds it to .gitignore
+4. Edit modal-uv.yaml to set app_name, gpu, and volume.name for this project
+5. Run: modal-uv doctor
+   - This checks modal-uv health: auth state, volume existence, app deployment, daemon status
+   - Does not wake the container
+```
+
+### Option 2: Manual Getting Started
+
+```bash
+pip install modal-uv
+```
+
+Authenticate with Modal (opens browser for OAuth):
+
+```bash
+modal-uv onboard
+```
+
+This also installs the `use-modal-uv` skill to detected coding agents (`~/.config/opencode/`, `~/.claude/`, `~/.agents/`).
+
+In your project repo, initialize modal-uv files:
+
+```bash
+modal-uv init
+```
+
+This creates `modal-uv.yaml` with defaults (using the directory name as `app_name`) if missing, and creates `.modal-uv/` for generated state with a `.gitignore` entry.
+
+Edit `modal-uv.yaml` to configure your app:
+
+```yaml
+app_name: "my-project"
+gpu: "T4"
+work_dir: "/tmp/work"
+
+volumes:
+  - name: "modal-uv-cache"
+    mount_path: "/mnt/volume"
+    commit_interval_seconds: 30
+
+env: {}
+
+runtime:
+  scaledown_window_seconds: 300
+
+image:
+  python_version: "3.12"
+  base_image: "python:3.12-slim"
+
+sync:
+  ignore:
+    - "data/**"
+    - "*.ckpt"
+```
+
+Then run commands on Modal:
+
+```bash
+modal-uv run -- pytest
+```
+
+## Repository Configuration
+
+`modal-uv.yaml` at the repository root is discovered by walking up from the current directory, similar to `git` or `uv`.
+
+Fields:
+
+- `app_name`: Modal app name (required)
+- `gpu`: GPU type, such as `T4`, `A10G`, `A100`, `H100`, or `L4`
+- `work_dir`: Working directory inside the Modal container (default: `/root/work`)
+- `volumes`: Modal volumes to mount in the container; may be empty or omitted
+- `volumes[].name`: Modal volume name
+- `volumes[].mount_path`: Mount path in the container (default: `/root/.cache`)
+- `volumes[].commit_interval_seconds`: Periodic Modal Volume commit interval while a command runs (default: `30`)
+- `env`: Extra container environment variables merged over modal-uv defaults
+- `runtime.scaledown_window_seconds`: Modal worker scaledown window (default: `300`)
+- `runtime.exec`: Optional shell executable for `modal-uv exec`; if omitted, the remote Worker uses `$SHELL`, then `/bin/sh`
+- `image.python_version`: Python version (default: `3.12`)
+- `image.base_image`: Base Docker image (default: `python:3.12-slim`)
+- `sync.ignore`: gitignore-style patterns excluded from direct sync
+
+## Repo-Local State
+
+`modal-uv` creates `.modal-uv/` at the repo root for generated/runtime files and ensures the root `.gitignore` ignores it.
+
+Examples of generated files:
+
+- `.modal-uv/deployment.py`
+- `.modal-uv/daemon.pid`
+- `.modal-uv/daemon.sock`
+- `.modal-uv/daemon.log`
+
+`.modal-uv/` is not normally synced to the Modal work directory.
+
+## Sync And Deployment
+
+`modal-uv run` and `modal-uv exec` scan local files, apply built-in ignores plus `sync.ignore`, ask the warm Modal container which files are missing or stale, upload only those files, spawn the execution, print the Modal function call ID, and return immediately.
+
+The detached daemon lazily ensures the Modal app is deployed before running work. It generates `.modal-uv/deployment.py` and redeploys when the deployment fingerprint changes. The fingerprint includes the deployment template, Modal-relevant config values, and the repo `pyproject.toml` SHA256 when present.
+
+During a running command, `modal-uv` periodically commits the Modal Volume every `volume.commit_interval_seconds` seconds, plus one final commit after the command exits. This persists outputs and checkpoints written under the mounted volume during long runs.
+
+Ordinary source changes do not redeploy the app; they are handled by direct sync.
+
+Modal authentication remains Modal's normal user-global authentication. `modal-uv` does not create repo-local auth files.
+
+## Commands
+
+Run `uv` commands on Modal:
+
+```bash
+modal-uv run -- pytest
+modal-uv run -- python -m lab
+modal-uv run -- python train.py --epochs 10
+```
+
+Tail or abort a spawned execution:
+
+```bash
+modal-uv logs fc-...
+modal-uv abort fc-...
+```
+
+Run shell-style commands in the synced Modal work directory:
+
+```bash
+modal-uv exec -- nvidia-smi
+modal-uv exec -- 'ls -la && pwd'
+```
+
+Open Modal's native interactive shell through the passthrough command:
+
+```bash
+modal-uv modal -- shell
+```
+
+Show Modal app status:
+
+```bash
+modal-uv status
+```
+
+Check the configured Modal volume directly:
+
+```bash
+modal-uv modal -- volume ls modal-uv-cache
+```
+
+Initialize or align modal-uv files in the current directory:
+
+```bash
+modal-uv init
+```
+
+Run any Modal CLI command through the modal-uv environment:
+
+```bash
+modal-uv modal -- app list
+modal-uv modal -- volume ls
+```
+
+Daemon helpers:
+
+```bash
+modal-uv daemon-status
+modal-uv daemon-stop
+```
+
+## Updates
+
+Upgrade modal-uv and refresh the skill on all detected agents:
+
+```bash
+modal-uv update
+```
+
+Install the skill to a specific agent (`opencode`, `claude`, `agents`) or an explicit directory path:
+
+```bash
+modal-uv install-skill opencode
+modal-uv install-skill /path/to/skills/dir
+```
+
+Detected agents are based on which config directories exist (`~/.config/opencode/`, `~/.claude/`, `~/.agents/`).
+
+Use `--config` or `-c` to specify a custom config file:
+
+```bash
+modal-uv run --config path/to/modal-uv.yaml -- pytest
+```
+
+## Checks
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```

modal_uv-0.2.0/README.md

@@ -0,0 +1,218 @@
+# modal-uv
+
+Run `uv` commands on Modal.com with GPU support, direct file sync, async execution IDs, logs, abort, and persistent Modal volumes.
+
+## Installation
+
+### Option 1: Coding Agent (Recommended)
+
+Paste this prompt to your coding agent (opencode, Claude Code, Gemini CLI, etc.):
+
+```
+Install modal-uv globally and set it up:
+1. Run: pip install modal-uv
+2. Run: modal-uv onboard
+   - This opens a browser for Modal OAuth authentication
+   - Complete the auth flow in the browser
+   - It also installs the use-modal-uv skill to detected coding agents
+3. In the project repo, run: modal-uv init
+   - This creates modal-uv.yaml with defaults if missing
+   - It creates .modal-uv/ for generated state and adds it to .gitignore
+4. Edit modal-uv.yaml to set app_name, gpu, and volume.name for this project
+5. Run: modal-uv doctor
+   - This checks modal-uv health: auth state, volume existence, app deployment, daemon status
+   - Does not wake the container
+```
+
+### Option 2: Manual Getting Started
+
+```bash
+pip install modal-uv
+```
+
+Authenticate with Modal (opens browser for OAuth):
+
+```bash
+modal-uv onboard
+```
+
+This also installs the `use-modal-uv` skill to detected coding agents (`~/.config/opencode/`, `~/.claude/`, `~/.agents/`).
+
+In your project repo, initialize modal-uv files:
+
+```bash
+modal-uv init
+```
+
+This creates `modal-uv.yaml` with defaults (using the directory name as `app_name`) if missing, and creates `.modal-uv/` for generated state with a `.gitignore` entry.
+
+Edit `modal-uv.yaml` to configure your app:
+
+```yaml
+app_name: "my-project"
+gpu: "T4"
+work_dir: "/tmp/work"
+
+volumes:
+  - name: "modal-uv-cache"
+    mount_path: "/mnt/volume"
+    commit_interval_seconds: 30
+
+env: {}
+
+runtime:
+  scaledown_window_seconds: 300
+
+image:
+  python_version: "3.12"
+  base_image: "python:3.12-slim"
+
+sync:
+  ignore:
+    - "data/**"
+    - "*.ckpt"
+```
+
+Then run commands on Modal:
+
+```bash
+modal-uv run -- pytest
+```
+
+## Repository Configuration
+
+`modal-uv.yaml` at the repository root is discovered by walking up from the current directory, similar to `git` or `uv`.
+
+Fields:
+
+- `app_name`: Modal app name (required)
+- `gpu`: GPU type, such as `T4`, `A10G`, `A100`, `H100`, or `L4`
+- `work_dir`: Working directory inside the Modal container (default: `/root/work`)
+- `volumes`: Modal volumes to mount in the container; may be empty or omitted
+- `volumes[].name`: Modal volume name
+- `volumes[].mount_path`: Mount path in the container (default: `/root/.cache`)
+- `volumes[].commit_interval_seconds`: Periodic Modal Volume commit interval while a command runs (default: `30`)
+- `env`: Extra container environment variables merged over modal-uv defaults
+- `runtime.scaledown_window_seconds`: Modal worker scaledown window (default: `300`)
+- `runtime.exec`: Optional shell executable for `modal-uv exec`; if omitted, the remote Worker uses `$SHELL`, then `/bin/sh`
+- `image.python_version`: Python version (default: `3.12`)
+- `image.base_image`: Base Docker image (default: `python:3.12-slim`)
+- `sync.ignore`: gitignore-style patterns excluded from direct sync
+
+## Repo-Local State
+
+`modal-uv` creates `.modal-uv/` at the repo root for generated/runtime files and ensures the root `.gitignore` ignores it.
+
+Examples of generated files:
+
+- `.modal-uv/deployment.py`
+- `.modal-uv/daemon.pid`
+- `.modal-uv/daemon.sock`
+- `.modal-uv/daemon.log`
+
+`.modal-uv/` is not normally synced to the Modal work directory.
+
+## Sync And Deployment
+
+`modal-uv run` and `modal-uv exec` scan local files, apply built-in ignores plus `sync.ignore`, ask the warm Modal container which files are missing or stale, upload only those files, spawn the execution, print the Modal function call ID, and return immediately.
+
+The detached daemon lazily ensures the Modal app is deployed before running work. It generates `.modal-uv/deployment.py` and redeploys when the deployment fingerprint changes. The fingerprint includes the deployment template, Modal-relevant config values, and the repo `pyproject.toml` SHA256 when present.
+
+During a running command, `modal-uv` periodically commits the Modal Volume every `volume.commit_interval_seconds` seconds, plus one final commit after the command exits. This persists outputs and checkpoints written under the mounted volume during long runs.
+
+Ordinary source changes do not redeploy the app; they are handled by direct sync.
+
+Modal authentication remains Modal's normal user-global authentication. `modal-uv` does not create repo-local auth files.
+
+## Commands
+
+Run `uv` commands on Modal:
+
+```bash
+modal-uv run -- pytest
+modal-uv run -- python -m lab
+modal-uv run -- python train.py --epochs 10
+```
+
+Tail or abort a spawned execution:
+
+```bash
+modal-uv logs fc-...
+modal-uv abort fc-...
+```
+
+Run shell-style commands in the synced Modal work directory:
+
+```bash
+modal-uv exec -- nvidia-smi
+modal-uv exec -- 'ls -la && pwd'
+```
+
+Open Modal's native interactive shell through the passthrough command:
+
+```bash
+modal-uv modal -- shell
+```
+
+Show Modal app status:
+
+```bash
+modal-uv status
+```
+
+Check the configured Modal volume directly:
+
+```bash
+modal-uv modal -- volume ls modal-uv-cache
+```
+
+Initialize or align modal-uv files in the current directory:
+
+```bash
+modal-uv init
+```
+
+Run any Modal CLI command through the modal-uv environment:
+
+```bash
+modal-uv modal -- app list
+modal-uv modal -- volume ls
+```
+
+Daemon helpers:
+
+```bash
+modal-uv daemon-status
+modal-uv daemon-stop
+```
+
+## Updates
+
+Upgrade modal-uv and refresh the skill on all detected agents:
+
+```bash
+modal-uv update
+```
+
+Install the skill to a specific agent (`opencode`, `claude`, `agents`) or an explicit directory path:
+
+```bash
+modal-uv install-skill opencode
+modal-uv install-skill /path/to/skills/dir
+```
+
+Detected agents are based on which config directories exist (`~/.config/opencode/`, `~/.claude/`, `~/.agents/`).
+
+Use `--config` or `-c` to specify a custom config file:
+
+```bash
+modal-uv run --config path/to/modal-uv.yaml -- pytest
+```
+
+## Checks
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```