How to Build an AI Financial Analyst That Reads Annual Reports and Financial Statements

ai-financial-analyst/
├── app/
│   ├── __init__.py
│   ├── statements.py
│   ├── ratios.py
│   └── scenario_dcf.py
├── tests/
│   └── test_financial_analyst.py
└── requirements.txt

from pydantic import BaseModel, Field, model_validator

class FinancialPeriodStatement(BaseModel):
    ticker: str
    fiscal_year: int
    currency: str = "USD"
    unit_multiplier: int = Field(1_000_000, description="1_000_000 for $ in millions")

    # Income Statement
    revenue: float
    cost_of_goods_sold: float
    operating_income: float
    interest_expense: float = 0.0
    net_income: float

    # Balance Sheet
    cash_and_equivalents: float
    current_assets: float
    total_assets: float
    current_liabilities: float
    total_debt: float
    total_liabilities: float
    total_shareholders_equity: float

    # Cash Flow Statement
    operating_cash_flow: float
    capital_expenditures: float = Field(..., ge=0.0, description="Positive magnitude of CapEx")

    @model_validator(mode="after")
    def verify_accounting_identities(self) -> "FinancialPeriodStatement":
        """Enforces Assets == Liabilities + Equity within 0.5% tolerance for table rounding."""
        rhs = self.total_liabilities + self.total_shareholders_equity
        diff = abs(self.total_assets - rhs)
        tolerance = max(1.0, abs(self.total_assets) * 0.005)
        if diff > tolerance:
            raise ValueError(
                f"Balance Sheet identity violation for {self.ticker} FY{self.fiscal_year}: "
                f"Total Assets ({self.total_assets}) != Total Liabilities ({self.total_liabilities}) "
                f"+ Equity ({self.total_shareholders_equity}). Diff={diff}"
            )
        return self

from typing import Dict, Any
from app.statements import FinancialPeriodStatement

def compute_financial_ratios(stmt: FinancialPeriodStatement) -> Dict[str, float]:
    """Deterministically computes profitability, liquidity, leverage, and cash flow ratios."""
    gross_profit = stmt.revenue - stmt.cost_of_goods_sold
    free_cash_flow = stmt.operating_cash_flow - stmt.capital_expenditures

    return {
        "gross_margin_pct": round((gross_profit / stmt.revenue) * 100.0, 2) if stmt.revenue else 0.0,
        "operating_margin_pct": round((stmt.operating_income / stmt.revenue) * 100.0, 2) if stmt.revenue else 0.0,
        "net_margin_pct": round((stmt.net_income / stmt.revenue) * 100.0, 2) if stmt.revenue else 0.0,
        "return_on_equity_pct": round((stmt.net_income / stmt.total_shareholders_equity) * 100.0, 2)
        if stmt.total_shareholders_equity
        else 0.0,
        "current_ratio": round(stmt.current_assets / stmt.current_liabilities, 2)
        if stmt.current_liabilities
        else 0.0,
        "debt_to_equity": round(stmt.total_debt / stmt.total_shareholders_equity, 2)
        if stmt.total_shareholders_equity
        else 0.0,
        "free_cash_flow": round(free_cash_flow, 2),
        "fcf_margin_pct": round((free_cash_flow / stmt.revenue) * 100.0, 2) if stmt.revenue else 0.0,
    }

def compare_periods_yoy(prior: FinancialPeriodStatement, current: FinancialPeriodStatement) -> Dict[str, Any]:
    """Computes Year-over-Year growth rates and margin expansion in basis points (bps)."""
    p_ratios = compute_financial_ratios(prior)
    c_ratios = compute_financial_ratios(current)

    rev_growth_pct = ((current.revenue - prior.revenue) / abs(prior.revenue)) * 100.0
    ni_growth_pct = ((current.net_income - prior.net_income) / abs(prior.net_income)) * 100.0
    op_margin_bps = round((c_ratios["operating_margin_pct"] - p_ratios["operating_margin_pct"]) * 100.0, 0)

    return {
        "ticker": current.ticker,
        "period_comparison": f"FY{prior.fiscal_year} vs FY{current.fiscal_year}",
        "revenue_yoy_growth_pct": round(rev_growth_pct, 2),
        "net_income_yoy_growth_pct": round(ni_growth_pct, 2),
        "operating_margin_change_bps": int(op_margin_bps),
        "prior_ratios": p_ratios,
        "current_ratios": c_ratios,
    }

