ocr(docs): surya venv version depends on serve mode (0.17 local / >=0.20 vllm)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mw2KQiswmD69T45fTfjKwW

docs/ocr.md

@@ -47,6 +47,23 @@ python3 -m venv ~/.coderai/paddle_venv
 python3 -m venv ~/.coderai/surya_venv
 ~/.coderai/surya_venv/bin/pip install -r requirements-surya.txt
 ```
+
+### Surya serving modes (`ocr.surya_serve`) — IMPORTANT: the venv version depends on the mode
+
+Surya changed architecture across versions, so the surya venv must hold the version that
+matches the chosen serving mode:
+
+| `surya_serve` | What it is | surya‑ocr version | How it runs |
+|---|---|---|---|
+| `local` (default) | classic detection + recognition on torch | **≤ 0.17.1** (`requirements-surya.txt` pins 0.17.1) | in the isolated venv, GPU |
+| `vllm` | the latest **"Surya2"** VLM (Qwen3.5‑VL, `datalab-to/surya-ocr-2`) | **≥ 0.20** (e.g. 0.22.1) | served by coderai's **vLLM backend**; Surya attaches via `SURYA_INFERENCE_URL` |
+| `llamacpp` | same Surya2 VLM | ≥ 0.20 | attaches to a `llama-server` at `ocr.surya_server_url` |
+
+Surya2 (≥0.20) is a VLM that CANNOT run standalone in the venv — it requires an external
+OpenAI server (vLLM/llama‑server). `vllm` mode is recommended: coderai serves
+`ocr.surya_model` through the vLLM backend (continuous batching) and points Surya at it.
+So: install **surya‑ocr 0.17.1** for `local`, or **surya‑ocr>=0.20** for `vllm`/`llamacpp` —
+one per venv.
 Or set `paddle_auto_build` / `surya_auto_build` to have coderai create the venv and install
 on first use. In the OCI image these venvs are **baked in** at `/opt/coderai/paddle_venv` /
 `/opt/coderai/surya_venv` (same as the `lipsync_venv` / `parler-venv`), so the image is

requirements-surya.txt

@@ -21,3 +21,7 @@
 # det+recognition locally on torch (GPU), so it's the classic pin. See docs/ocr.md.
 surya-ocr==0.17.1
 pypdfium2>=4.20.0
+# NOTE: 0.17.1 is for ocr.surya_serve="local" (classic det+recognition on torch, runs in
+# THIS venv). For ocr.surya_serve="vllm"/"llamacpp" (the latest "Surya2" VLM, Qwen3.5-VL
+# `datalab-to/surya-ocr-2`), install surya-ocr>=0.20 instead (e.g. 0.22.1) — it needs an
+# external vLLM/llama-server backend, not local torch. One version per venv; see docs/ocr.md.