← Files VeraARCHIVED FILE

modules/business-valuation/scripts/valuation_engine.py

25.2 KB · Nov 22, 2026 · 00:10 UTC

↓ Download file

"""Auditable Decimal formulas; selection and economic judgment stay with people.

Fixed arithmetic supports reproducible calculation and workbook replay.
The register is a small expression tree, never executable source or Python eval.
"""

from __future__ import annotations

import calendar
import re
from datetime import date
from decimal import Decimal, localcontext
from typing import Any

__all__ = ["ValuationError", "decimal", "calculate_method", "evaluate", "METHODS"]

METHODS = {
    "DCF_FCFF",
    "DCF_FCFE",
    "INCOME_EQUITY",
    "INCOME_EQUITY_FINITE",
    "RESIDUAL_INCOME_EQUITY",
    "ECONOMIC_PROFIT",
    "HOLDING_SOTP",
    "NAV",
    "MIXED_EQUITY",
    "MULTIPLE",
    "APV",
}


class ValuationError(ValueError):
    """A calculation cannot satisfy its declared contract."""


def decimal(value: Any) -> Decimal:
    """Require finite, bounded decimal text; absent is never zero."""
    if (
        not isinstance(value, str)
        or len(value) > 80
        or not re.fullmatch(r"-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?", value)
    ):
        raise ValuationError("Expected finite canonical decimal text")
    return Decimal(value)


def evaluate(op: str, values: list[Decimal]) -> Decimal:
    """Evaluate only the small supported arithmetic vocabulary."""
    with localcontext() as ctx:
        ctx.prec = 40
        if op == "sum":
            return sum(values, Decimal(0))
        if op == "exp":
            if len(values) != 1 or abs(values[0]) > 100:
                raise ValuationError(
                    "Exponential exceeds the supported numeric range [-100, 100]"
                )
            return values[0].exp()
        if len(values) != 2:
            raise ValuationError("Binary operation needs two operands")
        left, right = values
        if op == "subtract":
            return left - right
        if op == "multiply":
            return left * right
        if op == "divide" and right != 0:
            return left / right
        if op == "power" and left > 0:
            return left**right
    raise ValuationError("Invalid arithmetic operation or denominator")


class Ledger:
    """Keep every formula, exact value and transitive input reference together."""

    def __init__(self, method_id: str, inputs: dict[str, dict], currency: str):
        self.prefix = method_id
        self.inputs = inputs
        self.currency = currency
        self.rows: dict[str, dict] = {}

    def input(self, ref: Any, unit: str) -> str:
        if not isinstance(ref, str) or ref not in self.inputs:
            raise ValuationError(f"Unknown input reference: {ref}")
        record = self.inputs[ref]
        if record["unit"] != unit:
            raise ValuationError(f"Incompatible unit for {ref}: expected {unit}")
        if record["value"] is None:
            raise ValuationError(f"Missing input: {ref}")
        value = decimal(record["value"])
        identifier = f"{self.prefix}/input/{ref}"
        self.rows[identifier] = {
            "id": identifier,
            "value": format(value, "f"),
            "unit": unit,
            "op": "input",
            "arguments": [],
            "input_ids": [ref],
        }
        return identifier

    def constant(self, name: str, value: int) -> str:
        identifier = f"{self.prefix}/constant/{name}"
        self.rows[identifier] = {
            "id": identifier,
            "value": str(value),
            "unit": "scalar",
            "op": "constant",
            "arguments": [],
            "input_ids": [],
        }
        return identifier

    def value(self, ref: str) -> Decimal:
        return decimal(self.rows[ref]["value"])

    def add(self, name: str, op: str, args: list[str], unit: str | None = None) -> str:
        identifier = f"{self.prefix}/{name}"
        if identifier in self.rows:
            raise ValuationError("Duplicate calculation ID")
        value = evaluate(op, [self.value(ref) for ref in args])
        self.rows[identifier] = {
            "id": identifier,
            "value": format(value, "f"),
            "unit": unit or self.currency,
            "op": op,
            "arguments": args,
            "input_ids": sorted(
                {item for ref in args for item in self.rows[ref]["input_ids"]}
            ),
        }
        return identifier


