feat: add XAI explanation models for enhanced interpretability in analysis results

app/routes/analyze.py

@@ -122,6 +122,47 @@ class AudioInfo(BaseModel):
     sampleRate: int = 44100
     bitrate: int = 128
     format: str = "unknown"
+    channels: int = 2
+
+
+class ConfidenceBandModel(BaseModel):
+    tier: str
+    labelTr: str
+    labelEn: str
+    lowerBound: float
+    upperBound: float
+
+
+class ModelVoteModel(BaseModel):
+    name: str
+    probability: float
+    vote: str
+
+
+class FeatureContributionModel(BaseModel):
+    name: str
+    label: str
+    labelEn: str
+    category: str
+    value: float
+    zScore: float
+    shapValue: float
+    direction: str
+    description: str
+
+
+class XAIExplanation(BaseModel):
+    """Rich explainable analysis payload."""
+
+    probability: float
+    threshold: float
+    baseProbability: float
+    confidenceBand: ConfidenceBandModel
+    modelVotes: List[ModelVoteModel] = Field(default_factory=list)
+    bestModel: str = "XGBoost"
+    topContributions: List[FeatureContributionModel] = Field(default_factory=list)
+    allFeatures: Dict[str, FeatureContributionModel] = Field(default_factory=dict)
+    featureCount: int = 0
 
 
 class AnalysisResult(BaseModel):
@@ -137,6 +178,8 @@ class AnalysisResult(BaseModel):
     features: AnalysisFeatures
     audioInfo: AudioInfo
     vocalAnalysis: Optional[VocalAnalysis] = None
+    xai: Optional[XAIExplanation] = None
+    towerScores: Dict[str, float] = Field(default_factory=dict)
 
 
 class AnalyzeResponse(BaseModel):