path: root/backend/app/schemas.py

"""Pydantic response schemas for the Prism v2 Overview API."""
from typing import Literal

from pydantic import BaseModel, Field


class SearchResult(BaseModel):
    symbol: str
    name: str
    exchange: str | None = None


class MarketIndex(BaseModel):
    name: str
    price: float | None = None
    change_pct: float | None = None


class Quote(BaseModel):
    price: float | None = None
    prev_close: float | None = None
    change: float | None = None
    change_pct: float | None = None


class Signal(BaseModel):
    key: str
    state: Literal["pos", "warn", "neg", "neu"]
    value: str
    description: str


class OverviewStats(BaseModel):
    market_cap: float | None = None
    trailing_pe: float | None = None
    trailing_eps: float | None = None
    volume: float | None = None
    average_volume: float | None = None
    beta: float | None = None


class OverviewRatios(BaseModel):
    price_to_book: float | None = None
    price_to_sales: float | None = None
    ev_to_sales: float | None = None
    ev_to_ebitda: float | None = None
    gross_margin_ttm: float | None = None
    operating_margin_ttm: float | None = None
    net_margin_ttm: float | None = None
    roe_ttm: float | None = None
    roa_ttm: float | None = None
    roic_ttm: float | None = None
    debt_to_equity: float | None = None
    current_ratio: float | None = None
    dividend_yield_ttm: float | None = None
    dividend_payout_ratio_ttm: float | None = None


class Range52Week(BaseModel):
    low: float | None = None
    high: float | None = None
    price: float | None = None


class ShortInterest(BaseModel):
    short_percent_of_float: float | None = None
    short_ratio: float | None = None
    shares_short: int | None = None
    shares_short_prior_month: int | None = None
    shares_short_delta_pct: float | None = None


class CompanyProfile(BaseModel):
    symbol: str
    name: str
    sector: str | None = None
    industry: str | None = None
    exchange: str | None = None
    website: str | None = None
    summary: str | None = None


class OverviewMeta(BaseModel):
    status: Literal["complete", "partial"]
    is_partial: bool = False
    field_availability: dict[str, bool] = Field(default_factory=dict)
    sources: dict[str, str] = Field(default_factory=dict)


class TickerOverview(BaseModel):
    profile: CompanyProfile
    quote: Quote
    signals: list[Signal] = Field(default_factory=list)
    stats: OverviewStats
    ratios: OverviewRatios
    range_52w: Range52Week
    short_interest: ShortInterest
    meta: OverviewMeta


class HistoryPoint(BaseModel):
    date: str
    open: float | None = None
    high: float | None = None
    low: float | None = None
    close: float | None = None
    volume: float | None = None


class FinancialRow(BaseModel):
    label: str
    indent: int = 0
    is_total: bool = False
    is_section: bool = False
    is_margin: bool = False
    values: list[float | None] = Field(default_factory=list)


class FinancialStatement(BaseModel):
    columns: list[str] = Field(default_factory=list)
    rows: list[FinancialRow] = Field(default_factory=list)


class FinancialsResponse(BaseModel):
    period: Literal["annual", "quarterly"]
    income: FinancialStatement
    balance: FinancialStatement
    cash_flow: FinancialStatement


class DcfResult(BaseModel):
    available: bool = True
    error: str | None = None
    intrinsic_value_per_share: float | None = None
    enterprise_value: float | None = None
    equity_value: float | None = None
    net_debt: float | None = None
    cash_and_equivalents: float | None = None
    total_debt: float | None = None
    terminal_value_pv: float | None = None
    fcf_pv_sum: float | None = None
    growth_rate_used: float | None = None
    base_fcf: float | None = None
    wacc: float = 0.10
    terminal_growth: float = 0.03
    projection_years: int = 5


class MultipleResult(BaseModel):
    available: bool = True
    implied_price_per_share: float | None = None
    implied_ev: float | None = None
    equity_value: float | None = None
    net_debt: float | None = None
    multiple_used: float | None = None


class ValuationResponse(BaseModel):
    symbol: str
    current_price: float | None = None
    shares_outstanding: float | None = None
    dcf: DcfResult
    ev_ebitda: MultipleResult
    ev_revenue: MultipleResult
    price_to_book: MultipleResult


class WatchlistItem(BaseModel):
    symbol: str
    created_at: str
    quote: Quote | None = None


class WatchlistResponse(BaseModel):
    items: list[WatchlistItem]
    limit: int = 10


class RatioPoint(BaseModel):
    value: float | None = None
    spark: list[float | None] = Field(default_factory=list)
    vs_sector: float | None = None


class RatiosResponse(BaseModel):
    pe_ttm: RatioPoint
    ev_ebitda: RatioPoint
    gross_margin: RatioPoint
    net_margin: RatioPoint
    price_to_book: RatioPoint
    price_to_sales: RatioPoint
    ev_to_sales: RatioPoint
    p_fcf: RatioPoint
    forward_pe: RatioPoint
    operating_margin: RatioPoint
    ebitda_margin: RatioPoint
    fcf_margin: RatioPoint
    roe: RatioPoint
    roa: RatioPoint
    roic: RatioPoint
    debt_to_equity: RatioPoint
    current_ratio: RatioPoint
    quick_ratio: RatioPoint
    interest_coverage: RatioPoint
    dividend_yield: RatioPoint
    dividend_payout: RatioPoint


class InsiderTransaction(BaseModel):
    date: str | None = None
    insider: str
    position: str
    direction: Literal["buy", "sell", "other"]
    shares: int | None = None
    value: float | None = None


class InsiderMonthPoint(BaseModel):
    month: str
    buy: float
    sell: float


class InsiderSummary(BaseModel):
    buy_count: int
    sell_count: int
    buy_value: float
    sell_value: float


class InsidersResponse(BaseModel):
    summary: InsiderSummary
    monthly_chart: list[InsiderMonthPoint] = Field(default_factory=list)
    transactions: list[InsiderTransaction] = Field(default_factory=list)


class FilingItem(BaseModel):
    date: str
    form: str
    title: str
    url: str | None = None


class FilingKpis(BaseModel):
    total: int = 0
    count_10k: int = 0
    count_10q: int = 0
    count_8k: int = 0
    distinct_forms: int = 0


class FormMixRow(BaseModel):
    form: str
    count: int
    pct: float | None = None


class CadencePoint(BaseModel):
    month: str
    count_10k: int = 0
    count_10q: int = 0
    count_8k: int = 0
    count_other: int = 0


class FilingsResponse(BaseModel):
    kpis: FilingKpis
    cadence: list[CadencePoint] = Field(default_factory=list)
    form_mix: list[FormMixRow] = Field(default_factory=list)
    readout: str
    filings: list[FilingItem] = Field(default_factory=list)


class ErrorResponse(BaseModel):
    detail: str


class NewsItem(BaseModel):
    id: str
    title: str
    summary: str
    source: str
    url: str
    sentiment: Literal["bullish", "neutral", "bearish"]
    published_at: str


class NewsAggregate(BaseModel):
    buzz_articles_last_week: int
    bullish_pct: float
    neutral_pct: float
    bearish_pct: float


class NewsResponse(BaseModel):
    items: list[NewsItem] = Field(default_factory=list)
    aggregate: NewsAggregate | None = None
    provider: Literal["finnhub", "fmp"] | None = None
    fetched_at: str