Borsa MCP

"""
Financial Ratios Models
Pydantic models for financial ratio calculation results.
"""

from pydantic import BaseModel, Field
from typing import Optional, List


class RoeSonucu(BaseModel):
    """Return on Equity (ROE) calculation result."""
    roe_percent: float = Field(description="ROE as percentage")
    net_income: Optional[float] = Field(None, description="Net Income in millions TRY")
    total_equity: Optional[float] = Field(None, description="Total Equity in millions TRY")
    formula: Optional[str] = Field(None, description="Formula used: ROE = Net Income / Total Equity")
    assessment: Optional[str] = Field(None, description="Qualitative assessment (Excellent/Good/Average/Poor)")
    notes: Optional[str] = Field(None, description="Detailed explanation and context")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class RoicSonucu(BaseModel):
    """Return on Invested Capital (ROIC) calculation result."""
    roic_percent: float = Field(description="ROIC as percentage")
    nopat: Optional[float] = Field(None, description="Net Operating Profit After Tax in millions TRY")
    invested_capital: Optional[float] = Field(None, description="Invested Capital in millions TRY")
    operating_income: Optional[float] = Field(None, description="Operating Income in millions TRY")
    tax_rate_percent: Optional[float] = Field(None, description="Effective tax rate as percentage")
    formula: Optional[str] = Field(None, description="Formula used: ROIC = NOPAT / Invested Capital")
    assessment: Optional[str] = Field(None, description="Qualitative assessment (Excellent/Good/Average/Poor)")
    notes: Optional[str] = Field(None, description="Detailed explanation including capital breakdown")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class DebtRatiosSonucu(BaseModel):
    """Debt and Leverage Ratios calculation result."""
    debt_to_equity: float = Field(description="Debt-to-Equity ratio (Total Debt / Total Equity)")
    debt_to_assets: float = Field(description="Debt-to-Assets ratio (Total Debt / Total Assets)")
    interest_coverage: float = Field(description="Interest Coverage ratio (EBIT / Interest Expense)")
    debt_service_coverage: float = Field(description="Debt Service Coverage (Operating Income / (Interest + Current Debt))")

    total_debt: Optional[float] = Field(None, description="Total Debt in millions TRY")
    total_equity: Optional[float] = Field(None, description="Total Equity in millions TRY")
    total_assets: Optional[float] = Field(None, description="Total Assets in millions TRY")
    ebit: Optional[float] = Field(None, description="EBIT (Operating Income) in millions TRY")
    interest_expense: Optional[float] = Field(None, description="Interest Expense in millions TRY")
    current_debt: Optional[float] = Field(None, description="Current Debt in millions TRY")

    debt_to_equity_assessment: Optional[str] = Field(None, description="D/E assessment")
    debt_to_assets_assessment: Optional[str] = Field(None, description="D/A assessment")
    interest_coverage_assessment: Optional[str] = Field(None, description="Interest coverage assessment")
    debt_service_assessment: Optional[str] = Field(None, description="Debt service assessment")

    notes: Optional[str] = Field(None, description="Overall debt profile summary")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class FcfMarginSonucu(BaseModel):
    """Free Cash Flow Margin calculation result."""
    fcf_margin_percent: float = Field(description="FCF Margin as percentage")
    free_cash_flow: Optional[float] = Field(None, description="Free Cash Flow in millions TRY")
    total_revenue: Optional[float] = Field(None, description="Total Revenue in millions TRY")
    formula: Optional[str] = Field(None, description="Formula used: FCF Margin = FCF / Total Revenue")
    assessment: Optional[str] = Field(None, description="Qualitative assessment (Excellent/Good/Average/Poor)")
    notes: Optional[str] = Field(None, description="Detailed explanation and context")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class EarningsQualitySonucu(BaseModel):
    """Earnings Quality Metrics calculation result."""
    cf_to_earnings_ratio: float = Field(description="Operating Cash Flow / Net Income ratio (>1.0 is good)")
    accruals_ratio_percent: float = Field(description="Accruals Ratio as percentage (lower is better, <5% good)")
    wc_impact_percent: float = Field(description="Working Capital Impact as percentage of OCF (negative is good)")

    operating_cash_flow: Optional[float] = Field(None, description="Operating Cash Flow in millions TRY")
    net_income: Optional[float] = Field(None, description="Net Income in millions TRY")
    total_assets: Optional[float] = Field(None, description="Total Assets in millions TRY")
    wc_change: Optional[float] = Field(None, description="Change in Working Capital in millions TRY")

    cf_to_earnings_assessment: Optional[str] = Field(None, description="Cash flow quality assessment")
    accruals_assessment: Optional[str] = Field(None, description="Accruals quality assessment")
    wc_impact_assessment: Optional[str] = Field(None, description="Working capital impact assessment")
    overall_quality: Optional[str] = Field(None, description="Overall earnings quality rating (High/Medium/Low)")

    notes: Optional[str] = Field(None, description="Detailed quality analysis")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class PiotroskiFScoreSonucu(BaseModel):
    """Piotroski F-Score calculation result (9-point score)."""
    f_score: int = Field(description="Total F-Score (0-9, higher is better)")
    profitability_score: int = Field(description="Profitability sub-score (0-4)")
    leverage_score: int = Field(description="Leverage/Liquidity sub-score (0-3)")
    operating_efficiency_score: int = Field(description="Operating efficiency sub-score (0-2)")

    component_scores: dict = Field(description="Individual component scores breakdown")
    assessment: str = Field(description="F-Score assessment (Strong 8-9, Good 6-7, Weak 0-3)")
    notes: str = Field(description="Detailed breakdown of score components")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class AltmanZScoreSonucu(BaseModel):
    """Altman Z-Score calculation result."""
    z_score: float = Field(description="Z-Score value")
    wc_to_ta: Optional[float] = Field(None, description="Working Capital / Total Assets component")
    re_to_ta: Optional[float] = Field(None, description="Retained Earnings / Total Assets component")
    ebit_to_ta: Optional[float] = Field(None, description="EBIT / Total Assets component")
    mc_to_tl: Optional[float] = Field(None, description="Market Cap / Total Liabilities component")
    sales_to_ta: Optional[float] = Field(None, description="Sales / Total Assets component")

    formula: Optional[str] = Field(None, description="Altman Z-Score formula")
    assessment: Optional[str] = Field(None, description="Bankruptcy risk assessment (Safe >2.99, Grey 1.81-2.99, Distress <1.81)")
    notes: Optional[str] = Field(None, description="Detailed explanation of score and risk level")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class ShareholderYieldSonucu(BaseModel):
    """Shareholder Yield calculation result."""
    shareholder_yield_percent: float = Field(description="Total Shareholder Yield as percentage")
    dividend_yield_percent: float = Field(description="Dividend Yield as percentage")
    buyback_yield_percent: float = Field(description="Buyback Yield as percentage")

    total_dividends: float = Field(description="Total Dividends paid in millions TRY")
    buybacks: float = Field(description="Share Buybacks in millions TRY")
    market_cap: float = Field(description="Market Capitalization in millions TRY")

    formula: str = Field(description="Formula: (Dividends + Buybacks) / Market Cap")
    assessment: str = Field(description="Shareholder return assessment")
    notes: str = Field(description="Detailed breakdown of shareholder returns")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class RealGrowthSonucu(BaseModel):
    """Real Growth Rate calculation result (inflation-adjusted)."""
    real_growth_percent: float = Field(description="Real (inflation-adjusted) growth rate as percentage")
    nominal_growth_percent: Optional[float] = Field(None, description="Nominal growth rate as percentage")
    inflation_percent: Optional[float] = Field(None, description="Inflation rate used as percentage")

    formula: Optional[str] = Field(None, description="Fisher Equation: Real Growth ≈ Nominal Growth - Inflation")
    data_sources: Optional[dict] = Field(None, description="Sources for nominal growth and inflation data")
    assessment: Optional[str] = Field(None, description="Growth quality assessment")
    notes: Optional[str] = Field(None, description="Context and explanation of real growth")
    error: Optional[str] = Field(None, description="Error message if calculation failed")


