feat(ai-services): dedicated GET /avm/v2/feature-importance endpoint (TEC-2760)

Exposes ensemble feature importance as a standalone endpoint per R5.1 spec.
Aggregates XGBoost (0.4) + LightGBM (0.35) + CatBoost (0.25) gain when trained
boosters are loaded; falls back to the curated heuristic ranking otherwise, so
callers can depend on the endpoint during scaffold/heuristic-only runs.

- Factored heuristic drivers into a shared constant (_HEURISTIC_DRIVERS)
- Added AVMv2FeatureImportanceResponse model (model_version + source + drivers)
- Added service.get_feature_importance() public method
- Added tests/test_avm_v2.py::test_feature_importance_heuristic (24 total pass)

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
2026-04-18 15:27:30 +07:00
parent 5731577fa9
commit 729afe2db6
4 changed files with 92 additions and 16 deletions

View File

@@ -213,6 +213,19 @@ class AVMv2RollbackRequest(BaseModel):
target_version: str = Field(..., min_length=1, description="Model version to roll back to")
class AVMv2FeatureImportanceResponse(BaseModel):
"""Global feature importance across the loaded ensemble.
`source` is `"model"` when importances come from the trained boosters
(weighted XGBoost gain + LightGBM gain + CatBoost importance), or
`"heuristic"` when the service is running without trained artifacts.
"""
model_version: str
source: str = Field(..., description="One of: model, heuristic")
drivers: list[AVMv2FeatureImportance] = Field(default_factory=list)
class AVMv1Summary(BaseModel):
"""Compact summary of a v1 prediction for comparison."""