poly-hammer-worker 0.1.1.dev12__tar.gz → 0.3.0__tar.gz

poly_hammer_worker-0.3.0/.dockerignore

@@ -0,0 +1,35 @@
+# Dependencies
+node_modules
+**/node_modules
+frontend/node_modules
+
+# Build outputs
+dist
+**/dist
+frontend/dist
+
+# Python
+__pycache__
+*.pyc
+.venv
+backend/.venv
+
+# Git
+.git
+.gitignore
+
+# IDE
+.vscode
+.idea
+
+# Test artifacts
+htmlcov
+.coverage
+.pytest_cache
+playwright-report
+test-results
+
+# Misc
+*.log
+.DS_Store
+Thumbs.db

{poly_hammer_worker-0.1.1.dev12 → poly_hammer_worker-0.3.0}/.gitignore

@@ -6,7 +6,9 @@ node_modules/
 scratches
 backend/reports
 .terraform
+.terraform-*
 terraform.tfvars
 .vite/
 secret.env
 __pycache__/
+.hatchet/

poly_hammer_worker-0.3.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: poly-hammer-worker
+Version: 0.3.0
+Summary: Poly Hammer self-hosted GPU worker — runs AI inference inside Docker
+License-Expression: MIT
+Requires-Python: <4,>=3.10
+Requires-Dist: hatchet-sdk>=1.32.0
+Requires-Dist: hf-transfer>=0.1.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: huggingface-hub<1.0,>=0.30.0
+Requires-Dist: modal>=1.3.2
+Requires-Dist: psutil>=5.9
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12

poly_hammer_worker-0.3.0/README.md