def _keys(args: dict, required: set[str], optional: set[str] | None = None) -> None:
    if (
        not isinstance(args, dict)
        or set(args) - required - (optional or set())
        or required - set(args)
    ):
        raise ValuationError(f"Expected method inputs: {sorted(required)}")


def _date(value: Any) -> date:
    if not isinstance(value, str):
        raise ValuationError("Timing dates require YYYY-MM-DD text")
    try:
        result = date.fromisoformat(value)
    except ValueError as exc:
        raise ValuationError("Invalid timing date") from exc
    if result.isoformat() != value or result.year == 9999:
        raise ValuationError("Timing dates require canonical dates before year 9999")
    return result


def _year_fraction(
    ledger: Ledger, name: str, start: date, end: date, basis: str
) -> str:
    """Expose actual days and denominators as replayable integer arithmetic."""
    parts = []
    cursor = start
    while cursor < end:
        stop = end if basis == "ACT/365F" else min(end, date(cursor.year + 1, 1, 1))
        denominator = (
            365 if basis == "ACT/365F" else 366 if calendar.isleap(cursor.year) else 365
        )
        part = len(parts)
        parts.append(
            ledger.add(
                f"{name}/part-{part}",
                "divide",
                [
                    ledger.constant(f"{name}/days-{part}", (stop - cursor).days),
                    ledger.constant(f"{name}/year-{part}", denominator),
                ],
                "years",
            )
        )
        cursor = stop
    return ledger.add(name, "sum", parts, "years")


