Refactor(ai): replace dynamic metadata maps (refactor/ai-typed-metadata) (#28)

Author: KariHall619

pkg/ai/capabilities.go

@@ -38,14 +38,24 @@ type CapabilitiesRequest struct {
 
 // CapabilitiesResponse defines the complete capability information for the AI plugin
 type CapabilitiesResponse struct {
-	Version     string                 `json:"version"`
-	Models      []ModelCapability      `json:"models"`
-	Databases   []DatabaseCapability   `json:"databases"`
-	Features    []FeatureCapability    `json:"features"`
-	Health      HealthStatusReport     `json:"health"`
-	Limits      ResourceLimits         `json:"limits"`
-	LastUpdated time.Time              `json:"last_updated"`
-	Metadata    map[string]interface{} `json:"metadata,omitempty"`
+	Version     string               `json:"version"`
+	Models      []ModelCapability    `json:"models"`
+	Databases   []DatabaseCapability `json:"databases"`
+	Features    []FeatureCapability  `json:"features"`
+	Health      HealthStatusReport   `json:"health"`
+	Limits      ResourceLimits       `json:"limits"`
+	LastUpdated time.Time            `json:"last_updated"`
+	Metadata    CapabilityMetadata   `json:"metadata"`
+}
+
+// CapabilityMetadata provides contextual information about the response.
+type CapabilityMetadata struct {
+	CacheStatus   string    `json:"cache_status"`
+	Source        string    `json:"source"`
+	ModelCount    int       `json:"model_count"`
+	FeatureCount  int       `json:"feature_count"`
+	HealthChecked bool      `json:"health_checked"`
+	GeneratedAt   time.Time `json:"generated_at"`
 }
 
 // ModelCapability represents the capabilities of an AI model
@@ -206,10 +216,17 @@ func (d *CapabilityDetector) GetCapabilities(ctx context.Context, req *Capabilit
 	}
 
 	// Build fresh capability response
+	now := time.Now()
+	metadata := CapabilityMetadata{
+		CacheStatus:   "miss",
+		Source:        "live",
+		HealthChecked: req.CheckHealth,
+		GeneratedAt:   now,
+	}
 	response := &CapabilitiesResponse{
 		Version:     "1.0.0",
-		LastUpdated: time.Now(),
-		Metadata:    make(map[string]interface{}),
+		LastUpdated: now,
+		Metadata:    metadata,
 	}
 
 	// Collect models if requested
@@ -219,6 +236,7 @@ func (d *CapabilityDetector) GetCapabilities(ctx context.Context, req *Capabilit
 			return nil, fmt.Errorf("failed to detect model capabilities: %w", err)
 		}
 		response.Models = models
+		metadata.ModelCount = len(models)
 	}
 
 	// Collect database capabilities if requested
@@ -228,7 +246,9 @@ func (d *CapabilityDetector) GetCapabilities(ctx context.Context, req *Capabilit
 
 	// Collect feature capabilities if requested
 	if req.IncludeFeatures {
-		response.Features = d.detectFeatureCapabilities()
+		features := d.detectFeatureCapabilities()
+		response.Features = features
+		metadata.FeatureCount = len(features)
 	}
 
 	// Perform health checks if requested
@@ -243,6 +263,9 @@ func (d *CapabilityDetector) GetCapabilities(ctx context.Context, req *Capabilit
 	// Always include resource limits
 	response.Limits = d.getResourceLimits()
 
+	// Attach finalized metadata snapshot
+	response.Metadata = metadata
+
 	// Update cache
 	d.cache.update(response)
 	d.lastUpdate = time.Now()
@@ -646,10 +669,13 @@ func (d *CapabilityDetector) getCachedCapabilities(req *CapabilitiesRequest) (*C
 	}
 
 	// Create a filtered response based on request
+	metadata := d.cache.data.Metadata
+	metadata.HealthChecked = req.CheckHealth
+
 	response := &CapabilitiesResponse{
 		Version:     d.cache.data.Version,
 		LastUpdated: d.cache.data.LastUpdated,
-		Metadata:    d.cache.data.Metadata,
+		Metadata:    metadata,
 	}
 
 	if req.IncludeModels {

pkg/ai/manager.go

@@ -51,6 +51,12 @@ var (
 	ErrInvalidConfig = errors.New("invalid configuration")
 )
 
+// ProviderConfigInfo captures metadata about a provider's requirements.
+type ProviderConfigInfo struct {
+	RequiresAPIKey bool   `json:"requires_api_key"`
+	ProviderType   string `json:"provider_type"`
+}
+
 // ProviderInfo represents information about an AI provider
 type ProviderInfo struct {
 	Name        string                   `json:"name"`
@@ -59,7 +65,7 @@ type ProviderInfo struct {
 	Endpoint    string                   `json:"endpoint"`
 	Models      []interfaces.ModelInfo   `json:"models"`
 	LastChecked time.Time                `json:"last_checked"`
-	Config      map[string]interface{}   `json:"config,omitempty"`
+	Config      ProviderConfigInfo       `json:"config"`
 	Health      *interfaces.HealthStatus `json:"health,omitempty"`
 }
 
@@ -360,6 +366,10 @@ func (m *Manager) DiscoverProviders(ctx context.Context) ([]*ProviderInfo, error
 				Endpoint:    endpoint,
 				Models:      models,
 				LastChecked: time.Now(),
+				Config: ProviderConfigInfo{
+					ProviderType:   "local",
+					RequiresAPIKey: false,
+				},
 			}
 
 			providers = append(providers, provider)
@@ -630,9 +640,9 @@ func (m *Manager) getOnlineProviders() []*ProviderInfo {
 			Endpoint:    entry.Endpoint,
 			Models:      entry.Models,
 			LastChecked: time.Now(),
-			Config: map[string]interface{}{
-				"requires_api_key": entry.RequiresAPIKey,
-				"provider_type":    providerType,
+			Config: ProviderConfigInfo{
+				RequiresAPIKey: entry.RequiresAPIKey,
+				ProviderType:   providerType,
 			},
 		})
 	}

pkg/plugin/service.go

@@ -229,30 +229,12 @@ func (s *AIPluginService) defaultDatabaseType() string {
 	return "mysql"
 }
 
-func extractDatabaseTypeFromMap(values map[string]any) string {
-	if values == nil {
-		return ""
-	}
-
-	keys := []string{"database_type", "databaseDialect", "database_dialect", "dialect"}
-	for _, key := range keys {
-		if raw, ok := values[key]; ok {
-			if str, ok := raw.(string); ok {
-				if normalized := normalizeDatabaseType(str); normalized != "" {
-					return normalized
-				}
-			}
-		}
-	}
-	return ""
-}
-
-func (s *AIPluginService) resolveDatabaseType(explicit string, configMap map[string]any) string {
+func (s *AIPluginService) resolveDatabaseType(explicit string, overrides GenerationConfigOverrides) string {
 	if normalized := normalizeDatabaseType(explicit); normalized != "" {
 		return normalized
 	}
 
-	if fromConfig := extractDatabaseTypeFromMap(configMap); fromConfig != "" {
+	if fromConfig := overrides.preferredDatabaseType(); fromConfig != "" {
 		return fromConfig
 	}
 
@@ -703,6 +685,45 @@ var (
 	MinCompatibleAPITestingVersion = GRPCInterfaceVersion
 )
 
+// GenerationMetadata describes metadata returned with AI generation responses.
+type GenerationMetadata struct {
+	Confidence float32 `json:"confidence"`
+	Model      string  `json:"model,omitempty"`
+	Dialect    string  `json:"dialect"`
+}
+
+// CapabilitySummary is returned when the capability detector is unavailable.
+type CapabilitySummary struct {
+	PluginReady   bool   `json:"plugin_ready"`
+	AIAvailable   bool   `json:"ai_available"`
+	DegradedMode  bool   `json:"degraded_mode"`
+	PluginVersion string `json:"plugin_version"`
+	APIVersion    string `json:"api_version"`
+}
+
+// GenerationConfigOverrides captures optional generation configuration overrides.
+type GenerationConfigOverrides struct {
+	DatabaseTypePrimary string `json:"database_type"`
+	DatabaseDialect     string `json:"databaseDialect"`
+	DatabaseDialectAlt  string `json:"database_dialect"`
+	Dialect             string `json:"dialect"`
+}
+
+func (g GenerationConfigOverrides) preferredDatabaseType() string {
+	candidates := []string{
+		g.DatabaseTypePrimary,
+		g.DatabaseDialect,
+		g.DatabaseDialectAlt,
+		g.Dialect,
+	}
+	for _, candidate := range candidates {
+		if normalized := normalizeDatabaseType(candidate); normalized != "" {
+			return normalized
+		}
+	}
+	return ""
+}
+
 // handleAIGenerate handles ai.generate calls
 func (s *AIPluginService) handleAIGenerate(ctx context.Context, req *server.DataQuery) (*server.DataQueryResult, error) {
 	start := time.Now()
@@ -732,9 +753,9 @@ func (s *AIPluginService) handleAIGenerate(ctx context.Context, req *server.Data
 	}
 
 	// Parse optional config
-	var configMap map[string]interface{}
+	var generationOverrides GenerationConfigOverrides
 	if params.Config != "" {
-		if err := json.Unmarshal([]byte(params.Config), &configMap); err != nil {
+		if err := json.Unmarshal([]byte(params.Config), &generationOverrides); err != nil {
 			logging.Logger.Warn("Failed to parse config JSON", "error", err)
 		}
 	}
@@ -757,7 +778,7 @@ func (s *AIPluginService) handleAIGenerate(ctx context.Context, req *server.Data
 	}
 
 	// Get database type from configuration, fallback to mysql if not configured
-	databaseType := s.resolveDatabaseType(params.DatabaseType, configMap)
+	databaseType := s.resolveDatabaseType(params.DatabaseType, generationOverrides)
 	context["database_type"] = databaseType
 
 	sqlResult, err := s.aiEngine.GenerateSQL(ctx, &ai.GenerateSQLRequest{
@@ -790,12 +811,12 @@ func (s *AIPluginService) handleAIGenerate(ctx context.Context, req *server.Data
 	simpleFormat := fmt.Sprintf("sql:%s\nexplanation:%s", sqlResult.SQL, sqlResult.Explanation)
 
 	// Build minimal meta information for UI display
-	metaData := map[string]interface{}{
-		"confidence": sqlResult.ConfidenceScore,
-		"model":      sqlResult.ModelUsed,
-		"dialect":    databaseType,
+	meta := GenerationMetadata{
+		Confidence: sqlResult.ConfidenceScore,
+		Model:      sqlResult.ModelUsed,
+		Dialect:    databaseType,
 	}
-	metaJSON, err := json.Marshal(metaData)
+	metaJSON, err := json.Marshal(meta)
 	if err != nil {
 		metaJSON = []byte(fmt.Sprintf(`{"confidence": %f, "model": "%s"}`,
 			sqlResult.ConfidenceScore, sqlResult.ModelUsed))
@@ -851,14 +872,14 @@ func (s *AIPluginService) handleAICapabilities(ctx context.Context, req *server.
 	if s.capabilityDetector == nil {
 		logging.Logger.Warn("Capability detector not available - returning minimal capabilities")
 		// Return minimal capabilities when detector is not available
-		minimalCaps := map[string]interface{}{
-			"plugin_ready":   true,
-			"ai_available":   false,
-			"degraded_mode":  true,
-			"plugin_version": PluginVersion,
-			"api_version":    APIVersion,
+		fallback := CapabilitySummary{
+			PluginReady:   true,
+			AIAvailable:   false,
+			DegradedMode:  true,
+			PluginVersion: PluginVersion,
+			APIVersion:    APIVersion,
 		}
-		capsJSON, _ := json.Marshal(minimalCaps)
+		capsJSON, _ := json.Marshal(fallback)
 		return &server.DataQueryResult{
 			Data: []*server.Pair{
 				{Key: "api_version", Value: APIVersion},
@@ -1102,12 +1123,12 @@ func (s *AIPluginService) handleLegacyQuery(ctx context.Context, req *server.Dat
 	simpleFormat := fmt.Sprintf("sql:%s\nexplanation:%s", sqlResult.SQL, sqlResult.Explanation)
 
 	// Build minimal meta information for UI display
-	metaData := map[string]interface{}{
-		"confidence": sqlResult.ConfidenceScore,
-		"model":      sqlResult.ModelUsed,
-		"dialect":    databaseType,
+	meta := GenerationMetadata{
+		Confidence: sqlResult.ConfidenceScore,
+		Model:      sqlResult.ModelUsed,
+		Dialect:    databaseType,
 	}
-	metaJSON, err := json.Marshal(metaData)
+	metaJSON, err := json.Marshal(meta)
 	if err != nil {
 		metaJSON = []byte(fmt.Sprintf(`{"confidence": %f, "model": "%s"}`,
 			sqlResult.ConfidenceScore, sqlResult.ModelUsed))

pkg/plugin/service_test.go

@@ -400,19 +400,19 @@ func TestResolveDatabaseType(t *testing.T) {
 	}
 
 	t.Run("uses explicit value when provided", func(t *testing.T) {
-		assert.Equal(t, "mysql", svc.resolveDatabaseType("mysql", nil))
+		assert.Equal(t, "mysql", svc.resolveDatabaseType("mysql", GenerationConfigOverrides{}))
 	})
 
 	t.Run("normalizes postgres aliases", func(t *testing.T) {
-		assert.Equal(t, "postgresql", svc.resolveDatabaseType("pg", nil))
+		assert.Equal(t, "postgresql", svc.resolveDatabaseType("pg", GenerationConfigOverrides{}))
 	})
 
 	t.Run("falls back to config default", func(t *testing.T) {
-		assert.Equal(t, "postgresql", svc.resolveDatabaseType("", nil))
+		assert.Equal(t, "postgresql", svc.resolveDatabaseType("", GenerationConfigOverrides{}))
 	})
 
 	t.Run("uses config map overrides", func(t *testing.T) {
-		configMap := map[string]any{"database_dialect": "sqlite3"}
-		assert.Equal(t, "sqlite", svc.resolveDatabaseType("", configMap))
+		overrides := GenerationConfigOverrides{DatabaseDialectAlt: "sqlite3"}
+		assert.Equal(t, "sqlite", svc.resolveDatabaseType("", overrides))
 	})
 }