[VincentG1234]

Summary

Add optional speculative_decoding study configuration so Optuna can tune vLLM speculative decoding (EAGLE3, MTP, dflash, etc.) with synthetic rejection sampling, alongside existing target-model parameters.

Why

Speculative decoding is a major throughput lever for vLLM serving, but the search space is conditional (on/off toggle, method choice, k slicing, draft vs target settings). Users had no way to optimize these settings within auto-tuning-vllm studies.

What changed

• auto_tune_vllm/core/speculative.py — new module: config validation, Optuna suggest(), JSON assembly for --speculative-config
• auto_tune_vllm/core/config.py — parse speculative_decoding YAML block; reject sampler: grid when enabled
• auto_tune_vllm/core/study_controller.py — vLLM >= 0.20 version gate at study start; inject speculative_config into trial parameters
• auto_tune_vllm/cli/main.py — skip auto grid-mode when speculative search is active; validate shows speculative status and adjusted cardinality
• auto_tune_vllm/utils/vllm_cli_parser.py — more robust vLLM version detection (importlib + fallbacks)
• docs/configuration.md — full speculative decoding section (methods, synthetic modes, limitations)
• examples/study_config_speculative_decoding.yaml — EAGLE3 + synthetic acceptance example (Qwen3-8B)
• README.md — move speculative decoding from future work to completed

How tested

• ruff check .
• pytest -v tests/ (108 passed)
• Manual E2E (maintainer): auto-tune-vllm optimize --config examples/study_config_speculative_decoding.yaml on vLLM >= 0.20 with GPU

Risks / limitations

• No unit tests for speculative.py / config parsing yet — validation logic is exercised only indirectly via existing suite
• Grid sampler incompatible — conditional search space (on/off, k) cannot be enumerated; config validation rejects sampler: grid
• Optuna constraints cannot reference speculative sub-params (spec_method, spec_num_speculative_tokens); only composed speculative_config JSON is in trial params
• Requires vLLM >= 0.20 for synthetic rejection sampling; study fails fast with upgrade instructions if version is too old
• n_trials budget: baseline trials still count toward completed_trials / n_trials (pre-existing behavior; unchanged by this PR)

Links

• vLLM docs: https://docs.vllm.ai/en/stable/features/speculative_decoding/