poly-hammer-worker 0.1.0.dev5__tar.gz

poly_hammer_worker-0.1.0.dev5/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+scratches
+backend/reports
+.terraform
+terraform.tfvars
+.vite/
+secret.env
+__pycache__/

poly_hammer_worker-0.1.0.dev5/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: poly-hammer-worker
+Version: 0.1.0.dev5
+Summary: Poly Hammer self-hosted GPU worker agent
+License-Expression: MIT
+Requires-Python: >=3.13
+Requires-Dist: docker>=7.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: psutil>=5.9
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# ph-worker — Poly Hammer Self-Hosted GPU Worker
+
+A CLI agent that connects your GPU workstation to the Poly Hammer Portal, letting you run AI inference jobs on your own hardware instead of consuming cloud credits.
+
+## Requirements
+
+- **NVIDIA GPU** with CUDA drivers installed
+- **Docker** with [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) (`--gpus` support)
+- **Python 3.11+**
+- An active Poly Hammer Portal account with a registered worker key
+
+## Installation
+
+```bash
+cd workers/self-hosted/client
+uv sync
+```
+
+## Quick Start
+
+### 1. Check GPU compatibility
+
+```bash
+ph-worker check-gpu
+```
+
+This will display your GPU model, VRAM, CUDA version, CPU cores, and RAM.
+
+### 2. Register a worker in the Portal
+
+Navigate to the **Workers** page in the Poly Hammer Portal and click **Add Worker**. You'll receive a worker key (`ph_worker_...`) — save it, it's shown only once.
+
+### 3. Start the worker
+
+```bash
+ph-worker start --worker-key ph_worker_XXXXXXXX
+```
+
+Or use environment variables:
+
+```bash
+export PH_WORKER_KEY=ph_worker_XXXXXXXX
+export PH_PORTAL_URL=https://portal.polyhammer.com   # default
+ph-worker start
+```
+
+The worker will:
+
+1. Detect your GPU/CUDA capabilities
+2. Send heartbeats to the portal
+3. Long-poll for inference jobs
+4. Pull the correct Docker image (tagged by CUDA version) on first job
+5. Run inference in an isolated container with GPU access
+6. Upload results and report completion
+
+## How It Works
+
+```
+Portal API  ←→  ph-worker agent  ←→  Docker (GPU container)
+                    │                        │
+                    ├── heartbeat (60s)       ├── JSON stdin (job)
+                    ├── poll for jobs         ├── JSON stdout (progress)
+                    ├── report progress       └── S3 upload (result)
+                    └── report complete/fail
+```
+
+- **Images are pre-built** with model weights baked in — no download delays at inference time
+- **CUDA-versioned tags** (`cuda13.1`, etc.) ensure compatibility with your local drivers
+- **Dynamic pulling** — the worker automatically pulls the right image when it receives a job for a model it hasn't run before
+
+## Configuration
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `--worker-key` | `PH_WORKER_KEY` | (required) | Worker API key from the portal |
+| `--portal-url` | `PH_PORTAL_URL` | `https://portal.polyhammer.com` | Portal API base URL |
+
+## Docker Image Tags
+
+Worker images are published to GHCR with CUDA-versioned tags:
+
+| Image | Tag | Description |
+|-------|-----|-------------|
+| `ghcr.io/poly-hammer/hy-motion-worker` | `cuda13.1` | HY-Motion models (latest stable) |
+| `ghcr.io/poly-hammer/mdm-worker` | `cuda13.1` | MDM models (latest stable) |
+| | `cuda13.1-<sha>` | Pinned to a specific commit |
+| | `latest` | Latest build (any CUDA version) |
+
+## Troubleshooting
+
+### "No CUDA detected"
+
+- Ensure NVIDIA drivers are installed: `nvidia-smi`
+- The NVIDIA Container Toolkit must be installed for Docker GPU support
+
+### Container fails to start
+
+- Verify Docker GPU support: `docker run --rm --gpus all nvidia/cuda:13.1.0-base-ubuntu22.04 nvidia-smi`
+- Check Docker daemon is running: `docker info`
+
+### Worker shows OFFLINE in portal
+
+- Heartbeats are sent every 60 seconds; the portal marks workers offline after 120 seconds
+- Check network connectivity to the portal URL
+- Verify your worker key is correct
+
+## Development
+
+```bash
+cd workers/self-hosted/client
+uv sync --group dev
+```

