vllm-project/semantic-router

cleanup: finish Router Learning migration and reject legacy learning config paths

Open

#2,242 opened on Jun 18, 2026

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Go (699 forks)github user discovery
area/model-selectionarea/researchenhancementhelp wantedpriority/P2roadmap

Repository metrics

Stars
 (4,293 stars)
PR merge metrics
 (PR metrics pending)

Description

Parent: #2238 Related: #2239, #2241, #2308, #2346 Day0 implementation baseline: #2258

Goal

Finish the migration from legacy stateful learning-style selector paths into the Router Learning adaptation model, and make legacy public config paths fail with clear actionable errors.

This issue is intentionally scoped to migration cleanup and compatibility boundaries. New day2 learning algorithms are tracked separately by #2308 and #2346. Adaptation composition is tracked by #2241. Runtime contract hardening is tracked by #2239.

Audited current-main baseline (2026-07-15)

  • Current main accepts the clean global.router.learning contract and rejects legacy public method names through config validation.
  • Legacy selector implementation files such as pkg/selection/elo.go, rl_driven.go, gmtrouter.go, and lookup-table code still exist for cleanup/internal migration analysis.
  • Their presence is not evidence that those names remain supported public Router Learning APIs.

Motivation

Router Learning should own stateful cross-request behavior through one documented adaptation runtime and config surface. Leaving older public paths around under decision.algorithm, legacy RL router names, or private per-algorithm state stores would make the H2 roadmap harder to reason about and harder to validate.

Scope

  • Audit docs, examples, recipes, CLI schema, dashboard surfaces, and tests for legacy public learning paths.
  • Reject legacy public config paths with actionable validation errors instead of silently rewriting them.
  • Confirm stateful learning behavior is configured under Router Learning adaptations.
  • Decide whether old GMTRouter/Elo/RL-driven implementation pieces should be deleted, wrapped as internal helpers, or documented as legacy internals.
  • Keep migration diagnostics clear in replay/debug output.

Non-goals

  • Do not add new learning algorithms here; use #2308 or follow-up algorithm issues.
  • Do not redesign adaptation composition here; use #2241.
  • Do not change the accepted Router Learning runtime contract without coordinating with #2239.

Acceptance criteria

  • Stateful learning behavior is owned by Router Learning state/adaptations, not public base algorithms.
  • Legacy public config paths are rejected with clear validation errors.
  • Docs and examples no longer imply stateful learning belongs under decision.algorithm.
  • Any remaining legacy implementation code is either removed, wrapped as internal-only, or documented with a removal plan.
  • Tests cover at least one legacy config rejection path.

Validation entrypoint

make agent-report ENV=cpu CHANGED_FILES="<space-separated changed files>"

Run config rejection tests plus the Router Learning gates reported by the harness.

Contributor guide