feat(lora): add Python resolver plugins for vLLM

[biswapanda]

Summary

• Add the backend-neutral Python resolver plugin contract configured through DYN_LORA_DOWNLOADER_PLUGIN.
• Pass the exact opaque source to the selected worker-side plugin; the plugin owns scheme parsing, provider authentication, immutable revision lookup, download, and atomic materialization.
• Validate the returned snapshot with a strict safetensors-only allowlist and enforce base compatibility, cache containment, measured size, timeouts, concurrency, pending-admission limits, and resident capacity.
• Add aggregated-vLLM load-on-miss with per-key singleflight, cancellation-safe resolution/load cleanup, engine-state reconciliation, private residency tracking, and administrative API isolation.
• Publish protocol-v2 resolver capabilities for the Rust routing layer in feat(lora): add request-time routing protocol #15031 and fail closed for unsupported worker paths.
• Document the external request contract, plugin ABI, operational limits, and W&B/native-vLLM compatibility-wrapper pattern.

Stack

• Part 2 of 2; stacked on feat(lora): add request-time routing protocol #15031 with GitHub base bis/dis-2937-implement-pluggable-request-time-lora-resolution.
• This PR contains the Python resolver contract, aggregated-vLLM integration, tests, and docs.

Supported scope

• Aggregated vLLM tokenized request path only.
• SGLang, TensorRT-LLM, disaggregated prefill/decode, and workers without an exact compatible capability advertisement fail closed; no SGLang-specific resolver changes are expected in this PR.
• Runtime adapters are pinned for the worker lifetime in protocol v2. Routing uses deterministic single-worker HRW placement and does not spill an accepted request to another worker.

Validation

• pre-commit run --all-files — passed
• Affected Python unit/integration suite — 320 passed, 6 expected skips
• Focused mypy validation for the changed runtime resolver, validation, and Omni paths — passed
• cargo test -p dynamo-llm --no-default-features --lib lora -- --nocapture — 184 passed
• cargo clippy -p dynamo-llm --no-default-features --all-targets -- -D warnings
• cargo fmt --all -- --check
• git diff --check origin/main...HEAD

GPU end-to-end

Ran Dynamo frontend → Rust opaque request parsing/routing → worker resolver plugin → snapshot validation → dynamic vLLM GPU load → generation with Qwen3-0.6B and a rank-64 Qwen3 adapter. The following cases passed:

• Base-model chat request.
• Qwen/Qwen3-0.6B|wandb-artifact:///team/project/qwen3-accuracy:v1 chat request.
• Bare wandb-artifact:///team/project/qwen3-accuracy:v1 request with one canonical base.
• /v1/completions cached repeat; resolver invocation count remained one.
• Streaming chat request through the runtime-LoRA path.
• Unsupported evil:///x returned HTTP 400.
• Unknown explicit base returned HTTP 404.
• Worker /v1/loras reported dyn-lora-f202aaf30cad5c6f70d5fa735d5bd592, and worker logs confirmed all adapter requests used that loaded key.

The E2E used the cached vllm/vllm-openai:v0.28.0 image and a local offline resolver that implements the W&B-shaped URI contract by atomically materializing the cached adapter. This validates the plugin boundary and real GPU adapter loading without W&B credentials or network access. The branch currently pins vLLM 0.29, so an exact pinned-image CI run remains desirable.

Remaining draft gates

• Add a maintained GPU E2E workflow using the branch-pinned vLLM image before graduating the feature from experimental status.
• Add dedicated low-cardinality runtime-LoRA metrics.
• The resolver is trusted in-process plugin code; cache reservations are advisory until Dynamo post-measures the materialized snapshot.

Review

• Reviewed with Claude Opus 1M using the adversarial, Will's mega-review, and thermo-nuclear code-quality review checklists.
• Addressed findings around cancellation safety, Python 3.10 timeout compatibility, feature-off overhead, constructor compatibility, strict snapshot contents, pending-admission accounting, queue/deadline semantics, worker shutdown, and engine-state reconciliation.

Related issues

• Depends on feat(lora): add request-time routing protocol #15031
• Relates to feat(frontend): runtime LoRA resolution for base|adapter and scheme-prefixed model IDs on chat/completions #14547
• Implements the worker portion of DEP RFC: Pluggable Request-Time LoRA Resolution #15018

[github-actions]

🌿 Fern Docs Preview: https://nvidia-preview-01a0b563-b862-776d-b615-072042629528.docs.buildwithfern.com/dynamo/dev