hyperstudy-perception 0.1.0__tar.gz

hyperstudy_perception-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hyperstudy_perception-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: hyperstudy-perception
+Version: 0.1.0
+Summary: Video perception pipeline: shots, speech, faces and captions from a video, as a versioned track bundle, run locally, on cloud GPUs or lab servers
+Project-URL: Homepage, https://github.com/hyperstudyio/hyperstudy-perception
+Project-URL: Changelog, https://github.com/hyperstudyio/hyperstudy-perception/releases
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: annotated-types==0.8.0
+Requires-Dist: attrs==26.1.0
+Requires-Dist: av==16.1.0
+Requires-Dist: cffi==2.1.1; platform_python_implementation != 'PyPy' and sys_platform == 'linux'
+Requires-Dist: cryptography==50.0.2; sys_platform == 'linux'
+Requires-Dist: jaraco-classes==3.4.0
+Requires-Dist: jaraco-context==6.1.2
+Requires-Dist: jaraco-functools==4.6.0
+Requires-Dist: jeepney==0.9.0; sys_platform == 'linux'
+Requires-Dist: jsonschema-specifications==2025.9.1
+Requires-Dist: jsonschema==4.26.0
+Requires-Dist: keyring==25.7.0
+Requires-Dist: more-itertools==11.2.1
+Requires-Dist: pycparser==3.12; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy' and sys_platform == 'linux'
+Requires-Dist: pydantic-core==2.50.1
+Requires-Dist: pydantic==2.14.1
+Requires-Dist: pywin32-ctypes==0.2.3; sys_platform == 'win32'
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: referencing==0.37.0
+Requires-Dist: rpds-py==2026.9.1
+Requires-Dist: secretstorage==3.5.0; sys_platform == 'linux'
+Requires-Dist: typing-extensions==4.16.0
+Requires-Dist: typing-inspection==0.4.4
+Description-Content-Type: text/markdown
+
+# hyperstudy-perception
+
+Turn a video into a time-indexed **perception track**: shots and keyframes, a word-timed transcript, face tracks
+clustered into people, and shot captions. The result is a versioned track bundle that the
+[HyperStudy Annotator](https://github.com/hyperstudyio/hyperstudy-annotator) imports for review and correction.
+
+```sh
+uv tool install hyperstudy-perception
+perception doctor                       # what can run on this machine
+perception graphs                       # the graphs it can run, by name
+perception run full.yaml --input video=clip.mp4 --only asr,faces --allow-downloads
+```
+
+Each step runs in its own locked environment, made by [uv](https://docs.astral.sh/uv/) the first time it is needed
+(`perception setup` makes them all ahead of time), under `~/.hyperstudy-perception`. Nothing else is needed on the
+machine: video is read with PyAV, whose wheels carry FFmpeg.
+
+Model weights are downloaded at run time under their own licences; several (py-feat, ArcFace) are non-commercial, and
+each bundle records the most restrictive licence among its layers.

hyperstudy_perception-0.1.0/README.md

@@ -0,0 +1,19 @@
+# hyperstudy-perception
+
+Turn a video into a time-indexed **perception track**: shots and keyframes, a word-timed transcript, face tracks
+clustered into people, and shot captions. The result is a versioned track bundle that the
+[HyperStudy Annotator](https://github.com/hyperstudyio/hyperstudy-annotator) imports for review and correction.
+
+```sh
+uv tool install hyperstudy-perception
+perception doctor                       # what can run on this machine
+perception graphs                       # the graphs it can run, by name
+perception run full.yaml --input video=clip.mp4 --only asr,faces --allow-downloads
+```
+
+Each step runs in its own locked environment, made by [uv](https://docs.astral.sh/uv/) the first time it is needed
+(`perception setup` makes them all ahead of time), under `~/.hyperstudy-perception`. Nothing else is needed on the
+machine: video is read with PyAV, whose wheels carry FFmpeg.
+
+Model weights are downloaded at run time under their own licences; several (py-feat, ArcFace) are non-commercial, and
+each bundle records the most restrictive licence among its layers.

hyperstudy_perception-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "hyperstudy-perception"
+version = "0.1.0"
+description = "Video perception pipeline: shots, speech, faces and captions from a video, as a versioned track bundle, run locally, on cloud GPUs or lab servers"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]   # the repository's, copied in by scripts/build-dist.sh
+requires-python = ">=3.12"
+dependencies = [
+  "annotated-types==0.8.0",
+  "attrs==26.1.0",
+  "av==16.1.0",
+  "cffi==2.1.1 ; platform_python_implementation != 'PyPy' and sys_platform == 'linux'",
+  "cryptography==50.0.2 ; sys_platform == 'linux'",
+  "jaraco-classes==3.4.0",
+  "jaraco-context==6.1.2",
+  "jaraco-functools==4.6.0",
+  "jeepney==0.9.0 ; sys_platform == 'linux'",
+  "jsonschema==4.26.0",
+  "jsonschema-specifications==2025.9.1",
+  "keyring==25.7.0",
+  "more-itertools==11.2.1",
+  "pycparser==3.12 ; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy' and sys_platform == 'linux'",
+  "pydantic==2.14.1",
+  "pydantic-core==2.50.1",
+  "pywin32-ctypes==0.2.3 ; sys_platform == 'win32'",
+  "pyyaml==6.0.3",
+  "referencing==0.37.0",
+  "rpds-py==2026.9.1",
+  "secretstorage==3.5.0 ; sys_platform == 'linux'",
+  "typing-extensions==4.16.0",
+  "typing-inspection==0.4.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/hyperstudyio/hyperstudy-perception"
+Changelog = "https://github.com/hyperstudyio/hyperstudy-perception/releases"
+
+[project.scripts]
+perception = "perception.cli:main"
+
+[tool.uv.sources]
+perception-node = { path = "../sdk", editable = true }
+
+[dependency-groups]
+# the node SDK only for the tests' stand-in nodes, which run in this interpreter: real nodes get it in their own
+# environments (envs/*), from the copy the package carries
+dev = ["pytest>=8", "perception-node"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/perception"]
+# the pipeline's files the package carries (scripts/build-dist.sh puts them there; ignored by git, so named here)
+artifacts = ["src/perception/_pipeline/**"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/perception", "README.md"]
+artifacts = ["src/perception/_pipeline/**"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

hyperstudy_perception-0.1.0/src/perception/_pipeline/RELEASE.json

@@ -0,0 +1,59 @@
+{
+"commit": "9beebed7f711b6c85e2a735810db16841a741f39",
+"files": [
+"cloud/runpod/guard.sh",
+"cloud/runpod/image/Dockerfile",
+"cloud/runpod/image/start.sh",
+"cloud/runpod/image/tag.py",
+"cloud/skypilot/gpu-faces.yaml",
+"cloud/skypilot/gpu-tune.yaml",
+"cloud/skypilot/guard.sh",
+"cloud/skypilot/iam-perception-node.json",
+"cloud/skypilot/launch.sh",
+"cloud/skypilot/node-gpu.yaml",
+"cloud/skypilot/node-setup.sh",
+"cloud/skypilot/sky.yaml",
+"cloud/skypilot/smoke.yaml",
+"envs/api/pyproject.toml",
+"envs/api/uv.lock",
+"envs/audio/pyproject.toml",
+"envs/audio/uv.lock",
+"envs/core/pyproject.toml",
+"envs/core/uv.lock",
+"envs/faces/pyproject.toml",
+"envs/faces/uv.lock",
+"graphs/decode.yaml",
+"graphs/faces.yaml",
+"graphs/full.yaml",
+"graphs/mvp-captions.yaml",
+"graphs/mvp.yaml",
+"nodes/audio/asr/manifest.yaml",
+"nodes/audio/asr/node.py",
+"nodes/audio/asr/prepare.py",
+"nodes/audio/asr/test_wav.py",
+"nodes/audio/asr/wav.py",
+"nodes/conftest.py",
+"nodes/core/decode/manifest.yaml",
+"nodes/core/decode/media.py",
+"nodes/core/decode/node.py",
+"nodes/core/decode/test_media.py",
+"nodes/testdata/README.md",
+"nodes/testdata/rotated-90.mp4",
+"nodes/vision/face-track/frames.py",
+"nodes/vision/face-track/loader.py",
+"nodes/vision/face-track/manifest.yaml",
+"nodes/vision/face-track/node.py",
+"nodes/vision/face-track/prepare.py",
+"nodes/vision/face-track/test_frames.py",
+"nodes/vision/face-track/test_loader.py",
+"nodes/vision/face-track/test_thumbnails.py",
+"nodes/vision/face-track/thumbnails.py",
+"nodes/vision/face-track/tracking.py",
+"nodes/vlm/shot-captions/manifest.yaml",
+"nodes/vlm/shot-captions/node.py",
+"schema/README.md",
+"schema/bundle-0.1.schema.json",
+"sdk/pyproject.toml",
+"sdk/src/perception_node/__init__.py"
+]
+}

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/runpod/guard.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# First step on every RunPod pod, before anything is sent (remote_driver.py runs it over ssh):
+#   bash -s MIN_DRIVER < cloud/runpod/guard.sh       (the oldest NVIDIA driver the nodes' torch runs on, e.g. 580)
+# 1. The pod's removal at its deadline is running: its start command set it (runpodctl, with the pod's own key), the
+#    backstop if the laptop never comes back to delete it. That key is scoped to the pod: it removes the pod, and can
+#    neither list the account's pods nor remove another (both checked on RunPod, 2026-10-25).
+# 2. No key to the account on the pod: the pod's own key is refused by the API, and there is no RunPod or AWS config.
+set -euo pipefail
+min_driver=$1
+environ=${PERCEPTION_POD_ENVIRON:-/proc/1/environ}   # the container's own variables (ssh sessions do not inherit them)
+var() { tr '\0' '\n' < "$environ" | sed -n "s/^$1=//p"; }
+pod=$(var RUNPOD_POD_ID)
+[ -n "$pod" ] || { echo "guard: no RUNPOD_POD_ID in the pod's environment: not a RunPod pod" >&2; exit 1; }
+command -v runpodctl > /dev/null || { echo "guard: runpodctl is missing: the pod could not remove itself at its deadline" >&2; exit 1; }
+for f in ~/.runpod/config.toml ~/.runpod/config.yaml ~/.aws/credentials ~/.aws/config; do
+  [ ! -e "$f" ] || { echo "guard: $f exists on the pod: a key to an account must never be there" >&2; exit 1; }
+done
+# its own key: what removes it at the deadline
+[ -n "$(var RUNPOD_API_KEY)" ] || { echo "guard: no RUNPOD_API_KEY in the pod's environment: it could not remove itself at its deadline" >&2; exit 1; }
+# the pod's key must not reach the account: RunPod answers 401 or 403 to it for the account's pods. Exit 75: the check could
+# not be made (no answer, RunPod's own trouble), which says nothing about the key (the driver tries another pod)
+code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 30 -A hyperstudy-perception \
+       -H "Authorization: Bearer $(var RUNPOD_API_KEY)" "${PERCEPTION_RUNPOD_API:-https://rest.runpod.io/v1}/pods" || true)
+case "$code" in
+  401|403) ;;
+  2??) echo "guard: the pod's own key got $code listing the account's pods (401 or 403 expected): not used" >&2; exit 1 ;;
+  *) echo "guard: could not check the pod's own key (RunPod answered ${code:-nothing}); another pod is tried" >&2; exit 75 ;;
+esac
+# its removal at the deadline, which its start command set before anything else ran (remote_driver.removal_at_boot)
+pgrep -f perception-deadline > /dev/null || { echo "guard: the pod's removal at its deadline is not running" >&2; exit 1; }
+# a driver new enough for the nodes' CUDA, checked here only (RunPod's allowedCudaVersions is not used: see
+# remote_driver.runpod_launch): exit 75, another pod may have one
+driver=$(nvidia-smi --query-gpu=driver_version --format=csv,noheader 2> /dev/null | head -1 || true)
+[ "${driver%%.*}" -ge "$min_driver" ] 2> /dev/null || {
+  echo "guard: the pod's NVIDIA driver is ${driver:-not known}, older than $min_driver (the nodes' CUDA); another pod is tried" >&2; exit 75; }
+gpu=$(nvidia-smi --query-gpu=name --format=csv,noheader 2> /dev/null | head -1 || true)
+echo "guard: ${gpu:-no GPU seen} (driver $driver) in $(var RUNPOD_DC_ID); no key to the account; its removal at its deadline is running"

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/runpod/image/Dockerfile

@@ -0,0 +1,39 @@
+# The RunPod image for perception's nodes (RunPodBackend.image): software only, no repository code, weights or data
+# (it is public). Built by .github/workflows/runpod-image.yml from the context tag.py stages (these two files).
+#
+# On RunPod's own PyTorch image, which its hosts keep cached: our image's start then pulls only the small layers below
+# (measured: a 6.8 GB image of our own took 145 s to start, the cached one 12-32 s). The nodes' environments are not in
+# it: uv fetches them from PyPI in the datacenter faster than a host pulls them from GHCR. Its Python and torch are
+# not used (uv brings each node's own).
+FROM runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04@sha256:2594f25beeef751aeebcc207ba4c45a382ba174655f01e15cbbfad0e2bdb5ef8
+ENV DEBIAN_FRONTEND=noninteractive
+
+# what nodes and the driver use (setup then installs nothing); sshd takes keys only. Each pod makes its own host keys
+# at start (start.sh): the ones in the base image are public, and are never used
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ffmpeg rsync \
+ && rm -rf /var/lib/apt/lists/* /etc/ssh/ssh_host_* \
+ && mkdir -p /run/sshd /etc/ssh/sshd_config.d \
+ && printf 'PermitRootLogin prohibit-password\nPasswordAuthentication no\nKbdInteractiveAuthentication no\n' \
+      > /etc/ssh/sshd_config.d/perception.conf \
+ && { grep -q '^Include /etc/ssh/sshd_config.d' /etc/ssh/sshd_config || sed -i '1i Include /etc/ssh/sshd_config.d/*.conf' /etc/ssh/sshd_config; }
+
+# runpodctl 3, for the pod's removal at its deadline with its own key (remote_driver.removal_at_boot)
+ARG RUNPODCTL=3.0.1
+ARG RUNPODCTL_SHA256=b66d11eca8cacbf18a2de6943c6e18a79ffbdc8a3c30aa13a49dc6cfc15d4239
+RUN curl -fsSL -o /usr/local/bin/runpodctl https://github.com/runpod/runpodctl/releases/download/v${RUNPODCTL}/runpodctl-linux-amd64 \
+ && echo "${RUNPODCTL_SHA256}  /usr/local/bin/runpodctl" | sha256sum -c - \
+ && chmod 755 /usr/local/bin/runpodctl
+
+# uv, the version the annotator app bundles, where node-setup.sh puts it
+ARG UV=0.13.5
+ARG UV_SHA256=f68d291c75783122dad58ab77def0e13f3233f358731db5d6d7e8715603b928f
+RUN curl -fsSL -o /tmp/uv.tgz https://github.com/astral-sh/uv/releases/download/${UV}/uv-x86_64-unknown-linux-gnu.tar.gz \
+ && echo "${UV_SHA256}  /tmp/uv.tgz" | sha256sum -c - \
+ && mkdir -p /root/.perception-uv \
+ && tar -xzf /tmp/uv.tgz -C /root/.perception-uv --strip-components=1 \
+ && rm /tmp/uv.tgz \
+ && /root/.perception-uv/uv --version
+
+COPY start.sh /perception-start.sh
+CMD ["/perception-start.sh"]

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/runpod/image/start.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# A pod's start (the image's CMD; remote_driver.removal_at_boot runs it after setting the pod's removal): ssh host keys
+# of its own, the key the driver made for it (PUBLIC_KEY, from RunPod), and sshd. Nothing else runs until the driver
+# connects.
+set -eu
+ssh-keygen -A
+mkdir -p /root/.ssh
+chmod 700 /root/.ssh
+printf '%s\n' "${PUBLIC_KEY:?the pod was given no PUBLIC_KEY}" > /root/.ssh/authorized_keys
+chmod 600 /root/.ssh/authorized_keys
+exec /usr/sbin/sshd -D -e

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/runpod/image/tag.py

@@ -0,0 +1,40 @@
+"""The RunPod image's tag, from everything that goes into it (its Dockerfile and start.sh), and its build context:
+
+    python3 cloud/runpod/image/tag.py                  prints the tag (12 hex digits)
+    python3 cloud/runpod/image/tag.py --context DIR    also copies exactly those files into DIR (what is built)
+
+The same files give the same tag: RunPodBackend.image_tag must equal it (a test checks), so a change to the image needs
+a new build (.github/workflows/runpod-image.yml) and that tag. Standard library only."""
+
+import hashlib
+import shutil
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+
+
+def files() -> dict[str, Path]:
+    """Each file in the context, by its path there."""
+    return {name: HERE / name for name in ("Dockerfile", "start.sh")}
+
+
+def tag() -> str:
+    h = hashlib.sha256()
+    for name, path in sorted(files().items()):
+        h.update(name.encode() + b"\0" + path.read_bytes() + b"\0")
+    return h.hexdigest()[:12]
+
+
+def stage(dest: Path):
+    for name, path in files().items():
+        (dest / name).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, dest / name)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 3 and sys.argv[1] == "--context":
+        stage(Path(sys.argv[2]))
+    elif len(sys.argv) != 1:
+        sys.exit(__doc__)
+    print(tag())

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/gpu-faces.yaml

@@ -0,0 +1,39 @@
+# First NVIDIA run: decode + face tracks on one clip, on an L4 or A10G machine. The clip is copied to the machine only
+# (file mount from the laptop) and deleted with it. Results are exported to ~/out for the laptop to fetch before the
+# cluster is deleted. Sending a study's stimulus to a cloud machine needs that study's approval: a whole graph run
+# off the laptop is not checked by the graph's privacy policy.
+#   cloud/skypilot/launch.sh cloud/skypilot/gpu-faces.yaml perception-gpu --env CLIP_SRC=/path/to/clip.mp4
+resources:
+  cloud: aws
+  region: us-east-1
+  # L4 (g6) or A10G (g5): both 24 GB. On 2026-10-23 us-east-1 had no g6.xlarge spot capacity in any zone, and the
+  # account's G spot quota is 0 outside us-east-1.
+  accelerators: {L4: 1, A10G: 1}
+  use_spot: true
+  disk_size: 60
+
+envs:
+  CLIP_SRC: null      # required: the clip on the laptop
+
+file_mounts:
+  /data/clip.mp4: ${CLIP_SRC}
+
+setup: |
+  set -e
+  bash cloud/skypilot/guard.sh 90
+  sudo apt-get update -qq && sudo apt-get install -y -qq ffmpeg > /dev/null
+  command -v uv || curl -LsSf https://astral.sh/uv/install.sh | sh
+  export PATH=$HOME/.local/bin:$PATH
+  (cd orchestrator && uv sync -q) && (cd envs/core && uv sync -q) && (cd envs/faces && uv sync -q)
+
+run: |
+  set -e
+  export PATH=$HOME/.local/bin:$PATH
+  nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv
+  (cd envs/faces && uv run python -c "import torch; print('torch', torch.__version__, 'cuda', torch.cuda.is_available(), torch.version.cuda)")
+  cd orchestrator
+  uv run perception doctor
+  time uv run perception run ../graphs/faces.yaml --input video=/data/clip.mp4 --allow-downloads
+  run=$(uv run perception status | awk 'NR==1{print $1}')
+  uv run perception export "$run" --output ~/out/bundle
+  cp -r ~/.hyperstudy-perception/work/"$run" ~/out/work

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/gpu-tune.yaml

@@ -0,0 +1,55 @@
+# What limits the face node on an L4: one machine, one decode, then the face node at several batch sizes and numbers
+# of frame-decoding workers, with GPU utilisation logged every second. g6.2xlarge (8 vCPUs), so batch 32 with no
+# workers compares directly with the first run on a g6.xlarge (4 vCPUs). Results go to ~/out for the laptop to fetch.
+# Copies the clip to the machine, like gpu-faces.yaml (see there on approval).
+#   cloud/skypilot/launch.sh cloud/skypilot/gpu-tune.yaml perception-tune --env CLIP_SRC=/path/to/clip.mp4
+resources:
+  cloud: aws
+  region: us-east-1
+  accelerators: L4:1
+  cpus: 8
+  use_spot: false     # no L4 spot capacity in us-east-1 on 2026-10-23
+  disk_size: 60
+
+envs:
+  CLIP_SRC: null      # required: the clip on the laptop
+  # batch_size:num_workers. Batch 64 ran out of GPU memory on 2026-10-24 (py-feat feeds whole 1080p frames).
+  SWEEP: "8:0 16:0 32:0 16:4 32:4"
+
+file_mounts:
+  /data/clip.mp4: ${CLIP_SRC}
+
+setup: |
+  set -e
+  bash cloud/skypilot/guard.sh 90
+  sudo apt-get update -qq && sudo apt-get install -y -qq ffmpeg > /dev/null
+  command -v uv || curl -LsSf https://astral.sh/uv/install.sh | sh
+  export PATH=$HOME/.local/bin:$PATH
+  (cd orchestrator && uv sync -q) && (cd envs/core && uv sync -q) && (cd envs/faces && uv sync -q)
+
+run: |
+  set -e
+  export PATH=$HOME/.local/bin:$PATH
+  mkdir -p ~/out
+  # Background processes end with the job however it ends: a GPU logger left running kept a failed job open on
+  # 2026-10-24 until it was cancelled by hand.
+  trap 'kill $(jobs -p) 2>/dev/null || :' EXIT
+  nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv | tee ~/out/gpu.txt
+  # Ray, which runs SkyPilot jobs, sets OMP_NUM_THREADS=1, and PyTorch takes its CPU thread count from it.
+  echo "vCPUs $(nproc --all); OMP_NUM_THREADS from the job: ${OMP_NUM_THREADS:-unset}" | tee -a ~/out/gpu.txt
+  export OMP_NUM_THREADS=$(nproc --all)
+  nvidia-smi dmon -s um -o T > ~/out/dmon.txt 2>&1 &
+  cd orchestrator
+  uv run perception run ../graphs/decode.yaml --input video=/data/clip.mp4
+  for point in $SWEEP; do
+    b=${point%:*}; w=${point#*:}
+    sed "s/uses: vision.face-track@1.0.0/&\n    config: {batch_size: $b, num_workers: $w}/" ../graphs/faces.yaml > ../graphs/tune-$b-$w.yaml
+    echo "=== batch $b workers $w $(date +%T)" | tee -a ~/out/sweep.txt
+    SECONDS=0
+    # A failed point is recorded (with its error code, from status) and the sweep goes on.
+    if uv run perception run ../graphs/tune-$b-$w.yaml --input video=/data/clip.mp4 --allow-downloads; then result=ok; else result=failed; fi
+    echo "wall ${SECONDS}s $result end $(date +%T)" | tee -a ~/out/sweep.txt
+    run=$(uv run perception status | awk 'NR==1{print $1}')
+    uv run perception status "$run" | tee -a ~/out/sweep.txt
+    cp -r ~/.hyperstudy-perception/work/"$run" ~/out/work-$b-$w
+  done

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/guard.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# First step of every task's setup: a shutdown deadline, and a check that the machine holds no AWS credentials
+# and no role beyond perception-node.
+#   bash cloud/skypilot/guard.sh MINUTES
+# The deadline is the backstop if the laptop never comes back to delete the machine. launch.sh makes an OS shutdown
+# terminate the instance (EC2's default for on-demand machines is to stop it, which keeps the disk billing).
+set -euo pipefail
+sudo shutdown -h "+$1"
+if [ -e ~/.aws/credentials ] || [ -e ~/.aws/config ]; then
+  echo "guard: ~/.aws exists on the machine; sky.yaml was not applied" >&2; exit 1
+fi
+token=$(curl -sf -X PUT http://169.254.169.254/latest/api/token -H "X-aws-ec2-metadata-token-ttl-seconds: 60")
+# The only role allowed is perception-node, which can end perception-* machines and nothing else (sky.yaml).
+profile=$(curl -sf -H "X-aws-ec2-metadata-token: $token" http://169.254.169.254/latest/meta-data/iam/info \
+          | python3 -c 'import json,sys; print(json.load(sys.stdin)["InstanceProfileArn"])' || echo none)
+case "$profile" in
+  */perception-node) ;;
+  *) echo "guard: the instance profile is $profile, not perception-node; sky.yaml was not applied" >&2; exit 1 ;;
+esac
+echo "guard: no AWS credentials; role perception-node; shutdown in $1 min"

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/iam-perception-node.json

@@ -0,0 +1,18 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "FindTheCluster",
+      "Effect": "Allow",
+      "Action": ["ec2:DescribeInstances", "ec2:DescribeSecurityGroups", "ec2:DescribeVpcs"],
+      "Resource": "*"
+    },
+    {
+      "Sid": "EndPerceptionMachinesOnly",
+      "Effect": "Allow",
+      "Action": "ec2:TerminateInstances",
+      "Resource": "arn:aws:ec2:*:*:instance/*",
+      "Condition": {"StringLike": {"aws:ResourceTag/skypilot-cluster-name": "perception-*"}}
+    }
+  ]
+}

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/launch.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Run one task on AWS and delete the machine afterwards.
+#   [OUT=DIR] cloud/skypilot/launch.sh TASK.yaml CLUSTER [sky launch options, e.g. --env CLIP_SRC=/path/to/clip.mp4]
+# With OUT set, the machine's ~/out is copied into DIR before the machine is deleted (also when the job failed).
+# - SkyPilot reads sky.yaml as the project config: no credentials copied, and only the perception-node role.
+# - The workdir is a staged copy of the files git tracks, nothing else: commit a new file before a launch that needs
+#   it. (Untracked files were staged too until 2026-10-24; .gitignore does not cover every image, crop or bundle
+#   folder that can sit in a working copy.)
+# - Once the instance exists, its OS shutdown is set to terminate it, so guard.sh's deadline deletes on-demand
+#   machines as well as spot ones.
+# - sky down runs on exit, whether the job succeeded, failed or was interrupted.
+# - A wall-clock deadline (MAX_MINUTES, default 60) ends the launch, and so deletes the machine, whatever the job is
+#   doing: a hang of any kind (a stray process holding the job open, a stuck download) costs at most that long.
+set -euo pipefail
+task=$(cd "$(dirname "$1")" && pwd)/$(basename "$1"); cluster=$2; shift 2
+case "$cluster" in
+  perception-*) ;;
+  *) echo "launch.sh: cluster names start with perception- (the machine's role can only end those machines)" >&2; exit 2 ;;
+esac
+repo=$(git -C "$(dirname "$0")" rev-parse --show-toplevel)
+region=us-east-1
+export SKYPILOT_PROJECT_CONFIG=$repo/cloud/skypilot/sky.yaml
+
+stage=$(mktemp -d)
+git -C "$repo" ls-files -z | rsync -a --from0 --files-from=- "$repo/" "$stage/"
+finish() {
+  kill "${watcher:-}" "${deadline:-}" 2>/dev/null || :
+  if [ -n "${OUT:-}" ]; then mkdir -p "$OUT"; rsync -a "$cluster:out/" "$OUT/" || echo "launch.sh: could not fetch ~/out" >&2; fi
+  sky down -y "$cluster"
+  rm -rf "$stage"
+}
+trap finish EXIT
+
+# SkyPilot provisions the instance a few seconds to minutes into `sky launch`; set its shutdown behaviour as soon as it
+# exists. Gives up loudly after 15 minutes (then only `sky down`, autodown or MAX_MINUTES deletes it). Not under
+# set -e: one failed AWS call must not end the watcher silently.
+(
+  set +e
+  for _ in $(seq 90); do
+    ids=$(aws ec2 describe-instances --region "$region" --output text --query 'Reservations[].Instances[].InstanceId' \
+          --filters "Name=tag:skypilot-cluster-name,Values=$cluster*" Name=instance-state-name,Values=pending,running)
+    if [ -n "$ids" ]; then
+      for id in $ids; do
+        if aws ec2 modify-instance-attribute --region "$region" --instance-id "$id" --instance-initiated-shutdown-behavior terminate; then
+          echo "launch.sh: $id terminates on OS shutdown"
+        else
+          echo "launch.sh: WARNING could not make $id terminate on shutdown; its deadline will only stop it" >&2
+        fi
+      done
+      exit 0
+    fi
+    sleep 10
+  done
+  echo "launch.sh: WARNING no instance for $cluster after 15 min; its shutdown deadline will only stop it" >&2
+) &
+watcher=$!
+
+sky launch -c "$cluster" -i 15 --down -y "$task" --workdir "$stage" "$@" &
+launch=$!
+minutes=${MAX_MINUTES:-60}
+( sleep $((minutes * 60)); echo "launch.sh: past MAX_MINUTES=$minutes; deleting the machine" >&2; kill "$launch" ) &
+deadline=$!
+wait "$launch"

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/node-gpu.yaml

