fix(vllm): apply Options[] engine flags before engine init

[localai-bot]

Fixes #11130

Problem

CLI-style flags in a model's options: array were silently discarded:

backend: cuda13-vllm
options:
  - --quantization:gptq_marlin
  - --enable-prefix-caching
  - --kv-cache-dtype:fp8_e5m2
  - --reasoning-parser:qwen3

The vLLM backend read Options[] only for tool_parser/reasoning_parser, and read it after AsyncLLMEngine.from_engine_args() - past the point where anything it set could still reach the engine.

Fix

apply_options_to_engine_args() in backend/python/common/vllm_utils.py maps -- prefixed options onto the AsyncEngineArgs dataclass, applied in LoadModel before the engine is constructed.

• Only -- prefixed entries are engine flags, so tool_parser:, reasoning_parser:, vad_only and friends keep their meaning. Both --flag:value (LocalAI convention) and --flag=value (vLLM CLI convention) are accepted.
• Dashes become underscores (--enable-prefix-caching -> enable_prefix_caching); values are coerced to the target field's type; a bare --flag sets a boolean field to true.
• Unknown or uncoercible flags warn on stderr and are skipped rather than failing the load - unlike engine_args:, Options[] is a shared bag that carries entries this mapping knows nothing about. Unknown flags get a closest-field hint.
• --tool-parser/--reasoning-parser are never reported as unknown: LocalAI consumes them itself, and whether the engine dataclass also carries the field varies by vLLM version.

Type inference reads the annotation's base, not a substring. The first cut matched substrings and misread vLLM's dtype: Literal["auto", "float16", "bfloat16"] as a float, silently dropping --dtype:bfloat16; there is a regression test for it. It also handles PEP 563 string annotations, which is how vLLM's arg_utils is written.

Precedence: typed proto fields -> options: -> engine_args:. Since engine_args: lands last, applyEngineArgDefaults in core/config/hooks_vllm.go now skips seeding a production default whose key the user already set as an option - otherwise the seeded enable_prefix_caching: true would silently beat a user's --enable-prefix-caching:false.

normalize_option_key also makes the parser lookup accept the CLI spelling, so --reasoning-parser:qwen3 selects LocalAI's reasoning parser and not just the engine field.

Tests

• backend/python/common/vllm_utils_test.py - 20 stdlib-only specs covering coercion (bool/int/float/dict/str), bare flags, = separator, unknown-flag warn-and-skip with hint, uncoercible values, Literal-typed fields, PEP 563 string annotations, and non-flag options being left alone.
• core/config/hooks_test.go - two new specs: a default is not seeded when the user set that key via options:, and unrelated options still get the defaults.
• New make test-python-helpers target, wired into the lint workflow's dependency-light job. These shared python helper tests previously ran nowhere in CI.

make lint clean; core/config suite green (409 specs).

Not covered

• vllm-omni builds Omni(**kwargs) rather than an AsyncEngineArgs dataclass, so it needs a different mapping and is untouched here.
• The dataclass-reflection path is exercised against stand-in dataclasses mirroring vLLM's field shapes (no vLLM wheel in the dev environment), not against vLLM itself. The issue's "deploy and check the engine log" step still wants a run on a GPU host.

Docs

docs/content/features/text-generation.md gains a "CLI-style engine flags in options" section stating the rules and the precedence; .agents/vllm-backend.md records the ordering trap for future work.

[mudler]

@localai-org-maint-bot CI is failing, pick this up and fix the branch