# Lens-Turbo CLI

Two scripts:

- `lens_turbo_cli.py` — single prompt, Pattern A (prompt + args)
- `lens_turbo_batch.py` — batch from JSON, Pattern C (resume + skip + retry)

## Single-shot

```bash
# Mac client (install once):
uv pip install --system websocket-client

# Run:
python lens_turbo_cli.py \
  "a photorealistic photo of an astronaut riding a horse on Mars" \
  --ip 10.8.0.12 --gpu 0 \
  --steps 4 --cfg 1.0 --seed 42 \
  --out ./out
```

## Batch

Input JSON — `list` of objects with `word` + `prompt`:

```json
[
  {"word": "apple",  "prompt": "a fresh red apple, studio light, 4k"},
  {"word": "sunset", "prompt": "warm sunset over the ocean, cinematic"}
]
```

Run:

```bash
python lens_turbo_batch.py cli/example_vocab.json \
  --ip 10.8.0.12 --gpu 0 \
  --out-dir ./vocab_images
```

Output → `<out-dir>/<word>.png`. Filenames are sanitized (CJK preserved,
spaces/punctuation → `_`). Re-runs skip existing files; `--force` to
overwrite.

Other JSON layouts auto-detected: `{entries: [...]}` / `{data: [...]}` /
`{items: [...]}`.

### Useful batch flags

| Flag | Default | Notes |
|---|---|---|
| `--limit N` | none | dry-run first N entries |
| `--seed N` | random | fix for reproducibility |
| `--force` | off | overwrite existing files |
| `--retry N` | 2 | per-image retry attempts |
| `--base-resolution` | 1024 | bump to 1440 for higher quality |
| `--aspect-ratio` | 1:1 | one of 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 9:21 |
| `--prompt-key` / `--word-key` | `prompt` / `word` | rename if your JSON uses different fields |
| `--timeout` | 900 | per-image wall-clock cap |
| `--ws-recv-timeout` | 1200 | WS idle timeout — first image after cold-load is slow |

### First-run cold load

The FIRST image in the batch triggers `LensPipeline.from_pretrained`
server-side. Expect ~120 s for that one. Subsequent images use the
cached pipeline and take ~12 s each (1024² @ 4 steps, `cpu_text_encoder`
mode on a single RTX 3090).

## Variants

| Model | `--repo-id` | `--steps` | `--cfg` |
|---|---|---|---|
| Lens-Turbo (default) | `microsoft/Lens-Turbo` | 4 | 1.0 |
| Lens (RL-tuned) | `microsoft/Lens` | 20 | 5.0 |
| Lens-Base (no RL) | `microsoft/Lens-Base` | 50 | 5.0 |

## Debugging

```bash
# Dump the workflow JSON so you can load it in the ComfyUI web UI:
python lens_turbo_cli.py "..." --dump-workflow /mnt/modelall/tmp/wf.json

# Then on the server:
tail -f /mnt/modelall/tmp/comfy.log | grep -E 'lens-turbo|LensTurbo|OutOfMemory'
```

## Force a reload (after upgrading lens_source/)

```bash
python lens_turbo_cli.py "..." --force-reload
```

## VRAM modes

```bash
# 24 GB RTX 3090 — default, hybrid CPU/GPU placement
python lens_turbo_cli.py "..."

# 48 GB+ card — skip offload for ~2-3× speedup
python lens_turbo_cli.py "..." --offload-mode none
```