poly_hammer_worker-0.1.0.dev5/README.md

@@ -0,0 +1,112 @@
+# ph-worker — Poly Hammer Self-Hosted GPU Worker
+
+A CLI agent that connects your GPU workstation to the Poly Hammer Portal, letting you run AI inference jobs on your own hardware instead of consuming cloud credits.
+
+## Requirements
+
+- **NVIDIA GPU** with CUDA drivers installed
+- **Docker** with [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) (`--gpus` support)
+- **Python 3.11+**
+- An active Poly Hammer Portal account with a registered worker key
+
+## Installation
+
+```bash
+cd workers/self-hosted/client
+uv sync
+```
+
+## Quick Start
+
+### 1. Check GPU compatibility
+
+```bash
+ph-worker check-gpu
+```
+
+This will display your GPU model, VRAM, CUDA version, CPU cores, and RAM.
+
+### 2. Register a worker in the Portal
+
+Navigate to the **Workers** page in the Poly Hammer Portal and click **Add Worker**. You'll receive a worker key (`ph_worker_...`) — save it, it's shown only once.
+
+### 3. Start the worker
+
+```bash
+ph-worker start --worker-key ph_worker_XXXXXXXX
+```
+
+Or use environment variables:
+
+```bash
+export PH_WORKER_KEY=ph_worker_XXXXXXXX
+export PH_PORTAL_URL=https://portal.polyhammer.com   # default
+ph-worker start
+```
+
+The worker will:
+
+1. Detect your GPU/CUDA capabilities
+2. Send heartbeats to the portal
+3. Long-poll for inference jobs
+4. Pull the correct Docker image (tagged by CUDA version) on first job
+5. Run inference in an isolated container with GPU access
+6. Upload results and report completion
+
+## How It Works
+
+```
+Portal API  ←→  ph-worker agent  ←→  Docker (GPU container)
+                    │                        │
+                    ├── heartbeat (60s)       ├── JSON stdin (job)
+                    ├── poll for jobs         ├── JSON stdout (progress)
+                    ├── report progress       └── S3 upload (result)
+                    └── report complete/fail
+```
+
+- **Images are pre-built** with model weights baked in — no download delays at inference time
+- **CUDA-versioned tags** (`cuda13.1`, etc.) ensure compatibility with your local drivers
+- **Dynamic pulling** — the worker automatically pulls the right image when it receives a job for a model it hasn't run before
+
+## Configuration
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `--worker-key` | `PH_WORKER_KEY` | (required) | Worker API key from the portal |
+| `--portal-url` | `PH_PORTAL_URL` | `https://portal.polyhammer.com` | Portal API base URL |
+
+## Docker Image Tags
+
+Worker images are published to GHCR with CUDA-versioned tags:
+
+| Image | Tag | Description |
+|-------|-----|-------------|
+| `ghcr.io/poly-hammer/hy-motion-worker` | `cuda13.1` | HY-Motion models (latest stable) |
+| `ghcr.io/poly-hammer/mdm-worker` | `cuda13.1` | MDM models (latest stable) |
+| | `cuda13.1-<sha>` | Pinned to a specific commit |
+| | `latest` | Latest build (any CUDA version) |
+
+## Troubleshooting
+
+### "No CUDA detected"
+
+- Ensure NVIDIA drivers are installed: `nvidia-smi`
+- The NVIDIA Container Toolkit must be installed for Docker GPU support
+
+### Container fails to start
+
+- Verify Docker GPU support: `docker run --rm --gpus all nvidia/cuda:13.1.0-base-ubuntu22.04 nvidia-smi`
+- Check Docker daemon is running: `docker info`
+
+### Worker shows OFFLINE in portal
+
+- Heartbeats are sent every 60 seconds; the portal marks workers offline after 120 seconds
+- Check network connectivity to the portal URL
+- Verify your worker key is correct
+
+## Development
+
+```bash
+cd workers/self-hosted/client
+uv sync --group dev
+```

