major update

app/schemas/fundamental.py

@@ -16,3 +16,4 @@ class FundamentalResponse(BaseModel):
     earnings_surprise: float | None = None
     market_cap: float | None = None
     fetched_at: datetime | None = None
+    unavailable_fields: dict[str, str] = {}

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):

app/schemas/sentiment.py

@@ -8,6 +8,13 @@ from typing import Literal
 from pydantic import BaseModel, Field
 
 
+class CitationItem(BaseModel):
+    """A single citation from the sentiment analysis."""
+
+    url: str
+    title: str
+
+
 class SentimentScoreResult(BaseModel):
     """A single sentiment score record."""
 
@@ -16,6 +23,8 @@ class SentimentScoreResult(BaseModel):
     confidence: int = Field(ge=0, le=100)
     source: str
     timestamp: datetime
+    reasoning: str = ""
+    citations: list[CitationItem] = []
 
 
 class SentimentResponse(BaseModel):

app/schemas/sr_level.py

@@ -19,9 +19,22 @@ class SRLevelResult(BaseModel):
     created_at: datetime
 
 
+class SRZoneResult(BaseModel):
+    """A clustered S/R zone spanning a price range."""
+
+    low: float
+    high: float
+    midpoint: float
+    strength: int = Field(ge=0, le=100)
+    type: Literal["support", "resistance"]
+    level_count: int
+
+
 class SRLevelResponse(BaseModel):
     """Envelope-ready S/R levels response."""
 
     symbol: str
     levels: list[SRLevelResult]
+    zones: list[SRZoneResult] = []
+    visible_levels: list[SRLevelResult] = []
     count: int