[AlejandroParedesLT]

Overview

First slice of #61024's "Migrate speculative model code to Flat Model" bullet (RFC #44219). Moves the Medusa draft-model implementation from the legacy vllm/model_executor/models/ layout into the new vllm/models/<name>/<hw>/ layout.

Claims

• Moves vllm/model_executor/models/medusa.py to vllm/models/medusa/common/medusa.py + a package __init__.py, and repoints the MedusaModel entry in registry.py to vllm.models.medusa.
• No logic change. The only diff inside the moved file is fixing from .utils import maybe_prefix to the now-external from vllm.model_executor.models.utils import maybe_prefix (verified by diffing old vs. new file content).
• Medusa needs only a common/ directory, no nvidia/amd/cpu/xpu split: it's pure torch.nn (Linear, SiLU, LogitsProcessor, ParallelLMHead), no custom kernels, and has no dependency on any base model's architecture code (unlike e.g. llama_eagle.py, which imports LlamaForCausalLM directly and so can't move independently of a Llama migration). That made it the first candidate out of the ~30 remaining legacy drafter files.

Validation

.venv/bin/python -m pytest tests/models/test_registry.py -q -k MedusaModel
# 1 passed

.venv/bin/python -m pytest tests/config/test_model_arch_config.py -q -k medusa
# 1 passed

pre-commit run --files vllm/model_executor/models/registry.py vllm/models/medusa/__init__.py vllm/models/medusa/common/__init__.py vllm/models/medusa/common/medusa.py
# all hooks passed (ruff check/format, mypy, SPDX headers, etc.)

Not yet validated: tests/v1/e2e/spec_decode/acceptance_rates/mtp_other/test_medusa.py (the real vicuna-7b + FasterDecoding/medusa-vicuna-7b-v1.3 acceptance-rate test). It fails consistently (~4s, reproduced twice) with RuntimeError: Engine core initialization failed... Failed core proc(s): {} from wait_for_engine_startup -- before weight download or model loading begins. This looks like an engine-multiprocessing/sandbox limitation in the dev environment used for this PR, not something caused by this diff (the direct from vllm.models.medusa import Medusa import works, and the registry's own import-sanity test passes), but I haven't confirmed that against main yet. Flagging explicitly rather than claiming this test passes -- will confirm before marking ready for review.

Details

Convention followed: matches already-migrated families (deepseek_v32, kimi_k3, glm5next, etc.) -- vllm/models/<name>/__init__.py re-exporting from common/<name>.py. Medusa is the first fully common-only package in the new layout (no existing family currently skips the nvidia/amd split entirely), since it has nothing hardware-specific to split out.

Duplicate-work check: searched open issues/PRs (gh issue list/gh pr list, several keyword variants) before starting; found no PR doing this specific migration. One unrelated open PR (#48715, a large personal-fork rebase) happens to touch medusa.py incidentally among dozens of unrelated files -- not a competing Flat Model migration.

Scope: this PR only moves Medusa. The other ~30 legacy drafter files (EAGLE/EAGLE3, MTP variants, DFlash) are out of scope here; most are entangled with their own not-yet-migrated base model and need to be scoped individually.

This PR is a draft while the e2e validation gap above is resolved.

---

Pull Request Checklist

• I used vLLM's /pr-checklist skill. (Mandatory for agents, optional for humans).

• AI assistance was used during the creation of this PR.

• Design Fit: Minimizes impact on core components, reuses existing functionality, and justifies added complexity.

• Testing and Validation: Validates the change and ensures any added tests are meaningful and reliable, with CI coverage or documented CI resource constraints and validation performed outside CI. (e2e acceptance-rate test not yet confirmed -- see Validation section)

• Code Quality and Style: Keeps code and comments clear and concise, and updates relevant documentation and examples.

• Pull Request Contents: Includes a brief summary and relevant links, supports claims with evidence, explains root causes and implementation trade-offs, and follows the contributing guide.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S7agbtPNuVe9pxACkqbitP

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @AlejandroParedesLT.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[AlejandroParedesLT]

Closing: Medusa support was removed entirely in #61701 (merged 2026-10-15), after this PR was opened. Per that PR's rationale, Medusa isn't supported by Model Runner V2 and EAGLE/MTP/DFlash/DSpark cover its use case, so there's nothing left to migrate to the Flat Model layout here. Picking a different drafter for the next migration slice instead.