@@ -0,0 +1,25 @@
+# The machine the cloud backend (orchestrator/src/perception/backends/cloud.py) starts for one node, and deletes after it:
+# an L4 with 8 vCPUs, the face node's fastest measured setup (perception #4; frame decoding needs the cores). Only
+# set-up here: the driver checks the machine with guard.sh before sending anything, then runs the node over SSH.
+# Started with SKYPILOT_PROJECT_CONFIG=sky.yaml (no laptop credentials on the machine; only the perception-node role).
+resources:
+  cloud: aws
+  region: us-east-1
+  instance_type: g6.2xlarge
+  # on-demand: on 2026-10-23 us-east-1 had no L4 or A10G spot capacity, and the account's G spot quota is 0 elsewhere
+  use_spot: false
+  disk_size: 60
+
+envs:
+  DEADLINE_EPOCH: null   # required: the driver passes the node's deadline, as a moment (Unix seconds)
+
+setup: |
+  # SkyPilot runs setup detached (as a job: `sky launch` returns before it ends), so only what must come first is here:
+  # the machine shuts itself down (terminating: the driver sets that while it launches) at the deadline, even if the
+  # laptop that started it never comes back. guard.sh later sets it again, to what is left. What the node needs (ffmpeg,
+  # uv) the driver installs itself and waits for: node-setup.sh.
+  # Up to the moment, not a fixed delay: this runs detached, perhaps after guard.sh, and must not move the deadline later.
+  # Whole minutes left, rounded down; none (shut down now) once it has passed. (`shutdown HH:MM` would take a time
+  # already gone as tomorrow's.)
+  left=$(( (DEADLINE_EPOCH - $(date +%s)) / 60 )); [ "$left" -gt 0 ] || left=0
+  sudo shutdown -h "+$left"

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/node-setup.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# What a cloud node needs on its machine (AWS or RunPod), installed by the driver (remote_driver.py) over ssh after guard.sh
+# and before anything is sent, and waited for: SkyPilot runs a task's setup detached (as a job, `sky launch` returns
+# before it ends), so a node started after the launch could find ffmpeg half installed.
+#   bash -s < node-setup.sh        prints the uv it installed on its last line
+set -euo pipefail
+export DEBIAN_FRONTEND=noninteractive
+sudo=sudo; [ "$(id -u)" = 0 ] && sudo=   # a RunPod pod is root, with no sudo
+# a fresh Ubuntu machine runs its own updates at boot: wait for apt's lock rather than fail on it. rsync: the driver sends
+# with it (RunPod's image has none)
+if ! command -v ffmpeg > /dev/null || ! command -v ffprobe > /dev/null || ! command -v rsync > /dev/null; then   # an image may have them
+  $sudo apt-get -o DPkg::Lock::Timeout=600 update -qq
+  $sudo apt-get -o DPkg::Lock::Timeout=600 install -y -qq ffmpeg rsync > /dev/null
+fi
+# uv, the version the annotator app bundles, in a folder of its own (SkyPilot installs a uv of its own on the machine)
+dir="$HOME/.perception-uv"
+if [ ! -x "$dir/uv" ]; then
+  curl -LsSf https://astral.sh/uv/0.13.5/install.sh | env UV_INSTALL_DIR="$dir" UV_NO_MODIFY_PATH=1 sh > /dev/null
+fi
+"$dir/uv" --version | grep -q '^uv 0\.13\.5' || { echo "node-setup: $dir/uv is not uv 0.13.5" >&2; exit 1; }
+command -v ffmpeg > /dev/null && command -v ffprobe > /dev/null && command -v rsync > /dev/null
+echo "$dir/uv"

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/sky.yaml

