RUN_LOCAL.md

# Run Endpoint Labeler Locally

Label trajectory success cutoffs on your machine. Same app as the HF Space, no org CPU limits.

## 1. Setup (one time)

```bash
cd /Users/kaushiksid/projs/rlplus/Labeler

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Use Python **3.11 or 3.12**. Avoid 3.13 — stdlib `audioop` was removed and breaks older Gradio builds.

## 2. Connect to HuggingFace data (optional)

**Public datasets** (e.g. `jesbu1/epic_rfm`) — no login needed.

**Gated or private datasets** — login once:

```bash
huggingface-cli login
# or: export HF_TOKEN=hf_...
```

The app reads `HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN` automatically.

## 3. Launch

```bash
source .venv/bin/activate
python app.py
```

Or:

```bash
./run_local.sh
```

Open **http://127.0.0.1:7860**

## 4. Load data in the UI

| Field | Example | Notes |
|-------|---------|-------|
| Dataset Repository | `jesbu1/epic_rfm` | Any HF dataset with `frames`, `is_robot`, `quality_label` |
| Config Name | `epic` | Leave empty if single-config dataset |
| Quality Filter | `Success` | Filter trajectories before sampling |
| Human / Robot Samples | `10` / `10` | How many trajectories to label |

Click **Load Dataset** → videos download to `video_cache/` (cached after first fetch).

## 5. Label workflow

1. Scrub frame slider to the **success / task-complete frame**
2. Enter **End Frame** (or read from slider position)
3. Click **Save Label** → appends to `labels.csv`
4. After labeling a full batch, click **Analyze Pattern** for suggested cutoff %

## Output

`labels.csv`:

```csv
dataset_repo,config_name,trajectory_id,is_robot,quality_label,task,manual_end_frame,manual_end_percent,notes
```

Copy suggested cutoff % into `reward_fm/rfm/data/dataset_success_cutoff.txt`:

```
dataset_short_name,0.95
```

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `ModuleNotFoundError: audioop` | Use Python 3.12 (not 3.13) |
| Videos won't load | Check dataset repo name; run `huggingface-cli login` for gated data |
| Empty sample list | Try Quality Filter = `All`, or increase sample counts |
| Slow first load | Normal — streaming + video download; cached after that |

## HF Spaces (if local isn't needed)

- Personal: https://huggingface.co/spaces/sksk99/endpoint-labeler
- Org: https://huggingface.co/spaces/robometer/endpoint-labeler

Both use this same repo. Space needs `python_version: 3.12` in README (already set).