from typing import Dict
from pydantic import BaseModel, Field

class DCFScenarioAssumptions(BaseModel):
    name: str
    base_fcf: float
    annual_growth_rate: float = Field(..., ge=-0.5, le=1.0)
    wacc: float = Field(..., gt=0.02, le=0.30)
    terminal_growth_rate: float = Field(..., ge=0.0, le=0.06)
    projection_years: int = 5

def calculate_dcf_enterprise_value(scenario: DCFScenarioAssumptions) -> Dict[str, float]:
    """Calculates 5-year projected FCF present value and Gordon Growth Terminal Value."""
    if scenario.wacc <= scenario.terminal_growth_rate:
        raise ValueError("WACC must be strictly greater than terminal growth rate.")

    pv_fcf_sum = 0.0
    projected_fcf = scenario.base_fcf
    for year in range(1, scenario.projection_years + 1):
        projected_fcf = projected_fcf * (1.0 + scenario.annual_growth_rate)
        pv_fcf_sum += projected_fcf / ((1.0 + scenario.wacc) ** year)

    terminal_fcf = projected_fcf * (1.0 + scenario.terminal_growth_rate)
    terminal_value = terminal_fcf / (scenario.wacc - scenario.terminal_growth_rate)
    pv_terminal_value = terminal_value / ((1.0 + scenario.wacc) ** scenario.projection_years)
    enterprise_value = pv_fcf_sum + pv_terminal_value

    return {
        "pv_of_cash_flows": round(pv_fcf_sum, 2),
        "pv_of_terminal_value": round(pv_terminal_value, 2),
        "enterprise_value": round(enterprise_value, 2),
    }

import pytest
from app.statements import FinancialPeriodStatement
from app.ratios import compute_financial_ratios, compare_periods_yoy
from app.scenario_dcf import DCFScenarioAssumptions, calculate_dcf_enterprise_value

def test_balance_sheet_identity_guardrail():
    with pytest.raises(ValueError, match="Balance Sheet identity violation"):
        FinancialPeriodStatement(
            ticker="ACME",
            fiscal_year=2025,
            revenue=1000.0,
            cost_of_goods_sold=400.0,
            operating_income=300.0,
            net_income=220.0,
            cash_and_equivalents=150.0,
            current_assets=400.0,
            total_assets=1000.0,
            current_liabilities=200.0,
            total_debt=300.0,
            total_liabilities=500.0,
            total_shareholders_equity=300.0,  # 500 + 300 = 800 != 1000
            operating_cash_flow=280.0,
            capital_expenditures=50.0,
        )

def test_ratios_yoy_and_dcf():
    fy24 = FinancialPeriodStatement(
        ticker="ACME", fiscal_year=2024,
        revenue=1000.0, cost_of_goods_sold=400.0, operating_income=250.0, net_income=180.0,
        cash_and_equivalents=120.0, current_assets=350.0, total_assets=900.0,
        current_liabilities=150.0, total_debt=200.0, total_liabilities=400.0,
        total_shareholders_equity=500.0, operating_cash_flow=240.0, capital_expenditures=40.0,
    )
    fy25 = FinancialPeriodStatement(
        ticker="ACME", fiscal_year=2025,
        revenue=1200.0, cost_of_goods_sold=450.0, operating_income=336.0, net_income=250.0,
        cash_and_equivalents=180.0, current_assets=450.0, total_assets=1100.0,
        current_liabilities=180.0, total_debt=220.0, total_liabilities=450.0,
        total_shareholders_equity=650.0, operating_cash_flow=310.0, capital_expenditures=50.0,
    )
    comp = compare_periods_yoy(fy24, fy25)
    assert comp["revenue_yoy_growth_pct"] == 20.0
    assert comp["operating_margin_change_bps"] == 300  # 25.0% -> 28.0% = +300 bps

    dcf = calculate_dcf_enterprise_value(
        DCFScenarioAssumptions(
            name="Base Case", base_fcf=260.0, annual_growth_rate=0.10, wacc=0.09, terminal_growth_rate=0.025
        )
    )
    assert dcf["enterprise_value"] > 5000.0