The Surya-2 engine serves its VLM via a managed vLLM subprocess
(vllm_worker.ensure_service). That subprocess is not a manager-tracked
model, and the OCR VRAM releaser only tore down the lightweight worker
pools (killing the HTTP workers) — it never stopped the vLLM holding the
bulk VRAM (gpu_memory_utilization × card). So on-request eviction saw the
VRAM as used, found nothing it could free, and (with no CPU fallback) a
docTR/Paddle load on the same card could OOM.

- vllm_worker: add stop_service_for(cfg, model_path, served_name) (stop ONE
  service, return estimated GB freed) + is_running() helper.
- OcrManager._release_vram now also stops the managed Surya-2 vLLM
  (_stop_surya_vllm) when surya_serve == "vllm", so the registered external
  releaser actually reclaims its VRAM. Next OCR request re-boots it via
  ensure_service. Targeted by (model_path, served_name) so an LLM vLLM
  instance is left alone.

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

OCR ran outside the shared GPU governors: /v1/ocr(/batch) and run_ocr_step
call OcrManager.ocr_document directly, bypassing request_model, so OCR
neither waited on thermal cooldown nor evicted/released VRAM against
LLM/diffusion models.

- thermal: ocr_document now awaits thermal.wait_until_safe (via to_thread)
  before OCR-ing pages, so OCR honours the same cooldown/front-pause gate as
  every other GPU workload.
- VRAM (both directions):
  * evict-before-build: when a pool loads its instances, ask the model
    manager to free size*per-instance-VRAM first (_evict_models_for_vram),
    so OCR contends on equal footing instead of OOMing.
  * releaser: OcrManager registers _release_vram(needed_gb) via
    register_external_vram_releaser, tearing down built pools so loading an
    LLM/diffusion model can reclaim OCR VRAM. Pools rebuild lazily next request.
- engine cleanup() (SYNC, eviction-thread safe) + vram_gb() footprint per
  engine: docTR ~0.7 GB (frees model + empty_cache), subprocess ~2.5 GB
  (kills worker). _Pool tracks all instances and release_sync() tears them down.
- configure() now tears down stale pools on reconfigure (prompt VRAM free
  instead of GC-deferred).

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

Surya2 returns PageOCRResult.blocks[] (html/polygon/confidence/label/reading_order),
not .text_lines like classic surya. Worker now extracts text from block HTML (tag-stripped)
ordered by reading_order, with polygon->bbox. Verified end-to-end: latest Surya2 served via
the vLLM backend transcribes a scanned IT legal page with all codici fiscali correct.

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

vLLM integrated exactly like ds4/ktransformers — a managed external engine in an
ISOLATED venv (it pins torch 2.13/cu13, conflicting with the main venv), proxied over
its OpenAI HTTP API, selected per-model via a `backend: vllm` pin or the vllm.model_id
alias (never auto-claimed). Continuous batching for high aggregate throughput.

- config.py: VllmConfig (+ Config field, from_dict, to_dict)
- codai/api/vllm_worker.py: managed vllm.entrypoints.openai.api_server subprocess in the
  isolated venv (venv resolver: config>/opt/coderai/vllm_venv>/cache>~/.coderai), /v1/models
  health gate, auto_build
- codai/backends/vllm.py: VllmBackend OpenAI proxy (mirrors ktransformers)
- manager: get_active_vllm_config, "vllm" in _ENGINE_BACKENDS, _vllm_name_claims=False,
  vllm_should_handle, load branch, text-accept, /v1/models surfacing
- front-proxy: required_capability (vllm pin+alias), _DEFAULT_CAPS vllm on GPU nodes,
  assignment/engine_superviso...

- PaddleOCR 3.7 dropped use_gpu/use_angle_cls/show_log and raises ValueError for
  unknown ctor args; worker now tries 3.x (device=) then 2.x kwargs and prefers
  .predict() over .ocr(). Verified on a real scanned IT legal page.
- surya-ocr >=~0.15 ('Surya2') rearchitected to a VLM needing an external
  vLLM-in-Docker or llama-server backend (SpawnError in an isolated venv). Pin to
  0.6.4 which runs det+recognition locally on torch, matching the worker's API.

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

First OCR request for an unbuilt paddle/surya engine no longer blocks for minutes;
with auto_build it kicks off the background builder (same one the web UI uses) and
returns 503 'building — retry shortly'. Without auto_build it points at Settings.

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

OCR (v0.1.85): new codai/ocr/ subsystem — dedicated OCR engines (NOT a VLM):
- docTR (in-process, GPU) + PaddleOCR & Surya (isolated-venv subprocess workers
  via codai/ocr/workers/ocr_worker.py to avoid opencv-contrib/pillow<11 clashes;
  paddle-gpu bundles its own CUDA so a cu12x wheel runs on newer-CUDA hosts).
- /v1/ocr, /v1/ocr/batch, /v1/ocr/schemas CRUD; `ocr` pipeline step.
- Data-driven, user-extensible extraction schemas (named files + inline + auto),
  built-in seeds (italian_sentenza/generic_document/invoice); optional JSON Schema
  validation. Structured extraction via an existing coderai text model.
- Configurable stamp/signature detection (off|layout|detector|both); bundled
  signature YOLO default; layout markers EN+IT (timbro/sigillo/firma).
- Admin OCR card: engines/instances/detect/extraction + schema picker/raw-JSON/
  field-builder + isolated-venv build trigger (background build + status).
- Isolated venvs resolve baked(/o...