@@ -0,0 +1,82 @@
+# Self-Hosted Worker Images
+
+Docker images for running Poly Hammer AI inference workers on your own hardware.
+Model weights are volume-mounted at runtime via named Docker volumes.
+
+## Quick Start
+
+```bash
+# From workers/self-hosted/:
+docker compose build
+
+# Or build a single image:
+docker compose build hy-motion
+docker compose build hello-motion
+```
+
+This produces locally-tagged images:
+
+| Service | Image Tag | GPU Required |
+|---------|-----------|-------------|
+| HY-Motion | `ph-hy-motion:latest` | Yes |
+| Hello Motion | `ph-hello-motion:latest` | No |
+
+## Hardware Requirements
+
+### HY-Motion (`ph-hy-motion`)
+
+| Resource | Minimum |
+|----------|---------|
+| GPU VRAM | 24 GB (Lite model) / 40 GB (full model) |
+| System RAM | 16–32 GB |
+| Disk (image) | ~40 GB |
+| Disk (build) | ~80 GB (temporary build layers) |
+
+### Hello Motion (`ph-hello-motion`)
+
+No GPU required. Uses a bundled motion.npz fixture to simulate the full
+inference pipeline. Useful for end-to-end testing of the worker system.
+
+## License Notices
+
+**You must review and accept the following licenses before building these images.**
+
+### HY-Motion (`ph-hy-motion`)
+
+- **Tencent Hunyuan Community License**: The HY-Motion model weights are released by Tencent under the [Tencent Hunyuan Community License Agreement](https://github.com/Tencent/HunyuanVideo/blob/main/LICENSE.txt). This license includes territory restrictions and usage conditions. Review it carefully.
+- **CLIP (OpenAI)**: The CLIP text encoder is released under the [MIT License](https://github.com/openai/CLIP/blob/main/LICENSE).
+- **Qwen3 (Alibaba)**: The Qwen3 text encoder is released under the [Apache 2.0 License](https://huggingface.co/Qwen/Qwen3-8B/blob/main/LICENSE).
+
+## Downloading Weights
+
+Weights are not baked into the image — download them once into a named volume:
+
+```bash
+docker volume create hy-motion-weights
+
+# Allocate a TTY (-it) so the live progress panel renders:
+docker run --rm -it --gpus all \
+    -v hy-motion-weights:/weights \
+    ph-hy-motion download-weights --job hy-motion --all
+```
+
+Expect roughly **50 GB** for `--all` and 20–60 minutes on a typical
+residential connection (`hf-transfer` is enabled by default).
+
+### Helpful flags
+
+| Flag | Purpose |
+|------|---------|
+| `--hf-token <token>` | Authenticate with HuggingFace. Lifts anonymous rate limits and unlocks gated repos. Also reads `HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN` env vars. |
+| `--no-progress` | Disable the live panel (use under `docker run -d` or in CI where there is no TTY). |
+| `--dry-run` | Print the download plan and exit without contacting HuggingFace. |
+| `--retries N` | Retry attempts per step on transient failures (default: 3, exponential backoff). |
+| `-v` / `--verbose` | Enable DEBUG logging from `ph-worker` and `huggingface_hub`. |
+| `-q` / `--quiet` | Suppress INFO logs; only show warnings, errors, and the progress panel. |
+
+### Why doesn't it look like anything is happening?
+
+If you ran `docker run` without `-t` (no TTY), Rich's live panel can't draw
+and you'll only see the periodic INFO log lines from `huggingface_hub`
+(e.g. `Fetching N files`). Pass `-it` for the panel, or `--no-progress` to
+opt into log-only mode.

poly_hammer_worker-0.3.0/compose.yml

@@ -0,0 +1,72 @@
+# =============================================================================
+# Self-Hosted Worker Images — Local Build
+#
+# Each image IS a Hatchet worker. Run directly:
+#   docker run --gpus all ph-hy-motion start --token <WORKER_TOKEN>
+#
+# Build all images (from workers/self-hosted/):
+#   docker compose build
+#
+# Build a single image:
+#   docker compose --env-file secret.env build hy-motion
+#   docker compose build ph-hello-motion
+#
+# Build a specific CUDA variant:
+#   docker compose build hy-motion-cu121
+#
+# See README.md for license notices and hardware requirements.
+# =============================================================================
+
+services:
+  # ---------------------------------------------------------------------------
+  # HY-Motion — Default (cu128 / CUDA 13.1 — Blackwell, Hopper, Ampere)
+  # ---------------------------------------------------------------------------
+  hy-motion:
+    image: ghcr.io/poly-hammer/ph-hy-motion:latest
+    build:
+      context: .
+      dockerfile: poly_hammer_worker/jobs/hy_motion/Dockerfile
+    volumes:
+      - hy-motion-weights:/weights
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+
+  # ---------------------------------------------------------------------------
+  # HY-Motion — cu121 (CUDA 12.1 — RTX 20xx+, driver ≥530)
+  # ---------------------------------------------------------------------------
+  hy-motion-cu121:
+    image: ghcr.io/poly-hammer/ph-hy-motion:cu121
+    build:
+      context: .
+      dockerfile: poly_hammer_worker/jobs/hy_motion/Dockerfile
+      args:
+        CUDA_TAG: 12.1.1-cudnn8-devel-ubuntu22.04
+        TORCH_INDEX_URL: https://download.pytorch.org/whl/cu121
+        TORCH_VERSION: "2.6.0"
+        TORCHVISION_VERSION: "0.21.0"
+    volumes:
+      - hy-motion-weights:/weights
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+
+  # ---------------------------------------------------------------------------
+  # Hello Motion — Debug Image (no GPU)
+  # ---------------------------------------------------------------------------
+  ph-hello-motion:
+    image: ghcr.io/poly-hammer/ph-hello-motion:latest
+    build:
+      context: .
+      dockerfile: poly_hammer_worker/jobs/hello_motion/Dockerfile
+
+volumes:
+  hy-motion-weights:

poly_hammer_worker-0.3.0/docs/index.md

@@ -0,0 +1,320 @@
+# Self-Hosted Worker Setup Guide
+
+Run Poly Hammer AI inference on your own GPU hardware. This guide covers
+installing Docker, setting up NVIDIA GPU support, choosing the right image
+for your hardware, and running your first worker.
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum |
+|-------------|---------|
+| NVIDIA GPU | RTX 2060 or newer (Turing, Ampere, Ada Lovelace, Hopper, Blackwell) |
+| GPU VRAM | 24 GB (Lite model) / 40 GB (Full model) |
+| System RAM | 16 GB (Lite) / 32 GB (Full) |
+| Disk space | ~40 GB for the image + ~30 GB for model weights |
+| Docker | 24.0+ with NVIDIA Container Toolkit |
+
+---
+
+## 1. Install Docker
+
+### Linux (Ubuntu / Debian)
+
+```bash
+# Install Docker Engine
+curl -fsSL https://get.docker.com | sh
+
+# Add your user to the docker group (log out and back in after)
+sudo usermod -aG docker $USER
+```
+
+### Windows
+
+1. Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/)
+2. Enable **WSL 2 backend** during setup (required for GPU passthrough)
+3. In Docker Desktop settings, ensure **"Use the WSL 2 based engine"** is checked
+
+> **Note:** GPU passthrough on Windows requires WSL 2 with an Ubuntu distribution.
+> All Docker commands below should be run inside your WSL 2 terminal, not PowerShell.
+
+---
+
+## 2. Install NVIDIA GPU Support
+
+### Linux
+
+Install the NVIDIA driver and the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html),
+which lets Docker containers access your GPU:
+
+```bash
+# 1. Install the latest NVIDIA driver (if not already installed)
+sudo apt-get update
+sudo apt-get install -y nvidia-driver-570
+
+# 2. Add the NVIDIA Container Toolkit repository
+curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
+  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
+curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
+  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
+  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
+
+# 3. Install the toolkit
+sudo apt-get update
+sudo apt-get install -y nvidia-container-toolkit
+
+# 4. Configure Docker to use the NVIDIA runtime
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+### Windows (WSL 2)
+
+GPU support in WSL 2 is provided automatically by the Windows NVIDIA driver —
+you do **not** install a separate Linux driver inside WSL.
+
+1. Install the latest [NVIDIA Game Ready or Studio driver](https://www.nvidia.com/Download/index.aspx) on Windows
+2. Open your WSL 2 Ubuntu terminal and install the Container Toolkit:
+
+```bash
+# Inside WSL 2 Ubuntu
+curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
+  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
+curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
+  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
+  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
+sudo apt-get update
+sudo apt-get install -y nvidia-container-toolkit
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+### Verify GPU Access
+
+Run this to confirm Docker can see your GPU:
+
+```bash
+docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi
+```
+
+You should see your GPU name, driver version, and CUDA version in the output.
+
+---
+
+## 3. Choose Your CUDA Variant
+
+Worker images are published in two CUDA variants. Pick the one that matches
+your GPU generation and driver version:
+
+| Tag | CUDA | PyTorch | Base Image | Best For | Min Driver |
+|-----|------|---------|------------|----------|------------|
+| `:latest` | 13.1 (cu128) | 2.10.0 | `nvidia/cuda:13.1.1-cudnn-devel-ubuntu24.04` | RTX 50xx (Blackwell), H100, A100, RTX 30xx/40xx | 570+ |
+| `:cu121` | 12.1 (cu121) | 2.6.0 | `nvidia/cuda:12.1.1-cudnn-devel-ubuntu22.04` | RTX 20xx (Turing), RTX 30xx, GTX 16xx | 530+ |
+
+**How to check your driver version:**
+
+```bash
+nvidia-smi
+# Look for "Driver Version: XXX.XX" in the top-right of the table
+```
+
+**How to choose:**
+
+- If your driver is **570+** (most current systems), use `:latest` — it supports all GPUs from Ampere onward and adds native Blackwell sm_120 support.
+- If your driver is **530–569** or you have a **Turing-era GPU** (RTX 2060–2080, GTX 1660), use `:cu121`.
+- When in doubt, use `:cu121` — it has the widest hardware compatibility.
+
+---
+
+## 4. Authenticate with the Registry
+
+Worker images are hosted on GitHub Container Registry (GHCR) and require
+authentication. You need a **GitHub account** that has been granted access
+to the `poly-hammer` organization's packages.
+
+```bash
+# Log in to GHCR (use a GitHub Personal Access Token with read:packages scope)
+echo $GITHUB_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
+```
+
+---
+
+## 5. Pull the Image
+
+```bash
+# Default variant (cu128 — CUDA 13.1)
+docker pull ghcr.io/poly-hammer/ph-hy-motion:latest
+
+# Or the cu121 variant for older GPUs / drivers
+docker pull ghcr.io/poly-hammer/ph-hy-motion:cu121
+```
+
+---
+
+## 6. Download Model Weights
+
+Weights are stored in a named Docker volume so they persist across container
+restarts and image upgrades. You only need to download them once.
+
+```bash
+# Create a named volume
+docker volume create hy-motion-weights
+
+# Download all model weights (~30 GB, one-time)
+docker run --rm --gpus all \
+  -v hy-motion-weights:/weights \
+  ghcr.io/poly-hammer/ph-hy-motion:latest \
+  download-weights --job hy-motion --all
+```
+
+Replace `:latest` with `:cu121` if you chose the cu121 variant.
+
+> **Tip:** You can also download a single model variant:
+>
+> ```bash
+> docker run --rm --gpus all \
+>   -v hy-motion-weights:/weights \
+>   ghcr.io/poly-hammer/ph-hy-motion:latest \
+>   download-weights --job hy-motion --model hy-motion-1.0-lite
+> ```
+
+---
+
+## 7. Start the Worker
+
+You need a **worker registration token** from the Poly Hammer Portal.
+Go to **Credentials > Tokens > Add Token** and select the
+**Worker Registration** type.
+
+```bash
+docker run -d --gpus all \
+  --restart unless-stopped \
+  --name ph-worker \
+  -v hy-motion-weights:/weights \
+  ghcr.io/poly-hammer/ph-hy-motion:latest \
+  start --token YOUR_WORKER_TOKEN
+```
+
+The worker will:
+
+1. Register with the portal and receive Hatchet credentials
+2. Detect your GPU hardware
+3. Connect to the task orchestrator
+4. Begin accepting inference jobs
+
+### Custom Worker Name
+
+By default the worker identifies itself as `{hostname}/{container_name}`.
+Override it with `--name`:
+
+```bash
+docker run -d --gpus all \
+  --restart unless-stopped \
+  --name ph-worker \
+  -v hy-motion-weights:/weights \
+  ghcr.io/poly-hammer/ph-hy-motion:latest \
+  start --token YOUR_WORKER_TOKEN --name "my-workstation"
+```
+
+---
+
+## 8. Verify the Worker
+
+### Check GPU Detection
+
+```bash
+docker run --rm --gpus all ghcr.io/poly-hammer/ph-hy-motion:latest check-gpu
+```
+
+Expected output:
+
+```
+GPU detected
+  Model:  NVIDIA GeForce RTX 4090
+  VRAM:   24.0 GB
+  CUDA:   13.1
+  CPU:    16 cores
+  RAM:    64.0 GB
+```
+
+### Check Worker Logs
+
+```bash
+docker logs -f ph-worker
+```
+
+### Portal Status
+
+Once connected, your worker will appear on the **Workers** page in the
+portal with an **Active** status badge.
+
+---
+
+## Updating the Worker
+
+When a new image version is published, pull and recreate:
+
+```bash
+docker pull ghcr.io/poly-hammer/ph-hy-motion:latest
+docker stop ph-worker && docker rm ph-worker
+
+# Re-run with the same volume — no need to re-download weights
+docker run -d --gpus all \
+  --restart unless-stopped \
+  --name ph-worker \
+  -v hy-motion-weights:/weights \
+  ghcr.io/poly-hammer/ph-hy-motion:latest \
+  start --token YOUR_WORKER_TOKEN
+```
+
+---
+
+## Troubleshooting
+
+### "No GPU detected"
+
+- **Linux:** Make sure the NVIDIA Container Toolkit is installed and Docker is
+  restarted. Run `nvidia-smi` on the host to verify drivers are loaded.
+- **Windows/WSL 2:** Make sure you're running Docker commands from inside WSL 2
+  (not PowerShell). Confirm the Windows NVIDIA driver is installed.
+- **Both:** Ensure you're passing `--gpus all` to `docker run`.
+
+### "Permission denied" pulling from GHCR
+
+- Log in with `docker login ghcr.io` using a PAT that has `read:packages` scope.
+- Confirm your GitHub account has access to the `poly-hammer` org.
+
+### Worker shows "Inactive" in the portal
+
+- The worker heartbeat is stale (>5 seconds since last ping). Check
+  `docker logs ph-worker` for connection errors.
+- Verify your network allows outbound traffic to the portal and Hatchet gRPC
+  endpoint.
+
+### Out of VRAM errors
+
+- The full **HY-Motion 1.0** model requires **40 GB VRAM** (A100, A6000).
+- The **HY-Motion 1.0 Lite** model requires **24 GB VRAM** (RTX 3090, RTX 4090).
+- If your GPU has less than 24 GB, it cannot run either model.
+
+### Wrong CUDA variant
+
+If you see CUDA errors at runtime, you may have the wrong image variant for
+your driver version. Check with `nvidia-smi` and pick the appropriate tag
+(`:latest` for driver 570+, `:cu121` for driver 530+).
+
+---
+
+## Hardware Compatibility Reference
+
+| GPU Family | Architecture | Example GPUs | Recommended Tag | Min Driver |
+|------------|-------------|--------------|-----------------|------------|
+| RTX 50xx | Blackwell | RTX 5090, RTX 5080 | `:latest` | 570+ |
+| RTX 40xx | Ada Lovelace | RTX 4090, RTX 4080, RTX 4070 Ti | `:latest` or `:cu121` | 530+ |
+| RTX 30xx | Ampere | RTX 3090, RTX 3080, A100, A6000 | `:latest` or `:cu121` | 530+ |
+| RTX 20xx | Turing | RTX 2080 Ti, RTX 2070 | `:cu121` | 530+ |
+| GTX 16xx | Turing | GTX 1660 Ti, GTX 1660 Super | `:cu121` | 530+ |
+| Data Center | Hopper | H100, H200 | `:latest` | 530+ |
+
+> **Note:** GTX 10xx (Pascal) and older GPUs are not supported.

poly_hammer_worker-0.3.0/poly_hammer_worker/__init__.py

@@ -0,0 +1 @@
+"""Poly Hammer self-hosted GPU worker — Docker-native Hatchet worker agent."""

poly_hammer_worker-0.3.0/poly_hammer_worker/api_client.py

@@ -0,0 +1,70 @@
+"""
+HTTP client for the Poly Hammer Portal worker API.
+
+Used during worker startup to exchange a portal worker-registration token
+for Hatchet credentials via ``POST /v1/workers/register``.
+"""
+
+import logging
+from dataclasses import dataclass
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class RegistrationResult:
+    """Credentials returned by the portal registration endpoint."""
+
+    hatchet_token: str
+    grpc_host: str
+    tls_strategy: str
+    user_id: str
+    portal_token_id: str
+
+
+class PortalClient:
+    """Thin HTTP client for the portal worker registration API."""
+
+    def __init__(self, portal_url: str, worker_token: str) -> None:
+        self._base_url = portal_url.rstrip("/")
+        self._token = worker_token
+
+    def register(self) -> RegistrationResult:
+        """Exchange the worker-registration token for Hatchet credentials.
+
+        Calls ``POST /v1/workers/register`` with the portal token and
+        returns the Hatchet JWT, gRPC host, TLS strategy, and user ID.
+        """
+        url = f"{self._base_url}/v1/workers/register"
+        headers = {"Authorization": f"Bearer {self._token}"}
+
+        resp = httpx.post(url, headers=headers, timeout=15)
+
+        if resp.status_code == 401:
+            raise SystemExit(
+                "Authentication failed. Check that your --token is a valid "
+                "WORKER_REGISTRATION token from the portal."
+            )
+        if resp.status_code == 503:
+            raise SystemExit(
+                "Hatchet is not configured on this portal instance. "
+                "Contact the portal administrator."
+            )
+        resp.raise_for_status()
+
+        data = resp.json()
+        result = RegistrationResult(
+            hatchet_token=data["hatchet_token"],
+            grpc_host=data["grpc_host"],
+            tls_strategy=data["tls_strategy"],
+            user_id=data["user_id"],
+            portal_token_id=data["portal_token_id"],
+        )
+        logger.info(
+            "Registered with portal (user=%s, grpc=%s)",
+            result.user_id,
+            result.grpc_host,
+        )
+        return result