Add default profile fallback and single-profile shortcut

Signed-off-by: roytman <roytman@il.ibm.com>

Author: roytman

pkg/epp/framework/plugins/scheduling/profilehandler/headerphase/README.md

@@ -12,12 +12,25 @@ each request is for, instead of needing one EPP instance per phase.
 Reads the configured header from the incoming request and looks up the
 `schedulingProfiles` entry with that exact name:
 
-- If a matching profile hasn't run yet, it runs that profile alone.
-- If the header is missing or names a profile that isn't configured, no profile runs. The
-  scheduler reports that no profile could be run at all, without a reason, which the EPP
-  maps to a 429 response to the client -- misleading, since the scheduler doesn't
-  distinguish a malformed request from exhausted capacity. The EPP logs the specific
-  reason (missing header vs. unconfigured value) for operators.
+- With exactly one profile configured, that profile always runs, regardless of the
+  header (or its absence). There is nothing else to disaggregate to, so a deployment
+  scaled down to a single stage -- or one that never disaggregates at all -- works
+  without swapping to a different profile handler.
+- With more than one profile configured and a matching profile named by the header, it
+  runs that profile alone.
+- With more than one profile configured and the header missing or blank, `defaultProfile`
+  runs instead of failing. This covers calls that never carry the header at all, such as
+  pass-through requests (e.g. `/models`) that don't go through phase-tagged scheduling.
+- With more than one profile configured and the header naming a profile that isn't
+  configured, no profile runs -- an unrecognized value is a real error, not treated the
+  same as an absent header. The scheduler reports that no profile could be run at all,
+  without a reason, which the EPP maps to a 429 response to the client -- misleading,
+  since the scheduler doesn't distinguish a malformed request from exhausted capacity.
+  The EPP logs the specific reason (missing header vs. unconfigured value) for operators.
+  A 400 would be the accurate status here, but `Pick` has no way to carry a typed error
+  through the scheduler to the client; that needs the same kind of `ProfileHandler`
+  extension-point signature change tracked for the conditional-decode gate in
+  [llm-d/llm-d-router#1686](https://github.com/llm-d/llm-d-router/issues/1686).
 
 ## How this differs from disagg-profile-handler
 
@@ -44,6 +57,7 @@ answer and makes one separate scheduling call per phase.
 | Name | Type | Default | Description |
 |---|---|---|---|
 | `headerName` | string | `EPP-Phase` | Request header whose value names the scheduling profile to run. Matched case-insensitively: the EPP lowercases every incoming header name, so this is normalized to lowercase regardless of how it's written here. |
+| `defaultProfile` | string | `decode` | Scheduling profile to run when the header is missing or blank and more than one profile is configured. Matched case-sensitively against `schedulingProfiles` names, like the header value itself. Ignored when only one profile is configured, since that profile always runs. |
 
 ### Example
 
@@ -65,4 +79,13 @@ schedulingProfiles:
   - pluginRef: decode-filter
 ```
 
-A request with `EPP-Phase: prefill` runs only the `prefill` profile.
+A request with `EPP-Phase: prefill` runs only the `prefill` profile. A request with no
+`EPP-Phase` header at all -- e.g. `GET /models` -- runs `decode`, the default.
+
+To use a different fallback than `decode`:
+
+```yaml
+- type: header-phase-profile-handler
+  parameters:
+    defaultProfile: prefill
+```

pkg/epp/framework/plugins/scheduling/profilehandler/headerphase/header_phase_profile_handler.go

@@ -34,6 +34,10 @@ const (
 
 	// defaultHeaderName is the request header read when parameters.HeaderName is empty.
 	defaultHeaderName = "EPP-Phase"
+
+	// defaultProfileName is the scheduling profile run when parameters.DefaultProfile is
+	// empty.
+	defaultProfileName = "decode"
 )
 
 // compile-time type assertion
@@ -44,6 +48,11 @@ type parameters struct {
 	// HeaderName is the request header whose value names the scheduling profile to run.
 	// Defaults to defaultHeaderName when empty.
 	HeaderName string `json:"headerName"`
+	// DefaultProfile is the scheduling profile to run when the header is missing or
+	// blank. Defaults to defaultProfileName when empty. Useful for requests that never
+	// carry the header at all - pass-through calls (e.g. /models) or a deployment that
+	// doesn't disaggregate.
+	DefaultProfile string `json:"defaultProfile"`
 }
 
 // Factory defines the factory function for HeaderPhaseProfileHandler.
@@ -55,24 +64,35 @@ func Factory(name string, rawParameters *json.Decoder, _ fwkplugin.Handle) (fwkp
 		}
 	}
 
-	return NewHeaderPhaseProfileHandler(params.HeaderName).WithName(name), nil
+	return NewHeaderPhaseProfileHandler(params.HeaderName, params.DefaultProfile).WithName(name), nil
 }
 
 // NewHeaderPhaseProfileHandler initializes a new HeaderPhaseProfileHandler and returns
-// its pointer. headerName is lowercased and trimmed, falling back to defaultHeaderName
-// when that leaves it empty: the EPP's request handler lowercases every incoming header
-// name at ingestion (pkg/epp/handlers/request.go), so the configured name must be
-// normalized the same way to match, and an empty header key would never match any
-// request.
-func NewHeaderPhaseProfileHandler(headerName string) *HeaderPhaseProfileHandler {
+// its pointer.
+//
+// headerName is lowercased and trimmed, falling back to defaultHeaderName when that
+// leaves it empty: the EPP's request handler lowercases every incoming header name at
+// ingestion (pkg/epp/handlers/request.go), so the configured name must be normalized the
+// same way to match, and an empty header key would never match any request.
+//
+// defaultProfile is trimmed, falling back to defaultProfileName when that leaves it
+// empty. Unlike headerName, it is not case-normalized: it names a schedulingProfiles
+// entry, which (like the header value itself) is matched case-sensitively.
+func NewHeaderPhaseProfileHandler(headerName, defaultProfile string) *HeaderPhaseProfileHandler {
 	headerName = strings.ToLower(strings.TrimSpace(headerName))
 	if headerName == "" {
 		headerName = strings.ToLower(defaultHeaderName)
 	}
 
+	defaultProfile = strings.TrimSpace(defaultProfile)
+	if defaultProfile == "" {
+		defaultProfile = defaultProfileName
+	}
+
 	return &HeaderPhaseProfileHandler{
-		typedName:  fwkplugin.TypedName{Type: HeaderPhaseProfileHandlerType, Name: HeaderPhaseProfileHandlerType},
-		headerName: headerName,
+		typedName:      fwkplugin.TypedName{Type: HeaderPhaseProfileHandlerType, Name: HeaderPhaseProfileHandlerType},
+		headerName:     headerName,
+		defaultProfile: defaultProfile,
 	}
 }
 
@@ -81,9 +101,17 @@ func NewHeaderPhaseProfileHandler(headerName string) *HeaderPhaseProfileHandler
 // phases of a disaggregated pipeline (e.g. encode, prefill, decode) whose caller already
 // knows, out of band, which phase each request is for - unlike the disagg profile
 // handler, which decides which profiles to run via decider plugins.
+//
+// Two fallbacks keep single-stage and header-less traffic working without a different
+// profile handler: with exactly one configured profile there is nothing to disaggregate,
+// so that profile always runs regardless of the header (or its absence); with more than
+// one configured profile, a request whose header is missing or blank runs defaultProfile
+// instead of failing. A header naming a profile that isn't configured is still an error -
+// only the header's absence triggers the default, not an unrecognized value.
 type HeaderPhaseProfileHandler struct {
-	typedName  fwkplugin.TypedName
-	headerName string
+	typedName      fwkplugin.TypedName
+	headerName     string
+	defaultProfile string
 }
 
 // TypedName returns the type and name tuple of this plugin instance.
@@ -116,44 +144,55 @@ func (h *HeaderPhaseProfileHandler) noMatchError(phase string) error {
 	return fmt.Errorf("header-phase profile handler: no scheduling profile configured for %q header value %q", h.headerName, phase)
 }
 
-// Pick selects the single SchedulingProfile named by the request's phase header. It
-// returns an empty map once that profile has run, or when the header is missing or
-// names a profile that isn't configured. In the latter case the scheduler's run loop
-// (pkg/epp/scheduling.Scheduler.Schedule) stops without ever calling ProcessResults, so
-// the specific reason is logged here rather than returned from ProcessResults, where it
-// would be unreachable. The client never sees that reason: it only gets the scheduler's
-// generic "failed to run any scheduler profile" error, which
-// pkg/epp/requestcontrol/director.go maps to a 429 ResourceExhausted response -
-// misleading, since a malformed or missing header is a client error, not a capacity
-// problem. Surfacing the real reason to the client needs a scheduler/ProfileHandler
-// contract change and is out of scope here; the log is a diagnostic aid for operators,
-// not an equivalent substitute for what the caller receives.
+// Pick selects the single SchedulingProfile to run: the only configured profile when
+// there is just one, otherwise the one named by the request's phase header, falling
+// back to defaultProfile when the header is missing or blank. It returns an empty map
+// once that profile has run, or when no profile could be resolved. In the latter case
+// the scheduler's run loop (pkg/epp/scheduling.Scheduler.Schedule) stops without ever
+// calling ProcessResults, so the specific reason is logged here rather than returned
+// from ProcessResults, where it would be unreachable. The client never sees that
+// reason: it only gets the scheduler's generic "failed to run any scheduler profile"
+// error, which pkg/epp/requestcontrol/director.go maps to a 429 ResourceExhausted
+// response - misleading, since a malformed or missing header is a client error, not a
+// capacity problem. Surfacing the real reason to the client needs a
+// scheduler/ProfileHandler contract change and is out of scope here; the log is a
+// diagnostic aid for operators, not an equivalent substitute for what the caller
+// receives.
 func (h *HeaderPhaseProfileHandler) Pick(ctx context.Context, request *fwksched.InferenceRequest, profiles map[string]fwksched.SchedulerProfile,
 	profileResults map[string]*fwksched.ProfileRunResult) map[string]fwksched.SchedulerProfile {
-	// TODO(#2135): single profile per request; extend to loop over an ordered phase
-	// list parsed from the header for non-deferred multi-profile scheduling.
 	if len(profileResults) > 0 { // the selected profile has already run
 		return map[string]fwksched.SchedulerProfile{}
 	}
 
+	// With exactly one configured profile there is nothing to disaggregate: always run
+	// it, so a deployment scaled down to a single stage works without swapping profile
+	// handlers or requiring every caller to send the header.
+	if len(profiles) == 1 {
+		for name, profile := range profiles {
+			return map[string]fwksched.SchedulerProfile{name: profile}
+		}
+	}
+
 	phase := h.phaseHeader(request)
-	profile, ok := profiles[phase]
+	resolvedPhase := phase
+	if resolvedPhase == "" {
+		resolvedPhase = h.defaultProfile
+	}
+
+	profile, ok := profiles[resolvedPhase]
 	if !ok {
 		log.FromContext(ctx).Error(h.noMatchError(phase), "no scheduling profile selected for request")
 		return map[string]fwksched.SchedulerProfile{}
 	}
 
-	return map[string]fwksched.SchedulerProfile{phase: profile}
+	return map[string]fwksched.SchedulerProfile{resolvedPhase: profile}
 }
 
 // ProcessResults handles the outcome of the single profile run selected by Pick.
 // It specifies in the SchedulingResult the key of the primary profile that should be
 // used to get the request's selected destination.
 func (h *HeaderPhaseProfileHandler) ProcessResults(_ context.Context, request *fwksched.InferenceRequest,
 	profileResults map[string]*fwksched.ProfileRunResult) (*fwksched.SchedulingResult, error) {
-	// TODO(#2135): single profile per request; extend by re-parsing the header's
-	// ordered phase list to pick a primary among multiple results for non-deferred
-	// multi-profile scheduling.
 	switch len(profileResults) {
 	case 0:
 		return nil, h.noMatchError(h.phaseHeader(request))