poly_hammer_worker-0.1.0.dev5/poly_hammer_worker/__init__.py

@@ -0,0 +1 @@
+"""Poly Hammer self-hosted GPU worker agent."""

poly_hammer_worker-0.1.0.dev5/poly_hammer_worker/api_client.py

@@ -0,0 +1,113 @@
+"""
+HTTP client for the Poly Hammer Portal worker API.
+
+All requests authenticate via the X-Worker-Key header.
+"""
+
+import logging
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Endpoints (relative to portal base URL)
+_POLL_PATH = "/api/v1/worker-jobs/poll"
+_COMPLETE_PATH = "/api/v1/worker-jobs/{job_id}/complete"
+_FAIL_PATH = "/api/v1/worker-jobs/{job_id}/fail"
+_PROGRESS_PATH = "/api/v1/worker-jobs/{job_id}/progress"
+_HEARTBEAT_PATH = "/api/v1/worker-jobs/heartbeat"
+
+
+class PortalClient:
+    """Thin HTTP wrapper around the worker-jobs API."""
+
+    def __init__(self, portal_url: str, worker_key: str) -> None:
+        self.base_url = portal_url.rstrip("/")
+        self._headers = {"X-Worker-Key": worker_key}
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=self._headers,
+            timeout=httpx.Timeout(connect=10.0, read=60.0, write=30.0, pool=10.0),
+        )
+
+    def poll_for_job(self) -> dict | None:
+        """Long-poll for a pending job. Returns job payload or None."""
+        try:
+            resp = self._client.get(_POLL_PATH)
+            if resp.status_code == 204 or resp.status_code == 200 and not resp.text:
+                return None
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.TimeoutException:
+            # Normal — server held connection for poll timeout with no job
+            return None
+        except httpx.HTTPStatusError as e:
+            logger.error("Poll failed: %s %s", e.response.status_code, e.response.text)
+            raise
+
+    def complete_job(
+        self,
+        job_id: str,
+        elapsed_seconds: float,
+        result_url: str | None = None,
+        result_metadata: dict | None = None,
+    ) -> None:
+        """Report job completion."""
+        body: dict[str, Any] = {"elapsed_seconds": elapsed_seconds}
+        if result_url:
+            body["result_url"] = result_url
+        if result_metadata:
+            body["result_metadata"] = result_metadata
+
+        resp = self._client.post(
+            _COMPLETE_PATH.format(job_id=job_id),
+            json=body,
+        )
+        resp.raise_for_status()
+
+    def fail_job(
+        self,
+        job_id: str,
+        error_message: str,
+        error_code: str = "INFERENCE_FAILED",
+    ) -> None:
+        """Report job failure."""
+        resp = self._client.post(
+            _FAIL_PATH.format(job_id=job_id),
+            json={"error_message": error_message, "error_code": error_code},
+        )
+        resp.raise_for_status()
+
+    def report_progress(self, job_id: str, progress: float) -> None:
+        """Send a progress update (0.0–1.0)."""
+        try:
+            resp = self._client.post(
+                _PROGRESS_PATH.format(job_id=job_id),
+                json={"progress": progress},
+            )
+            resp.raise_for_status()
+        except httpx.HTTPError:
+            # Progress updates are best-effort
+            logger.debug("Progress report failed (non-fatal)")
+
+    def heartbeat(
+        self,
+        supported_models: list[str] | None = None,
+        hardware_info: dict | None = None,
+    ) -> None:
+        """Send a heartbeat to keep the worker marked ONLINE."""
+        body: dict[str, Any] = {}
+        if supported_models is not None:
+            body["supported_models"] = supported_models
+        if hardware_info is not None:
+            body["hardware_info"] = hardware_info
+
+        try:
+            resp = self._client.post(_HEARTBEAT_PATH, json=body)
+            resp.raise_for_status()
+        except httpx.HTTPError:
+            logger.warning("Heartbeat failed (will retry)")
+
+    def close(self) -> None:
+        self._client.close()