def _dated_factors(
    ledger: Ledger,
    timing: dict,
    count: int,
    *,
    terminal_convention: str = "annual_end_period_perpetuity_at_horizon",
) -> tuple[list[str], str, dict]:
    """Discount explicit dated flows; never infer a curve or prorate amounts."""
    _keys(
        timing,
        {
            "valuation_date",
            "period_end_dates",
            "cash_flow_timing",
            "day_count",
            "rate_compounding",
            "rate_model",
            "rate_ids",
            "rationale",
        },
        {"terminal_discount_rate"},
    )
    valuation_date = _date(timing["valuation_date"])
    ends = timing["period_end_dates"]
    if not isinstance(ends, list) or len(ends) != count:
        raise ValuationError("Provide one end date per explicit cash flow")
    dates = [_date(value) for value in ends]
    if any(right <= left for left, right in zip([valuation_date, *dates], dates)):
        raise ValuationError("Cash-flow periods must increase after the valuation date")
    if (dates[-1] - valuation_date).days > 36600:
        raise ValuationError(
            "Dated calculation horizon exceeds the supported 36600-day bound"
        )
    basis, convention = timing["day_count"], timing["cash_flow_timing"]
    if not all(
        isinstance(timing[key], str)
        for key in ("day_count", "cash_flow_timing", "rate_compounding", "rate_model")
    ):
        raise ValuationError("Timing conventions require explicit text identifiers")
    if basis not in {"ACT/365F", "ACT/ACT_ISDA"}:
        raise ValuationError("Choose ACT/365F or ACT/ACT_ISDA explicitly")
    if convention not in {"end_period", "mid_period"}:
        raise ValuationError("Choose end_period or mid_period explicitly")
    if timing["rate_compounding"] not in {"effective_annual", "continuous"}:
        raise ValuationError("Unsupported discount-rate compounding")
    model, rates = timing["rate_model"], timing["rate_ids"]
    if model not in {"flat", "spot_curve", "forward_curve"}:
        raise ValuationError("Choose flat, spot_curve or forward_curve explicitly")
    if not isinstance(rates, list) or len(rates) != (1 if model == "flat" else count):
        raise ValuationError("Rate IDs must match the selected flat or curve model")
    if (model == "spot_curve") != ("terminal_discount_rate" in timing):
        raise ValuationError(
            "Only a spot curve requires a separate horizon discount rate"
        )
    if (
        not isinstance(timing["rationale"], str)
        or not timing["rationale"].strip()
        or len(timing["rationale"]) > 20000
    ):
        raise ValuationError("Explain the cash timing, day count and rate model")

    one = ledger.constant("timing/one", 1)
    two = ledger.constant("timing/two", 2)

    def factor(name: str, rate_id: Any, years: str) -> str:
        rate = ledger.input(rate_id, "ratio")
        if timing["rate_compounding"] == "continuous":
            exponent = ledger.add(
                f"{name}/exponent", "multiply", [rate, years], "ratio"
            )
            return ledger.add(name, "exp", [exponent], "ratio")
        if ledger.value(rate) <= -1:
            raise ValuationError("Effective annual discount rates must exceed -1")
        base = ledger.add(f"{name}/base", "sum", [one, rate], "ratio")
        return ledger.add(name, "power", [base, years], "ratio")

    factors, schedule = [], []
    previous = valuation_date
    previous_time = ledger.constant("timing/zero", 0)
    accumulated = one
    for index, end in enumerate(dates, 1):
        end_time = _year_fraction(
            ledger, f"time/{index}/end", valuation_date, end, basis
        )
        duration = ledger.add(
            f"time/{index}/duration", "subtract", [end_time, previous_time], "years"
        )
        cash_time = end_time
        cash_duration = duration
        if convention == "mid_period":
            total = ledger.add(
                f"time/{index}/sum", "sum", [previous_time, end_time], "years"
            )
            cash_time = ledger.add(
                f"time/{index}/cash", "divide", [total, two], "years"
            )
            cash_duration = ledger.add(
                f"time/{index}/half", "divide", [duration, two], "years"
            )
        rate_id = rates[0] if model == "flat" else rates[index - 1]
        if model == "forward_curve":
            current = factor(f"discount/{index}/cash-period", rate_id, cash_duration)
            cash_factor = ledger.add(
                f"discount/{index}", "multiply", [accumulated, current], "ratio"
            )
            full = factor(f"discount/{index}/full-period", rate_id, duration)
            accumulated = ledger.add(
                f"discount/{index}/accumulated",
                "multiply",
                [accumulated, full],
                "ratio",
            )
        else:
            cash_factor = factor(f"discount/{index}", rate_id, cash_time)
        factors.append(cash_factor)
        schedule.append(
            {
                "start_date": previous.isoformat(),
                "end_date": end.isoformat(),
                "cash_time_id": cash_time,
                "discount_factor_id": cash_factor,
                "rate_id": rate_id,
            }
        )
        previous, previous_time = end, end_time
    horizon_factor = (
        accumulated
        if model == "forward_curve"
        else factor(
            "discount/terminal-horizon",
            timing["terminal_discount_rate"] if model == "spot_curve" else rates[0],
            previous_time,
        )
    )
    return (
        factors,
        horizon_factor,
        {
            "valuation_date": timing["valuation_date"],
            "day_count": basis,
            "cash_flow_timing": convention,
            "rate_compounding": timing["rate_compounding"],
            "rate_model": model,
            "rationale": timing["rationale"],
            "schedule": schedule,
            "terminal_time_id": previous_time,
            "terminal_discount_factor_id": horizon_factor,
            "terminal_value_convention": terminal_convention,
        },
    )


