add scorer category to scorer interface. (#2119)

Signed-off-by: Nir Rozenbaum <nirro@il.ibm.com>

Author: nirrozenbaum

pkg/epp/config/loader/configloader_test.go

@@ -408,35 +408,39 @@ func (m *mockPlugin) TypedName() plugins.TypedName { return m.t }
 // Mock Scorer
 type mockScorer struct{ mockPlugin }
 
+// compile-time type assertion
+var _ framework.Scorer = &mockScorer{}
+
+func (m *mockScorer) Category() framework.ScorerCategory {
+	return framework.Distribution
+}
+
 func (m *mockScorer) Score(context.Context, *types.CycleState, *types.LLMRequest, []types.Endpoint) map[types.Endpoint]float64 {
 	return nil
 }
 
 // Mock Picker
 type mockPicker struct{ mockPlugin }
 
+// compile-time type assertion
+var _ framework.Picker = &mockPicker{}
+
 func (m *mockPicker) Pick(context.Context, *types.CycleState, []*types.ScoredEndpoint) *types.ProfileRunResult {
 	return nil
 }
 
 // Mock Handler
 type mockHandler struct{ mockPlugin }
 
-func (m *mockHandler) Pick(
-	context.Context,
-	*types.CycleState,
-	*types.LLMRequest,
-	map[string]*framework.SchedulerProfile,
-	map[string]*types.ProfileRunResult,
-) map[string]*framework.SchedulerProfile {
+// compile-time type assertion
+var _ framework.ProfileHandler = &mockHandler{}
+
+func (m *mockHandler) Pick(context.Context, *types.CycleState, *types.LLMRequest, map[string]*framework.SchedulerProfile,
+	map[string]*types.ProfileRunResult) map[string]*framework.SchedulerProfile {
 	return nil
 }
-func (m *mockHandler) ProcessResults(
-	context.Context,
-	*types.CycleState,
-	*types.LLMRequest,
-	map[string]*types.ProfileRunResult,
-) (*types.SchedulingResult, error) {
+func (m *mockHandler) ProcessResults(context.Context, *types.CycleState, *types.LLMRequest,
+	map[string]*types.ProfileRunResult) (*types.SchedulingResult, error) {
 	return nil, nil
 }
 

pkg/epp/scheduling/framework/plugins.go

@@ -31,6 +31,22 @@ const (
 	ProcessProfilesResultsExtensionPoint = "ProcessProfilesResults"
 )
 
+// ScorerCategory marks the preference a scorer applies when scoring candidate endpoints.
+type ScorerCategory string
+
+const (
+	// Affinity indicates a scorer that prefers endpoints with existing locality, such as kv-cache or session-related state,
+	// and therefore tends to give higher scores to the same endpoints.
+	Affinity ScorerCategory = "Affinity"
+
+	// Distribution indicates a scorer that prefers spreading requests evenly across all candidate endpoints to avoid
+	// hotspots and improve overall utilization.
+	Distribution ScorerCategory = "Distribution"
+
+	// Balance indicates a scorer that its preference is balanced between Affinity and Distribution.
+	Balance ScorerCategory = "Balance"
+)
+
 // ProfileHandler defines the extension points for handling multi SchedulerProfile instances.
 // More specifically, this interface defines the 'Pick' and 'ProcessResults' extension points.
 type ProfileHandler interface {
@@ -60,6 +76,7 @@ type Filter interface {
 // If a scorer returns value lower than 0, it will be treated as score 0.
 type Scorer interface {
 	plugins.Plugin
+	Category() ScorerCategory
 	Score(ctx context.Context, cycleState *types.CycleState, request *types.LLMRequest, pods []types.Endpoint) map[types.Endpoint]float64
 }
 

pkg/epp/scheduling/framework/plugins/multi/prefix/plugin.go

@@ -207,6 +207,11 @@ func (p *Plugin) TypedName() plugins.TypedName {
 	return p.typedName
 }
 
+// Category returns the preference the scorer applies when scoring candidate endpoints.
+func (p *Plugin) Category() framework.ScorerCategory {
+	return framework.Affinity
+}
+
 // WithName sets the name of the plugin.
 func (p *Plugin) WithName(name string) *Plugin {
 	p.typedName.Name = name

pkg/epp/scheduling/framework/plugins/multi/slo_aware_router/scorer.go

@@ -186,6 +186,11 @@ func (s *SLOAwareRouter) TypedName() plugins.TypedName {
 	return s.typedName
 }
 
+// Category returns the preference the scorer applies when scoring candidate endpoints.
+func (s *SLOAwareRouter) Category() framework.ScorerCategory {
+	return framework.Balance
+}
+
 func (s *SLOAwareRouter) WithName(name string) *SLOAwareRouter {
 	s.typedName.Name = name
 	return s

pkg/epp/scheduling/framework/plugins/scorer/kvcache_utilization.go

@@ -55,6 +55,11 @@ func (s *KVCacheUtilizationScorer) TypedName() plugins.TypedName {
 	return s.typedName
 }
 
+// Category returns the preference the scorer applies when scoring candidate endpoints.
+func (s *KVCacheUtilizationScorer) Category() framework.ScorerCategory {
+	return framework.Distribution
+}
+
 // Consumes returns the list of data that is consumed by the plugin.
 func (s *KVCacheUtilizationScorer) Consumes() map[string]any {
 	return map[string]any{

pkg/epp/scheduling/framework/plugins/scorer/lora_affinity.go

@@ -55,6 +55,11 @@ func (s *LoraAffinityScorer) TypedName() plugins.TypedName {
 	return s.typedName
 }
 
+// Category returns the preference the scorer applies when scoring candidate endpoints.
+func (s *LoraAffinityScorer) Category() framework.ScorerCategory {
+	return framework.Affinity
+}
+
 // Consumes returns the list of data that is consumed by the plugin.
 func (s *LoraAffinityScorer) Consumes() map[string]any {
 	return map[string]any{

pkg/epp/scheduling/framework/plugins/scorer/queue.go

@@ -57,6 +57,11 @@ func (s *QueueScorer) TypedName() plugins.TypedName {
 	return s.typedName
 }
 
+// Category returns the preference the scorer applies when scoring candidate endpoints.
+func (s *QueueScorer) Category() framework.ScorerCategory {
+	return framework.Distribution
+}
+
 // Consumes returns the list of data that is consumed by the plugin.
 func (s *QueueScorer) Consumes() map[string]any {
 	return map[string]any{

pkg/epp/scheduling/framework/plugins/scorer/running.go

@@ -57,6 +57,11 @@ func (s *RunningRequestsSizeScorer) TypedName() plugins.TypedName {
 	return s.typedName
 }
 
+// Category returns the preference the scorer applies when scoring candidate endpoints.
+func (s *RunningRequestsSizeScorer) Category() framework.ScorerCategory {
+	return framework.Distribution
+}
+
 // Consumes returns the list of data that is consumed by the plugin.
 func (s *RunningRequestsSizeScorer) Consumes() map[string]any {
 	return map[string]any{

pkg/epp/scheduling/framework/scheduler_profile_test.go

@@ -201,6 +201,10 @@ func (tp *testPlugin) TypedName() plugins.TypedName {
 	return tp.typedName
 }
 
+func (tp *testPlugin) Category() ScorerCategory {
+	return Distribution
+}
+
 func (tp *testPlugin) Filter(_ context.Context, _ *types.CycleState, _ *types.LLMRequest, endpoints []types.Endpoint) []types.Endpoint {
 	tp.FilterCallCount++
 	return findEndpoints(endpoints, tp.FilterRes...)