Add task_type validation and API discovery endpoint

- Add validateTaskType helper function to validate task_type parameter
- Reject invalid task_type values with 400 error and helpful message
- Add GET /api/v1 endpoint for API discovery
- Return comprehensive API overview with endpoints, task_types, and links
- Add tests for invalid task_type values (jailbreak, invalid_type)
- Add tests for valid task_types (intent, pii, security, all)
- Add test for API overview endpoint

Co-authored-by: rootfs <[email protected]>

Author: Copilot

src/semantic-router/pkg/api/server.go

@@ -184,6 +184,9 @@ func (s *ClassificationAPIServer) setupRoutes() *http.ServeMux {
 	// Health check endpoint
 	mux.HandleFunc("GET /health", s.handleHealth)
 
+	// API discovery endpoint
+	mux.HandleFunc("GET /api/v1", s.handleAPIOverview)
+
 	// Classification endpoints
 	mux.HandleFunc("POST /api/v1/classify/intent", s.handleIntentClassification)
 	mux.HandleFunc("POST /api/v1/classify/pii", s.handlePIIDetection)
@@ -224,6 +227,105 @@ func (s *ClassificationAPIServer) handleHealth(w http.ResponseWriter, r *http.Re
 	w.Write([]byte(`{"status": "healthy", "service": "classification-api"}`))
 }
 
+// APIOverviewResponse represents the response for GET /api/v1
+type APIOverviewResponse struct {
+	Service     string            `json:"service"`
+	Version     string            `json:"version"`
+	Description string            `json:"description"`
+	Endpoints   []EndpointInfo    `json:"endpoints"`
+	TaskTypes   []TaskTypeInfo    `json:"task_types"`
+	Links       map[string]string `json:"links"`
+}
+
+// EndpointInfo represents information about an API endpoint
+type EndpointInfo struct {
+	Path        string `json:"path"`
+	Method      string `json:"method"`
+	Description string `json:"description"`
+}
+
+// TaskTypeInfo represents information about a task type
+type TaskTypeInfo struct {
+	Name        string `json:"name"`
+	Description string `json:"description"`
+}
+
+// handleAPIOverview handles GET /api/v1 for API discovery
+func (s *ClassificationAPIServer) handleAPIOverview(w http.ResponseWriter, r *http.Request) {
+	response := APIOverviewResponse{
+		Service:     "Semantic Router Classification API",
+		Version:     "v1",
+		Description: "API for intent classification, PII detection, and security analysis",
+		Endpoints: []EndpointInfo{
+			{
+				Path:        "/api/v1/classify/intent",
+				Method:      "POST",
+				Description: "Classify user queries into routing categories",
+			},
+			{
+				Path:        "/api/v1/classify/pii",
+				Method:      "POST",
+				Description: "Detect personally identifiable information in text",
+			},
+			{
+				Path:        "/api/v1/classify/security",
+				Method:      "POST",
+				Description: "Detect jailbreak attempts and security threats",
+			},
+			{
+				Path:        "/api/v1/classify/combined",
+				Method:      "POST",
+				Description: "Perform combined classification (intent, PII, and security)",
+			},
+			{
+				Path:        "/api/v1/classify/batch",
+				Method:      "POST",
+				Description: "Batch classification with configurable task_type parameter",
+			},
+			{
+				Path:        "/health",
+				Method:      "GET",
+				Description: "Health check endpoint",
+			},
+			{
+				Path:        "/info/models",
+				Method:      "GET",
+				Description: "Get information about loaded models",
+			},
+			{
+				Path:        "/v1/models",
+				Method:      "GET",
+				Description: "OpenAI-compatible model listing",
+			},
+		},
+		TaskTypes: []TaskTypeInfo{
+			{
+				Name:        "intent",
+				Description: "Intent/category classification (default for batch endpoint)",
+			},
+			{
+				Name:        "pii",
+				Description: "Personally Identifiable Information detection",
+			},
+			{
+				Name:        "security",
+				Description: "Jailbreak and security threat detection",
+			},
+			{
+				Name:        "all",
+				Description: "All classification types combined",
+			},
+		},
+		Links: map[string]string{
+			"documentation": "https://vllm-project.github.io/semantic-router/",
+			"models_info":   "/info/models",
+			"health":        "/health",
+		},
+	}
+
+	s.writeJSONResponse(w, http.StatusOK, response)
+}
+
 // handleIntentClassification handles intent classification requests
 func (s *ClassificationAPIServer) handleIntentClassification(w http.ResponseWriter, r *http.Request) {
 	var req services.IntentRequest
@@ -335,6 +437,13 @@ func (s *ClassificationAPIServer) handleBatchClassification(w http.ResponseWrite
 		return
 	}
 
+	// Validate task_type if provided
+	if err := validateTaskType(req.TaskType); err != nil {
+		metrics.RecordBatchClassificationError("unified", "invalid_task_type")
+		s.writeErrorResponse(w, http.StatusBadRequest, "INVALID_TASK_TYPE", err.Error())
+		return
+	}
+
 	// Record the number of texts being processed
 	metrics.RecordBatchClassificationTexts("unified", len(req.Texts))
 
@@ -622,6 +731,24 @@ func (s *ClassificationAPIServer) getSystemInfo() SystemInfo {
 	}
 }
 
+// validateTaskType validates the task_type parameter for batch classification
+// Returns an error if the task_type is invalid, nil if valid or empty
+func validateTaskType(taskType string) error {
+	// Empty task_type defaults to "intent", so it's valid
+	if taskType == "" {
+		return nil
+	}
+
+	validTaskTypes := []string{"intent", "pii", "security", "all"}
+	for _, valid := range validTaskTypes {
+		if taskType == valid {
+			return nil
+		}
+	}
+
+	return fmt.Errorf("invalid task_type '%s'. Supported values: %v", taskType, validTaskTypes)
+}
+
 // extractRequestedResults converts unified results to batch format based on task type
 func (s *ClassificationAPIServer) extractRequestedResults(unifiedResults *services.UnifiedBatchResponse, taskType string, options *ClassificationOptions) []BatchClassificationResult {
 	// Determine the correct batch size based on task type

src/semantic-router/pkg/api/server_test.go

@@ -34,6 +34,59 @@ func TestHandleBatchClassification(t *testing.T) {
 			expectedStatus: http.StatusServiceUnavailable,
 			expectedError:  "Batch classification requires unified classifier. Please ensure models are available in ./models/ directory.",
 		},
+		{
+			name: "Invalid task_type - jailbreak",
+			requestBody: `{
+				"texts": ["test text"],
+				"task_type": "jailbreak"
+			}`,
+			expectedStatus: http.StatusBadRequest,
+			expectedError:  "invalid task_type 'jailbreak'. Supported values: [intent pii security all]",
+		},
+		{
+			name: "Invalid task_type - random",
+			requestBody: `{
+				"texts": ["test text"],
+				"task_type": "invalid_type"
+			}`,
+			expectedStatus: http.StatusBadRequest,
+			expectedError:  "invalid task_type 'invalid_type'. Supported values: [intent pii security all]",
+		},
+		{
+			name: "Valid task_type - pii",
+			requestBody: `{
+				"texts": ["test text"],
+				"task_type": "pii"
+			}`,
+			expectedStatus: http.StatusServiceUnavailable,
+			expectedError:  "Batch classification requires unified classifier. Please ensure models are available in ./models/ directory.",
+		},
+		{
+			name: "Valid task_type - security",
+			requestBody: `{
+				"texts": ["test text"],
+				"task_type": "security"
+			}`,
+			expectedStatus: http.StatusServiceUnavailable,
+			expectedError:  "Batch classification requires unified classifier. Please ensure models are available in ./models/ directory.",
+		},
+		{
+			name: "Valid task_type - all",
+			requestBody: `{
+				"texts": ["test text"],
+				"task_type": "all"
+			}`,
+			expectedStatus: http.StatusServiceUnavailable,
+			expectedError:  "Batch classification requires unified classifier. Please ensure models are available in ./models/ directory.",
+		},
+		{
+			name: "Empty task_type defaults to intent",
+			requestBody: `{
+				"texts": ["test text"]
+			}`,
+			expectedStatus: http.StatusServiceUnavailable,
+			expectedError:  "Batch classification requires unified classifier. Please ensure models are available in ./models/ directory.",
+		},
 		{
 			name: "Valid large batch",
 			requestBody: func() string {
@@ -731,3 +784,84 @@ func TestSetupRoutesSecurityBehavior(t *testing.T) {
 		})
 	}
 }
+
+// TestAPIOverviewEndpoint tests the API discovery endpoint
+func TestAPIOverviewEndpoint(t *testing.T) {
+	apiServer := &ClassificationAPIServer{
+		classificationSvc: services.NewPlaceholderClassificationService(),
+		config:            &config.RouterConfig{},
+	}
+
+	req := httptest.NewRequest("GET", "/api/v1", nil)
+	rr := httptest.NewRecorder()
+
+	apiServer.handleAPIOverview(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("Expected 200 OK, got %d", rr.Code)
+	}
+
+	var response APIOverviewResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &response); err != nil {
+		t.Fatalf("Failed to unmarshal response: %v", err)
+	}
+
+	// Verify the response structure
+	if response.Service == "" {
+		t.Error("Expected non-empty service name")
+	}
+
+	if response.Version != "v1" {
+		t.Errorf("Expected version 'v1', got '%s'", response.Version)
+	}
+
+	// Check that we have endpoints listed
+	if len(response.Endpoints) == 0 {
+		t.Error("Expected at least one endpoint")
+	}
+
+	// Check that we have task types listed
+	expectedTaskTypes := map[string]bool{
+		"intent":   false,
+		"pii":      false,
+		"security": false,
+		"all":      false,
+	}
+
+	for _, taskType := range response.TaskTypes {
+		if _, exists := expectedTaskTypes[taskType.Name]; exists {
+			expectedTaskTypes[taskType.Name] = true
+		}
+	}
+
+	for taskType, found := range expectedTaskTypes {
+		if !found {
+			t.Errorf("Expected to find task_type '%s' in response", taskType)
+		}
+	}
+
+	// Check that we have links
+	if len(response.Links) == 0 {
+		t.Error("Expected at least one link")
+	}
+
+	// Verify specific endpoints are present
+	endpointPaths := make(map[string]bool)
+	for _, endpoint := range response.Endpoints {
+		endpointPaths[endpoint.Path] = true
+	}
+
+	requiredPaths := []string{
+		"/api/v1/classify/intent",
+		"/api/v1/classify/pii",
+		"/api/v1/classify/security",
+		"/api/v1/classify/batch",
+		"/health",
+	}
+
+	for _, path := range requiredPaths {
+		if !endpointPaths[path] {
+			t.Errorf("Expected to find endpoint '%s' in response", path)
+		}
+	}
+}