@@ -0,0 +1,7 @@
+# SkyPilot project config for this repo's tasks; launch.sh points SKYPILOT_PROJECT_CONFIG here. A task YAML cannot set
+# this for AWS (SkyPilot only lets tasks override remote_identity on Kubernetes and Azure).
+aws:
+  # An instance profile that can only end perception-* machines (iam-perception-node.json). Naming one does two
+  # things: no laptop credentials are copied to the machine, and SkyPilot does not attach its default skypilot-v1
+  # role (EC2 and S3 full access), which it does even with NO_UPLOAD. guard.sh checks both on the machine.
+  remote_identity: perception-node

hyperstudy_perception-0.1.0/src/perception/_pipeline/cloud/skypilot/smoke.yaml

@@ -0,0 +1,28 @@
+# Smoke test of a cloud machine: install the orchestrator, run the decode graph on a synthetic video (ffmpeg test
+# pattern and tone, so no stimulus leaves the laptop), print timings, then the cluster is deleted.
+#   cloud/skypilot/launch.sh cloud/skypilot/smoke.yaml perception-smoke
+# --cpus/--gpus after the cluster name pick the machine; the defaults are the cheapest spot CPU machine.
+resources:
+  cloud: aws
+  region: us-east-1
+  cpus: 2+
+  use_spot: true
+
+setup: |
+  set -e
+  bash cloud/skypilot/guard.sh 45
+  sudo apt-get update -qq && sudo apt-get install -y -qq ffmpeg > /dev/null
+  command -v uv || curl -LsSf https://astral.sh/uv/install.sh | sh
+  export PATH=$HOME/.local/bin:$PATH
+  (cd orchestrator && uv sync -q) && (cd envs/core && uv sync -q)
+
+run: |
+  set -e
+  export PATH=$HOME/.local/bin:$PATH
+  nproc; free -g | head -2; nvidia-smi --query-gpu=name,memory.total --format=csv 2>/dev/null || echo "no GPU"
+  ffmpeg -v error -y -f lavfi -i testsrc2=size=1280x720:rate=30:duration=120 -f lavfi -i sine=frequency=440:duration=120 \
+    -c:v libx264 -pix_fmt yuv420p -c:a aac -shortest /tmp/synthetic.mp4
+  cd orchestrator
+  uv run perception doctor
+  time uv run perception run ../graphs/decode.yaml --input video=/tmp/synthetic.mp4
+  uv run perception status