major update

app/schemas/score.py

@@ -7,6 +7,34 @@ from datetime import datetime
 from pydantic import BaseModel, Field
 
 
+class SubScoreResponse(BaseModel):
+    """A single sub-score within a dimension breakdown."""
+
+    name: str
+    score: float
+    weight: float
+    raw_value: float | str | None = None
+    description: str = ""
+
+
+class ScoreBreakdownResponse(BaseModel):
+    """Breakdown of a dimension score into sub-scores."""
+
+    sub_scores: list[SubScoreResponse]
+    formula: str
+    unavailable: list[dict[str, str]] = []
+
+
+class CompositeBreakdownResponse(BaseModel):
+    """Breakdown of the composite score showing dimension weights and re-normalization."""
+
+    weights: dict[str, float]
+    available_dimensions: list[str]
+    missing_dimensions: list[str]
+    renormalized_weights: dict[str, float]
+    formula: str
+
+
 class DimensionScoreResponse(BaseModel):
     """A single dimension score."""
 
@@ -14,6 +42,7 @@ class DimensionScoreResponse(BaseModel):
     score: float
     is_stale: bool
     computed_at: datetime | None = None
+    breakdown: ScoreBreakdownResponse | None = None
 
 
 class ScoreResponse(BaseModel):
@@ -26,6 +55,7 @@ class ScoreResponse(BaseModel):
     dimensions: list[DimensionScoreResponse] = []
     missing_dimensions: list[str] = []
     computed_at: datetime | None = None
+    composite_breakdown: CompositeBreakdownResponse | None = None
 
 
 class WeightUpdateRequest(BaseModel):