feat: define engine-neutral backend telemetry and replica identity contract
#2,349 opened on Jul 5, 2026
Repository metrics
- Stars
- (4,293 stars)
- PR merge metrics
- (PR metrics pending)
Description
Summary
Define the engine-neutral contract that inference-aware backend routing will consume before adding engine-specific integrations for vLLM, SGLang, ATOM, or future serving engines.
Parent roadmap: #2287
Parent issue: #2332
Related code: src/semantic-router/pkg/config, src/semantic-router/pkg/selection, src/semantic-router/pkg/inflight, src/semantic-router/pkg/latency, src/semantic-router/pkg/extproc, deploy/operator/controllers/backend_discovery.go
Motivation
The current router can select a logical model and already has model-level latency, in-flight, multi-factor, and cache-affinity signals. It does not yet have a normalized backend/replica identity model or a telemetry schema that can represent queue depth, GPU load, KV/cache affinity, health, and freshness across different inference engines.
Without this layer, engine-specific work will either duplicate logic or leak vLLM/SGLang/ATOM details into the router hot path.
Scope
Define a normalized backend observation contract covering:
- logical model name, backend ref, endpoint, and replica identity;
- serving engine kind and version when available;
- queue depth, active requests, GPU utilization, memory pressure, and health;
- TTFT/TPOT/E2E latency samples keyed by backend/replica;
- KV cache, prefix cache, session, or prefix affinity hints;
- freshness, TTL, confidence, and fail-open behavior;
- diagnostics emitted to replay, response headers or traces where appropriate.
Non-goals
- Do not implement an engine-specific collector here.
- Do not require synchronous telemetry fetches on the request path.
- Do not replace logical model selection or provider config.
Acceptance criteria
- A backend telemetry schema and identity model can represent vLLM, SGLang, and ATOM without engine-specific fields in core selection logic.
- Missing/stale telemetry behavior is explicit and testable.
- Selection code can consume backend telemetry as a second-stage backend policy after logical model selection.
- Replay/diagnostics can explain selected model, selected backend/replica, telemetry freshness, and policy reason.
Validation
make agent-report ENV=cpu CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/selection src/semantic-router/pkg/inflight src/semantic-router/pkg/latency src/semantic-router/pkg/extproc deploy/operator website/docs"
make agent-lint CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/selection src/semantic-router/pkg/inflight src/semantic-router/pkg/latency src/semantic-router/pkg/extproc deploy/operator website/docs"
make agent-ci-gate CHANGED_FILES="src/semantic-router/pkg/config src/semantic-router/pkg/selection src/semantic-router/pkg/inflight src/semantic-router/pkg/latency src/semantic-router/pkg/extproc deploy/operator website/docs"