def calculate_method(method: dict, inputs: dict[str, dict], currency: str) -> dict:
    """Calculate one selected method, retaining equity versus enterprise basis."""
    kind = method["kind"]
    if kind not in METHODS:
        raise ValuationError("Unsupported valuation method")
    args = method["inputs"]
    ledger = Ledger(method["id"], inputs, currency)
    money = lambda ref: ledger.input(ref, currency)
    ratio = lambda ref: ledger.input(ref, "ratio")
    value_type = "equity"
    extras: dict[str, str] = {}
    timing_result = None
    residual_schedule = None
    economic_schedule = None
    holding_schedule = None
    comparable_schedule = None
    if "timing" in method and kind not in {
        "DCF_FCFF",
        "DCF_FCFE",
        "INCOME_EQUITY_FINITE",
        "RESIDUAL_INCOME_EQUITY",
        "ECONOMIC_PROFIT",
    }:
        raise ValuationError(
            "Explicit dated timing requires DCF, finite equity income, residual income or economic profit"
        )

    def sequence(refs: Any, name: str, limit: int = 100) -> list[str]:
        if not isinstance(refs, list) or not 1 <= len(refs) <= limit:
            raise ValuationError(f"{name} requires 1..{limit} explicit amounts")
        return [money(ref) for ref in refs]

    def positive(ref: str) -> str:
        if ledger.value(ref) <= 0:
            raise ValuationError("Positive value required")
        return ref

    def nonnegative(ref: str) -> str:
        if ledger.value(ref) < 0:
            raise ValuationError("Nonnegative value required")
        return ref

    if kind in {"DCF_FCFF", "DCF_FCFE"}:
        dated = "timing" in method
        _keys(
            args,
            {"flows", "terminal_next_flow", "terminal_growth"}
            | ({"terminal_rate"} if dated else {"discount_rate"}),
            set() if dated else {"terminal_rate"},
        )
        flows = sequence(args["flows"], "DCF", 1200 if dated else 100)
        growth = ratio(args["terminal_growth"])
        terminal_rate = ratio(
            args["terminal_rate"] if "terminal_rate" in args else args["discount_rate"]
        )
        if ledger.value(growth) <= -1 or ledger.value(terminal_rate) <= ledger.value(
            growth
        ):
            raise ValuationError(
                "Require discount rate > -1 and terminal rate > growth > -1"
            )
        nxt = nonnegative(money(args["terminal_next_flow"]))
        if dated:
            factors, factor, timing_result = _dated_factors(
                ledger, method["timing"], len(flows)
            )
        else:
            rate = ratio(args["discount_rate"])
            if ledger.value(rate) <= -1:
                raise ValuationError("Discount rate must exceed -1")
            base = ledger.add(
                "discount_base", "sum", [ledger.constant("one", 1), rate], "ratio"
            )
            factors = [
                ledger.add(
                    f"discount/{t}",
                    "power",
                    [base, ledger.constant(f"year-{t}", t)],
                    "ratio",
                )
                for t in range(1, len(flows) + 1)
            ]
            factor = factors[-1]
        present = []
        for t, (flow, cash_factor) in enumerate(zip(flows, factors), 1):
            present.append(ledger.add(f"pv/{t}", "divide", [flow, cash_factor]))
        spread = ledger.add(
            "terminal_spread", "subtract", [terminal_rate, growth], "ratio"
        )
        terminal = ledger.add("terminal_value", "divide", [nxt, spread])
        terminal_pv = ledger.add("pv_terminal", "divide", [terminal, factor])
        result = ledger.add("value", "sum", [*present, terminal_pv])
        extras = {"terminal_value": terminal, "pv_terminal": terminal_pv}
        if ledger.value(result) != 0:
            extras["terminal_share"] = ledger.add(
                "terminal_share", "divide", [terminal_pv, result], "ratio"
            )
        value_type = "operating_enterprise" if kind == "DCF_FCFF" else "equity"
    elif kind == "INCOME_EQUITY_FINITE":
        _keys(args, {"incomes", "residual_value"})
        incomes = sequence(args["incomes"], "Finite equity incomes", 1200)
        if "timing" not in method:
            raise ValuationError("Finite equity income requires explicit dated timing")
        if args["residual_value"] in args["incomes"]:
            raise ValuationError(
                "Residual value requires an independent input, not a period income"
            )
        residual = money(args["residual_value"])
        factors, horizon, timing_result = _dated_factors(
            ledger,
            method["timing"],
            len(incomes),
            terminal_convention="explicit_equity_residual_at_horizon",
        )
        present = [
            ledger.add(f"pv/{t}", "divide", [income, factor])
            for t, (income, factor) in enumerate(zip(incomes, factors), 1)
        ]
        income_pv = ledger.add("income_pv", "sum", present)
        residual_pv = ledger.add("pv_residual", "divide", [residual, horizon])
        result = ledger.add("value", "sum", [income_pv, residual_pv])
        extras = {
            "income_pv": income_pv,
            "residual_value": residual,
            "pv_residual": residual_pv,
        }
        if ledger.value(result) != 0:
            extras["residual_share"] = ledger.add(
                "residual_share", "divide", [residual_pv, result], "ratio"
            )
    elif kind == "RESIDUAL_INCOME_EQUITY":
        from valuation_residual import residual_income

        _keys(
            args,
            {
                "book_equity",
                "incomes",
                "distributions",
                "contributions",
                "terminal_equity_value",
            },
        )
        incomes = sequence(args["incomes"], "Residual incomes", 1200)
        timing = method.get("timing")
        if not timing or timing["cash_flow_timing"] != "end_period":
            raise ValuationError("Residual income requires explicit end-period timing")
        if (
            timing["rate_model"] == "spot_curve"
            and timing.get("terminal_discount_rate") != timing["rate_ids"][-1]
        ):
            raise ValuationError(
                "Residual income requires the final spot rate at the horizon"
            )
        factors, horizon, timing_result = _dated_factors(
            ledger,
            timing,
            len(incomes),
            terminal_convention="terminal_equity_less_closing_book_equity",
        )
        result, extras, residual_schedule = residual_income(
            ledger, args, factors, horizon
        )
    elif kind == "ECONOMIC_PROFIT":
        from valuation_economic import economic_profit

        _keys(
            args,
            {
                "operating_capital",
                "nopat",
                "net_reinvestment",
                "terminal_enterprise_value",
            },
        )
        nopat = sequence(args["nopat"], "NOPAT amounts", 1200)
        timing = method.get("timing")
        if not timing or timing["cash_flow_timing"] != "end_period":
            raise ValuationError("Economic profit requires explicit end-period timing")
        if (
            timing["rate_model"] == "spot_curve"
            and timing.get("terminal_discount_rate") != timing["rate_ids"][-1]
        ):
            raise ValuationError(
                "Economic profit requires the final spot rate at the horizon"
            )
        factors, horizon, timing_result = _dated_factors(
            ledger,
            timing,
            len(nopat),
            terminal_convention="terminal_enterprise_less_closing_operating_capital",
        )
        result, extras, economic_schedule = economic_profit(
            ledger, args, factors, horizon
        )
        value_type = "operating_enterprise"
    elif kind == "HOLDING_SOTP":
        from valuation_holding import holding_sotp

        _keys(
            args,
            {
                "holdings",
                "parent_assets",
                "parent_liabilities",
                "holding_costs_pv",
                "tax_adjustment",
                "eliminations",
            },
        )
        result, extras, holding_schedule = holding_sotp(ledger, args)
    elif kind == "INCOME_EQUITY":
        _keys(args, {"normalized_equity_income", "cost_equity"})
        result = ledger.add(
            "value",
            "divide",
            [
                positive(money(args["normalized_equity_income"])),
                positive(ratio(args["cost_equity"])),
            ],
        )
    elif kind == "NAV":
        _keys(args, {"assets", "liabilities", "tax_adjustment"})
        assets = ledger.add("assets", "sum", sequence(args["assets"], "Assets"))
        if not isinstance(args["liabilities"], list) or len(args["liabilities"]) > 100:
            raise ValuationError("Liabilities require an explicit list")
        liabilities = ledger.add(
            "liabilities", "sum", [money(ref) for ref in args["liabilities"]]
        )
        net = ledger.add("net_assets", "subtract", [assets, liabilities])
        result = ledger.add("value", "subtract", [net, money(args["tax_adjustment"])])
    elif kind == "MIXED_EQUITY":
        _keys(args, {"adjusted_equity", "incomes", "normal_return", "excess_discount"})
        capital = money(args["adjusted_equity"])
        normal = nonnegative(ratio(args["normal_return"]))
        discount = ratio(args["excess_discount"])
        if ledger.value(discount) <= -1:
            raise ValuationError("Discount rate must exceed -1")
        base = ledger.add(
            "discount_base", "sum", [ledger.constant("one", 1), discount], "ratio"
        )
        normal_income = ledger.add("normal_income", "multiply", [capital, normal])
        present = []
        for t, income in enumerate(sequence(args["incomes"], "Incomes"), 1):
            excess = ledger.add(f"excess/{t}", "subtract", [income, normal_income])
            factor = ledger.add(
                f"discount/{t}",
                "power",
                [base, ledger.constant(f"year-{t}", t)],
                "ratio",
            )
            present.append(ledger.add(f"pv/{t}", "divide", [excess, factor]))
        result = ledger.add("value", "sum", [capital, *present])
    elif kind == "MULTIPLE":
        _keys(args, {"metric", "selected_multiple", "kind"})
        if args["kind"] not in {"EV_EBITDA", "EV_EBIT", "EV_REVENUE", "P_E"}:
            raise ValuationError("Unsupported multiple basis")
        if "comparables" in method:
            from valuation_comparables import calculate_comparables

            comparable_schedule = calculate_comparables(ledger, method)
        result = ledger.add(
            "value",
            "multiply",
            [
                positive(money(args["metric"])),
                positive(ledger.input(args["selected_multiple"], "multiple")),
            ],
        )
        value_type = "equity" if args["kind"] == "P_E" else "operating_enterprise"
    else:
        _keys(args, {"unlevered_value", "pv_tax_shields", "pv_financing_costs"})
        gross = ledger.add(
            "gross",
            "sum",
            [
                money(args["unlevered_value"]),
                nonnegative(money(args["pv_tax_shields"])),
            ],
        )
        result = ledger.add(
            "value", "subtract", [gross, nonnegative(money(args["pv_financing_costs"]))]
        )
        value_type = "operating_enterprise"
    equity = result if value_type == "equity" else None
    if "bridge" in method:
        if value_type != "operating_enterprise":
            raise ValuationError(
                "Debt must not be deducted again from an equity-side result"
            )
        bridge = method["bridge"]
        _keys(
            bridge,
            {
                "financial_debt",
                "debt_like",
                "excess_cash",
                "non_operating_assets",
                "signed_adjustments",
            },
        )
        debt = ledger.add(
            "debt",
            "sum",
            [
                nonnegative(money(bridge["financial_debt"])),
                nonnegative(money(bridge["debt_like"])),
            ],
        )
        net = ledger.add("after_debt", "subtract", [result, debt])
        equity = ledger.add(
            "equity",
            "sum",
            [
                net,
                nonnegative(money(bridge["excess_cash"])),
                nonnegative(money(bridge["non_operating_assets"])),
                money(bridge["signed_adjustments"]),
            ],
        )
    output = {
        "method_id": method["id"],
        "kind": kind,
        "value_type": value_type,
        "value_id": result,
        "equity_id": equity,
        "detail_ids": extras,
        "convention": (
            "explicit_holding_parts"
            if holding_schedule is not None
            else (
                "explicit_dated_discount"
                if timing_result
                else "annual_end_year_constant_explicit_discount"
            )
        ),
        "timing": timing_result,
        "calculations": list(ledger.rows.values()),
    }
    if residual_schedule is not None:
        output["clean_surplus_schedule"] = residual_schedule
    if economic_schedule is not None:
        output["operating_capital_schedule"] = economic_schedule
    if holding_schedule is not None:
        output["holding_schedule"] = holding_schedule
    if comparable_schedule is not None:
        output["comparable_schedule"] = comparable_schedule
    return output

SHA-256: afcec8ce563e01d83fcbd1a2911ddac61b1450b2393202d26af37a6c5e9e9854