poly_hammer_worker-0.1.0.dev5/poly_hammer_worker/cli.py

@@ -0,0 +1,123 @@
+"""
+ph-worker CLI — Poly Hammer self-hosted GPU worker agent.
+
+Usage:
+    ph-worker start --worker-key <key> --portal-url <url>
+    ph-worker check-gpu
+"""
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+app = typer.Typer(help="Poly Hammer self-hosted GPU worker agent.")
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        from importlib.metadata import version
+
+        typer.echo(f"ph-worker {version('ph-worker')}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+) -> None:
+    pass
+
+
+@app.command()
+def start(
+    worker_key: Annotated[
+        str,
+        typer.Option(
+            envvar="PH_WORKER_KEY",
+            help="Worker API key (ph_worker_...). Can also be set via PH_WORKER_KEY env var.",
+        ),
+    ],
+    portal_url: Annotated[
+        str,
+        typer.Option(
+            envvar="PH_PORTAL_URL",
+            help="Poly Hammer Portal API base URL.",
+        ),
+    ] = "https://portal.polyhammer.com",
+    auto_cleanup: Annotated[
+        bool,
+        typer.Option(
+            "--auto-cleanup",
+            envvar="PH_AUTO_CLEANUP",
+            help="Automatically remove old worker images when disk space is low.",
+        ),
+    ] = False,
+    registry: Annotated[
+        str | None,
+        typer.Option(
+            envvar="PH_REGISTRY_URL",
+            help="Optional container registry URL to pull images from if not found locally.",
+        ),
+    ] = None,
+) -> None:
+    """Start the worker agent loop.
+
+    The worker will:
+    1. Detect local GPU/CUDA capabilities
+    2. Connect to the portal and send heartbeats
+    3. Long-poll for inference jobs
+    4. Use locally-built Docker images (or pull from --registry if set)
+    5. Run inference and upload results
+    """
+    from poly_hammer_worker.worker_loop import run_worker_loop
+
+    run_worker_loop(
+        worker_key=worker_key,
+        portal_url=portal_url,
+        auto_cleanup=auto_cleanup,
+        registry_url=registry,
+        console=console,
+    )
+
+
+@app.command()
+def check_gpu() -> None:
+    """Detect and display local GPU/CUDA capabilities."""
+    from poly_hammer_worker.hardware import detect_hardware
+
+    info = detect_hardware()
+
+    console.print("\n[bold]GPU / Hardware Info[/bold]\n")
+    console.print(f"  GPU Model:      {info.get('gpu_model', 'N/A')}")
+    console.print(f"  VRAM:           {info.get('vram_gb', 'N/A')} GB")
+    console.print(f"  CUDA Version:   {info.get('cuda_version', 'N/A')}")
+    console.print(f"  CPU Cores:      {info.get('cpu_cores', 'N/A')}")
+    console.print(f"  RAM:            {info.get('ram_gb', 'N/A')} GB")
+    console.print(f"  Disk Free:      {info.get('disk_free_gb', 'N/A')} GB")
+
+    cuda_version = info.get("cuda_version")
+    if cuda_version:
+        console.print(
+            f"\n  [green]CUDA {cuda_version} detected — ready for self-hosted workers[/green]"
+        )
+    else:
+        console.print(
+            "\n  [red]No CUDA detected — self-hosted workers require an NVIDIA GPU[/red]"
+        )
+
+    console.print()
+
+
+if __name__ == "__main__":
+    app()