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
```
