api: use consistent naming for cel/extproc (#369)

**Commit Message**

This renames some field and constant of API. The first is to rename
externalProcess -> externalProcessor where the latter is the official
naming in Envoy documentation and API. The second is to rename
LLMRequestCost.celExpression -> LLMRequestCost.cel where the short
version matches the LLMRequestCostTypeCEL value "CEL" plus the suffix
doesn't add any useful context.

---------

Signed-off-by: Takeshi Yoneda <[email protected]>

Author: mathetake

api/v1alpha1/api.go

@@ -95,7 +95,7 @@ type AIGatewayRouteSpec struct {
 	// An AI Gateway filter is responsible for the transformation of the request and response
 	// as well as the routing behavior based on the model name extracted from the request content, etc.
 	//
-	// Currently, the filter is only implemented as an external process filter, which might be
+	// Currently, the filter is only implemented as an external processor filter, which might be
 	// extended to other types of filters in the future. See https://github.com/envoyproxy/ai-gateway/issues/90
 	FilterConfig *AIGatewayFilterConfig `json:"filterConfig,omitempty"`
 
@@ -251,39 +251,39 @@ type AIGatewayRouteRuleMatch struct {
 type AIGatewayFilterConfig struct {
 	// Type specifies the type of the filter configuration.
 	//
-	// Currently, only ExternalProcess is supported, and default is ExternalProcess.
+	// Currently, only ExternalProcessor is supported, and default is ExternalProcessor.
 	//
-	// +kubebuilder:default=ExternalProcess
+	// +kubebuilder:default=ExternalProcessor
 	Type AIGatewayFilterConfigType `json:"type"`
 
-	// ExternalProcess is the configuration for the external process filter.
+	// ExternalProcessor is the configuration for the external processor filter.
 	// This is optional, and if not set, the default values of Deployment spec will be used.
 	//
 	// +optional
-	ExternalProcess *AIGatewayFilterConfigExternalProcess `json:"externalProcess,omitempty"`
+	ExternalProcessor *AIGatewayFilterConfigExternalProcessor `json:"externalProcessor,omitempty"`
 }
 
 // AIGatewayFilterConfigType specifies the type of the filter configuration.
 //
-// +kubebuilder:validation:Enum=ExternalProcess;DynamicModule
+// +kubebuilder:validation:Enum=ExternalProcessor;DynamicModule
 type AIGatewayFilterConfigType string
 
 const (
-	AIGatewayFilterConfigTypeExternalProcess AIGatewayFilterConfigType = "ExternalProcess"
-	AIGatewayFilterConfigTypeDynamicModule   AIGatewayFilterConfigType = "DynamicModule" // Reserved for https://github.com/envoyproxy/ai-gateway/issues/90
+	AIGatewayFilterConfigTypeExternalProcessor AIGatewayFilterConfigType = "ExternalProcessor"
+	AIGatewayFilterConfigTypeDynamicModule     AIGatewayFilterConfigType = "DynamicModule" // Reserved for https://github.com/envoyproxy/ai-gateway/issues/90
 )
 
-type AIGatewayFilterConfigExternalProcess struct {
-	// Replicas is the number of desired pods of the external process deployment.
+type AIGatewayFilterConfigExternalProcessor struct {
+	// Replicas is the number of desired pods of the external processor deployment.
 	//
 	// +optional
 	Replicas *int32 `json:"replicas,omitempty"`
-	// Resources required by the external process container.
+	// Resources required by the external processor container.
 	// More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
 	//
 	// +optional
 	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`
-	// TODO: maybe adding the option not to deploy the external process filter and let the user deploy it manually?
+	// TODO: maybe adding the option not to deploy the external processor filter and let the user deploy it manually?
 	// 	Not sure if it is worth it as we are migrating to dynamic modules.
 }
 
@@ -509,7 +509,7 @@ type LLMRequestCost struct {
 	//
 	// +kubebuilder:validation:Enum=OutputToken;InputToken;TotalToken;CEL
 	Type LLMRequestCostType `json:"type"`
-	// CELExpression is the CEL expression to calculate the cost of the request.
+	// CEL is the CEL expression to calculate the cost of the request.
 	// The CEL expression must return a signed or unsigned integer. If the
 	// return value is negative, it will be error.
 	//
@@ -529,7 +529,7 @@ type LLMRequestCost struct {
 	//	* "input_tokens * output_tokens"
 	//
 	// +optional
-	CELExpression *string `json:"celExpression,omitempty"`
+	CEL *string `json:"cel,omitempty"`
 }
 
 // LLMRequestCostType specifies the type of the LLMRequestCost.

api/v1alpha1/zz_generated.deepcopy.go

@@ -124,7 +124,7 @@ Rules []AIGatewayRouteRule `json:"rules"`
 // An AI Gateway filter is responsible for the transformation of the request and response
 // as well as the routing behavior based on the model name extracted from the request content, etc.
 //
-// Currently, the filter is only implemented as an external process filter, which might be
+// Currently, the filter is only implemented as an external processor filter, which might be
 // extended to other types of filters in the future. See https://github.com/envoyproxy/ai-gateway/issues/90
 FilterConfig *AIGatewayFilterConfig `json:"filterConfig,omitempty"`
 
@@ -184,9 +184,9 @@ type LLMRequestCost struct {
 MetadataKey string `json:"metadataKey"`
 // Type is the kind of the request cost calculation.
 Type LLMRequestCostType `json:"type"`
-// CELExpression is the CEL expression to calculate the cost of the request.
-// This is not empty when the Type is LLMRequestCostTypeCELExpression.
-CELExpression string `json:"celExpression,omitempty"`
+// CEL is the CEL expression to calculate the cost of the request.
+// This is not empty when the Type is LLMRequestCostTypeCEL.
+CEL string `json:"cel,omitempty"`
 }
 ```
 

docs/proposals/001-ai-gateway-proposal/proposal.md

@@ -1 +1 @@
-This example shows how to insert a custom router in the custom external process using `filterapi` package.
+This example shows how to insert a custom router in the custom external processor using `filterapi` package.

examples/extproc_custom_router/README.md

@@ -55,7 +55,7 @@ spec:
     # otherwise it returns 0 (no token usage).
     - metadataKey: llm_cel_calculated_token
       type: CEL
-      celExpression: "input_tokens == uint(3) ? 100000000 : 0"
+      cel: "input_tokens == uint(3) ? 100000000 : 0"
 ---
 apiVersion: aigateway.envoyproxy.io/v1alpha1
 kind: AIServiceBackend

examples/token_ratelimit/token_ratelimit.yaml

@@ -102,9 +102,9 @@ type LLMRequestCost struct {
 	MetadataKey string `json:"metadataKey"`
 	// Type is the kind of the request cost calculation.
 	Type LLMRequestCostType `json:"type"`
-	// CELExpression is the CEL expression to calculate the cost of the request.
-	// This is not empty when the Type is LLMRequestCostTypeCELExpression.
-	CELExpression string `json:"celExpression,omitempty"`
+	// CEL is the CEL expression to calculate the cost of the request.
+	// This is not empty when the Type is LLMRequestCostTypeCEL.
+	CEL string `json:"cel,omitempty"`
 }
 
 // LLMRequestCostType specifies the kind of the request cost calculation.
@@ -117,8 +117,8 @@ const (
 	LLMRequestCostTypeInputToken LLMRequestCostType = "InputToken"
 	// LLMRequestCostTypeTotalToken specifies that the request cost is calculated from the total token.
 	LLMRequestCostTypeTotalToken LLMRequestCostType = "TotalToken"
-	// LLMRequestCostTypeCELExpression specifies that the request cost is calculated from the CEL expression.
-	LLMRequestCostTypeCELExpression LLMRequestCostType = "CEL"
+	// LLMRequestCostTypeCEL specifies that the request cost is calculated from the CEL expression.
+	LLMRequestCostTypeCEL LLMRequestCostType = "CEL"
 )
 
 // VersionedAPISchema corresponds to VersionedAPISchema in api/v1alpha1/api.go.

filterapi/filterconfig.go

@@ -154,7 +154,7 @@ func (c *AIGatewayRouteController) reconcileExtProcExtensionPolicy(ctx context.C
 }
 
 // ensuresExtProcConfigMapExists ensures that a configmap exists for the external process.
-// This must happen before the external process deployment is created.
+// This must happen before the external processor deployment is created.
 func (c *AIGatewayRouteController) ensuresExtProcConfigMapExists(ctx context.Context, aiGatewayRoute *aigv1a1.AIGatewayRoute) (err error) {
 	name := extProcName(aiGatewayRoute)
 	// Check if a configmap exists for extproc exists, and if not, create one with the default config.
@@ -180,10 +180,10 @@ func extProcName(route *aigv1a1.AIGatewayRoute) string {
 }
 
 func applyExtProcDeploymentConfigUpdate(d *appsv1.DeploymentSpec, filterConfig *aigv1a1.AIGatewayFilterConfig) {
-	if filterConfig == nil || filterConfig.ExternalProcess == nil {
+	if filterConfig == nil || filterConfig.ExternalProcessor == nil {
 		return
 	}
-	extProc := filterConfig.ExternalProcess
+	extProc := filterConfig.ExternalProcessor
 	if resource := extProc.Resources; resource != nil {
 		d.Template.Spec.Containers[0].Resources = *resource
 	}
@@ -277,7 +277,7 @@ func (c *AIGatewayRouteController) syncAIGatewayRoute(ctx context.Context, aiGat
 	return nil
 }
 
-// updateExtProcConfigMap updates the external process configmap with the new AIGatewayRoute.
+// updateExtProcConfigMap updates the external processor configmap with the new AIGatewayRoute.
 func (c *AIGatewayRouteController) updateExtProcConfigMap(ctx context.Context, aiGatewayRoute *aigv1a1.AIGatewayRoute, uuid string) error {
 	configMap, err := c.kube.CoreV1().ConfigMaps(aiGatewayRoute.Namespace).Get(ctx, extProcName(aiGatewayRoute), metav1.GetOptions{})
 	if err != nil {
@@ -360,14 +360,14 @@ func (c *AIGatewayRouteController) updateExtProcConfigMap(ctx context.Context, a
 		case aigv1a1.LLMRequestCostTypeTotalToken:
 			fc.Type = filterapi.LLMRequestCostTypeTotalToken
 		case aigv1a1.LLMRequestCostTypeCEL:
-			fc.Type = filterapi.LLMRequestCostTypeCELExpression
-			expr := *cost.CELExpression
+			fc.Type = filterapi.LLMRequestCostTypeCEL
+			expr := *cost.CEL
 			// Sanity check the CEL expression.
 			_, err = llmcostcel.NewProgram(expr)
 			if err != nil {
 				return fmt.Errorf("invalid CEL expression: %w", err)
 			}
-			fc.CELExpression = expr
+			fc.CEL = expr
 		default:
 			return fmt.Errorf("unknown request cost type: %s", cost.Type)
 		}

internal/controller/ai_gateway_route.go

@@ -173,7 +173,7 @@ func Test_applyExtProcDeploymentConfigUpdate(t *testing.T) {
 		applyExtProcDeploymentConfigUpdate(dep, nil)
 		applyExtProcDeploymentConfigUpdate(dep, &aigv1a1.AIGatewayFilterConfig{})
 		applyExtProcDeploymentConfigUpdate(dep, &aigv1a1.AIGatewayFilterConfig{
-			ExternalProcess: &aigv1a1.AIGatewayFilterConfigExternalProcess{},
+			ExternalProcessor: &aigv1a1.AIGatewayFilterConfigExternalProcessor{},
 		})
 	})
 	t.Run("update", func(t *testing.T) {
@@ -184,7 +184,7 @@ func Test_applyExtProcDeploymentConfigUpdate(t *testing.T) {
 			},
 		}
 		applyExtProcDeploymentConfigUpdate(dep, &aigv1a1.AIGatewayFilterConfig{
-			ExternalProcess: &aigv1a1.AIGatewayFilterConfigExternalProcess{
+			ExternalProcessor: &aigv1a1.AIGatewayFilterConfigExternalProcessor{
 				Resources: &req,
 				Replicas:  ptr.To[int32](123),
 			},
@@ -535,9 +535,9 @@ func TestAIGatewayRouteController_updateExtProcConfigMap(t *testing.T) {
 							MetadataKey: "total-token",
 						},
 						{
-							Type:          aigv1a1.LLMRequestCostTypeCEL,
-							MetadataKey:   "cel-token",
-							CELExpression: ptr.To("model == 'cool_model' ?  input_tokens * output_tokens : total_tokens"),
+							Type:        aigv1a1.LLMRequestCostTypeCEL,
+							MetadataKey: "cel-token",
+							CEL:         ptr.To("model == 'cool_model' ?  input_tokens * output_tokens : total_tokens"),
 						},
 					},
 				},
@@ -590,7 +590,7 @@ func TestAIGatewayRouteController_updateExtProcConfigMap(t *testing.T) {
 					{Type: filterapi.LLMRequestCostTypeOutputToken, MetadataKey: "output-token"},
 					{Type: filterapi.LLMRequestCostTypeInputToken, MetadataKey: "input-token"},
 					{Type: filterapi.LLMRequestCostTypeTotalToken, MetadataKey: "total-token"},
-					{Type: filterapi.LLMRequestCostTypeCELExpression, MetadataKey: "cel-token", CELExpression: "model == 'cool_model' ?  input_tokens * output_tokens : total_tokens"},
+					{Type: filterapi.LLMRequestCostTypeCEL, MetadataKey: "cel-token", CEL: "model == 'cool_model' ?  input_tokens * output_tokens : total_tokens"},
 				},
 			},
 		},
@@ -675,8 +675,8 @@ func TestAIGatewayRouteController_syncExtProcDeployment(t *testing.T) {
 		},
 		Spec: aigv1a1.AIGatewayRouteSpec{
 			FilterConfig: &aigv1a1.AIGatewayFilterConfig{
-				Type: aigv1a1.AIGatewayFilterConfigTypeExternalProcess,
-				ExternalProcess: &aigv1a1.AIGatewayFilterConfigExternalProcess{
+				Type: aigv1a1.AIGatewayFilterConfigTypeExternalProcessor,
+				ExternalProcessor: &aigv1a1.AIGatewayFilterConfigExternalProcessor{
 					Replicas: ptr.To[int32](123),
 					Resources: &corev1.ResourceRequirements{
 						Limits: corev1.ResourceList{
@@ -755,8 +755,8 @@ func TestAIGatewayRouteController_syncExtProcDeployment(t *testing.T) {
 				corev1.ResourceMemory: resource.MustParse("32Mi"),
 			},
 		}
-		aiGatewayRoute.Spec.FilterConfig.ExternalProcess.Resources = newResourceLimits
-		aiGatewayRoute.Spec.FilterConfig.ExternalProcess.Replicas = ptr.To[int32](456)
+		aiGatewayRoute.Spec.FilterConfig.ExternalProcessor.Resources = newResourceLimits
+		aiGatewayRoute.Spec.FilterConfig.ExternalProcessor.Replicas = ptr.To[int32](456)
 
 		require.NoError(t, s.syncExtProcDeployment(t.Context(), aiGatewayRoute))
 		// Check the deployment is updated.

internal/controller/ai_gateway_route_test.go

@@ -219,7 +219,7 @@ func (c *chatCompletionProcessor) maybeBuildDynamicMetadata() (*structpb.Struct,
 			cost = c.costs.OutputTokens
 		case filterapi.LLMRequestCostTypeTotalToken:
 			cost = c.costs.TotalTokens
-		case filterapi.LLMRequestCostTypeCELExpression:
+		case filterapi.LLMRequestCostTypeCEL:
 			costU64, err := llmcostcel.EvaluateProgram(
 				rc.celProg,
 				c.requestHeaders[c.config.modelNameHeaderKey],

internal/extproc/chatcompletion_processor.go

@@ -114,11 +114,11 @@ func TestChatCompletion_ProcessResponseBody(t *testing.T) {
 				{LLMRequestCost: &filterapi.LLMRequestCost{Type: filterapi.LLMRequestCostTypeInputToken, MetadataKey: "input_token_usage"}},
 				{
 					celProg:        celProgInt,
-					LLMRequestCost: &filterapi.LLMRequestCost{Type: filterapi.LLMRequestCostTypeCELExpression, MetadataKey: "cel_int"},
+					LLMRequestCost: &filterapi.LLMRequestCost{Type: filterapi.LLMRequestCostTypeCEL, MetadataKey: "cel_int"},
 				},
 				{
 					celProg:        celProgUint,
-					LLMRequestCost: &filterapi.LLMRequestCost{Type: filterapi.LLMRequestCostTypeCELExpression, MetadataKey: "cel_uint"},
+					LLMRequestCost: &filterapi.LLMRequestCost{Type: filterapi.LLMRequestCostTypeCEL, MetadataKey: "cel_uint"},
 				},
 			},
 		}}

internal/extproc/chatcompletion_processor_test.go

@@ -36,7 +36,7 @@ const (
 
 var sensitiveHeaderKeys = []string{"authorization"}
 
-// Server implements the external process server.
+// Server implements the external processor server.
 type Server struct {
 	logger     *slog.Logger
 	config     *processorConfig
@@ -90,8 +90,8 @@ func (s *Server) LoadConfig(ctx context.Context, config *filterapi.Config) error
 	for i := range config.LLMRequestCosts {
 		c := &config.LLMRequestCosts[i]
 		var prog cel.Program
-		if c.CELExpression != "" {
-			prog, err = llmcostcel.NewProgram(c.CELExpression)
+		if c.CEL != "" {
+			prog, err = llmcostcel.NewProgram(c.CEL)
 			if err != nil {
 				return fmt.Errorf("cannot create CEL program for cost: %w", err)
 			}

internal/extproc/server.go

@@ -42,7 +42,7 @@ func TestServer_LoadConfig(t *testing.T) {
 			MetadataNamespace: "ns",
 			LLMRequestCosts: []filterapi.LLMRequestCost{
 				{MetadataKey: "key", Type: filterapi.LLMRequestCostTypeOutputToken},
-				{MetadataKey: "cel_key", Type: filterapi.LLMRequestCostTypeCELExpression, CELExpression: "1 + 1"},
+				{MetadataKey: "cel_key", Type: filterapi.LLMRequestCostTypeCEL, CEL: "1 + 1"},
 			},
 			Schema:                   filterapi.VersionedAPISchema{Name: filterapi.APISchemaOpenAI},
 			SelectedBackendHeaderKey: "x-ai-eg-selected-backend",
@@ -87,8 +87,8 @@ func TestServer_LoadConfig(t *testing.T) {
 		require.Len(t, s.config.requestCosts, 2)
 		require.Equal(t, filterapi.LLMRequestCostTypeOutputToken, s.config.requestCosts[0].Type)
 		require.Equal(t, "key", s.config.requestCosts[0].MetadataKey)
-		require.Equal(t, filterapi.LLMRequestCostTypeCELExpression, s.config.requestCosts[1].Type)
-		require.Equal(t, "1 + 1", s.config.requestCosts[1].CELExpression)
+		require.Equal(t, filterapi.LLMRequestCostTypeCEL, s.config.requestCosts[1].Type)
+		require.Equal(t, "1 + 1", s.config.requestCosts[1].CEL)
 		prog := s.config.requestCosts[1].celProg
 		require.NotNil(t, prog)
 		val, err := llmcostcel.EvaluateProgram(prog, "", "", 1, 1, 1)