"""Pydantic schemas for sentiment endpoints."""

from __future__ import annotations

from datetime import datetime
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."""

    id: int
    classification: Literal["bullish", "bearish", "neutral"]
    confidence: int = Field(ge=0, le=100)
    source: str
    timestamp: datetime
    reasoning: str = ""
    citations: list[CitationItem] = []
    recommendation: Literal["buy", "hold", "avoid"] | None = None


class SentimentResponse(BaseModel):
    """Envelope-ready sentiment response."""

    symbol: str
    scores: list[SentimentScoreResult]
    count: int
    dimension_score: float | None = Field(
        None, ge=0, le=100, description="Time-decay weighted sentiment dimension score"
    )
    lookback_hours: float