class CoreFinancialHealthAnalysis(BaseModel):
    """
    Consolidated Core Financial Health Analysis (5 metrics in 1).

    Combines ROE, ROIC, Debt Ratios, FCF Margin, and Earnings Quality
    into a single efficient analysis with overall health assessment.
    """
    ticker: str = Field(description="BIST ticker code")
    period: str = Field(description="Analysis period (quarterly)")

    # Metric 1: Return on Equity
    roe: RoeSonucu = Field(description="Return on Equity - profitability from equity")

    # Metric 2: Return on Invested Capital
    roic: RoicSonucu = Field(description="Return on Invested Capital - capital efficiency")

    # Metric 3: Debt Ratios (4 sub-ratios)
    debt_ratios: DebtRatiosSonucu = Field(description="Comprehensive debt and leverage ratios")

    # Metric 4: FCF Margin
    fcf_margin: FcfMarginSonucu = Field(description="Free Cash Flow margin - cash generation efficiency")

    # Metric 5: Earnings Quality
    earnings_quality: EarningsQualitySonucu = Field(description="Earnings quality assessment - detect manipulation")

    # Overall Assessment
    overall_health_score: str = Field(
        description="Overall financial health score: STRONG | GOOD | AVERAGE | WEAK"
    )
    strengths: List[str] = Field(
        description="Key financial strengths identified from the 5 metrics (2-5 points)"
    )
    concerns: List[str] = Field(
        description="Areas of concern identified from the 5 metrics (0-3 points)"
    )

    data_quality_notes: Optional[str] = Field(
        None,
        description="Data quality notes: missing fields, data limitations, or fetch issues"
    )
    error: Optional[str] = Field(None, description="Error message if overall calculation failed")


class AdvancedFinancialMetrics(BaseModel):
    """
    Consolidated Advanced Financial Metrics Analysis (2 metrics in 1).

    Combines Altman Z-Score (bankruptcy risk) and Real Growth Rate
    (inflation-adjusted growth) into a single efficient analysis.
    """
    ticker: str = Field(description="BIST ticker code")
    period: str = Field(description="Analysis period (quarterly)")

    # Metric 1: Altman Z-Score (Bankruptcy Risk)
    altman_z_score: AltmanZScoreSonucu = Field(
        description="Altman Z-Score bankruptcy prediction (Safe >2.99, Grey 1.81-2.99, Distress <1.81)"
    )

    # Metric 2A: Real Growth - Revenue
    real_growth_revenue: RealGrowthSonucu = Field(
        description="Revenue real growth rate (inflation-adjusted)"
    )

    # Metric 2B: Real Growth - Earnings
    real_growth_earnings: RealGrowthSonucu = Field(
        description="Earnings real growth rate (inflation-adjusted)"
    )

    # Overall Assessment
    financial_stability: str = Field(
        description="Financial stability from Z-Score: SAFE | GREY | DISTRESS"
    )
    growth_quality: str = Field(
        description="Growth quality from real growth metrics: STRONG | MODERATE | WEAK | NEGATIVE"
    )

    key_findings: List[str] = Field(
        description="Key findings combining bankruptcy risk and growth analysis (2-4 points)"
    )

    data_quality_notes: Optional[str] = Field(
        None,
        description="Data quality notes: missing fields, data limitations, or fetch issues"
    )
    error: Optional[str] = Field(None, description="Error message if overall calculation failed")