"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(quantlib): add the analytics the finance-math layer was missing
Haozhe Wu11f97f9dfede
diff --git a/agent/backtest/factor_costs.py b/agent/backtest/factor_costs.pynew file mode 100644index 000000000..085ba2e6e--- /dev/null+++ b/agent/backtest/factor_costs.py@@ -0,0 +1,416 @@+"""Trading-cost model for factor backtests: ADV caps, impact, borrow.++A long-short factor backtest that rebalances daily on a 500-name universe is+implicitly claiming it can trade every name, in any size, at the close, for a+flat fee. Three things break that claim, and this module prices all three:++**Capacity.** You cannot buy more of a stock in a day than the market trades.+The standard bound is a participation rate -- a fraction of average daily volume+you are willing to be. Beyond it you are the market, not a participant in it.+When a target weight needs more than the cap allows, the position moves *part of+the way* and the shortfall carries into the next period. It is not silently+filled, and it is not silently dropped: both would flatter the backtest, in+opposite directions.++**Impact.** The part you do trade moves the price against you, and the amount is+not linear in size. :mod:`src.quantlib.impact` already owns those models --+this module calls them rather than carrying a second copy.++**Borrow.** The short leg is not free. Someone lends you the stock and charges+for it, and for hard-to-borrow names that fee can exceed the alpha. A long-short+factor reported without borrow cost is reporting a portfolio nobody could have+held.++WHY THIS IS NOT IN THE ENGINE+-----------------------------+``backtest/engines/base.py`` prices costs per *fill*, which is the right model+when there is an order book and a fill sequence. A factor bench has neither: it+has a weight vector per rebalance date. Forcing one abstraction onto the other+would mean inventing fills that never happened. This module therefore works in+weight space, and the two never share a code path.++SIGN AND UNIT CONVENTIONS+-------------------------+* Weights are fractions of capital; a short is negative.+* Every cost this module returns is a POSITIVE drag, to be subtracted from a+ gross return. A function that returned a signed adjustment would eventually be+ added somewhere by mistake.+* ``adv`` is in the same currency as ``capital``, not in shares. Mixing those is+ the classic error here, so the argument names say ``_value`` and the+ docstrings repeat it.+* Rates named ``annual_*`` are annualised decimals; the periods-per-year+ argument converts them, and it has no default because a daily and a monthly+ bench would silently differ by 21x.+"""++from __future__ import annotations++from collections.abc import Sequence+from dataclasses import dataclass++import numpy as np+import pandas as pd++from src.quantlib.impact import DEFAULT_SLIPPAGE_BPS, linear_impact, sqrt_impact++__all__ = [+ "DEFAULT_MAX_PARTICIPATION",+ "IMPACT_MODELS",+ "MARKET_BORROW_RATES",+ "CapacityResult",+ "PeriodCost",+ "apply_adv_capacity",+ "borrow_cost",+ "rebalance_cost",+]++#: Fraction of a name's average daily value a strategy is allowed to be. 10% is+#: the conventional institutional ceiling; above it the participation itself+#: starts to define the price and the impact models stop being descriptive.+DEFAULT_MAX_PARTICIPATION: float = 0.10++#: Impact models callable by name. Both come from ``src.quantlib.impact``; this+#: module owns no impact formula of its own.+IMPACT_MODELS: tuple[str, ...] = ("fixed", "linear", "sqrt")++#: Indicative annual stock-borrow rates for a general-collateral name, by+#: market. These are STARTING POINTS for a caller who has no better number, not+#: measurements: a hard-to-borrow name can cost 20% or more, and nothing in this+#: repository knows which names those are. Pass your own rate when you have one.+MARKET_BORROW_RATES: dict[str, float] = {+ "US": 0.0030,+ "CN": 0.0850,+ "HK": 0.0100,+ "JP": 0.0050,+}+++@dataclass(frozen=True)+class CapacityResult:+ """Weights actually achievable under an ADV participation cap.++ Attributes:+ achieved_weights: Weights after capping, indexed by symbol.+ requested_weights: The weights that were asked for.+ unfilled_weights: ``requested - achieved`` per symbol. Non-zero means+ the strategy wanted a position the market could not give it that+ period; carry this into the next rebalance rather than discarding it.+ capped_symbols: Symbols whose trade hit the cap.+ participation: Realised participation per symbol, as a fraction of ADV.+ max_participation: The cap that was applied.+ """++ achieved_weights: pd.Series+ requested_weights: pd.Series+ unfilled_weights: pd.Series+ capped_symbols: tuple[str, ...]+ participation: pd.Series+ max_participation: float+++@dataclass(frozen=True)+class PeriodCost:+ """All-in trading drag for one rebalance period.++ Attributes:+ impact_cost: Drag from market impact and spread, as a fraction of+ capital. Positive.+ borrow_cost: Drag from borrowing the short leg, as a fraction of+ capital. Positive.+ total_cost: ``impact_cost + borrow_cost``. Positive.+ turnover: One-way turnover actually executed, as a fraction of capital.+ unfilled_turnover: Turnover the ADV cap prevented.+ capped_symbols: Symbols that hit the cap.+ impact_model: Which model priced the impact.+ """++ impact_cost: float+ borrow_cost: float+ total_cost: float+ turnover: float+ unfilled_turnover: float+ capped_symbols: tuple[str, ...]+ impact_model: str+++def _as_aligned(+ target: pd.Series, current: pd.Series+) -> tuple[pd.Series, pd.Series, pd.Index]:+ """Put two weight vectors on one index, filling absent names with zero.++ A name in the target but not the current book is a new position; a name in+ the current book but not the target is a full exit. Both are trades, so+ neither may be dropped by an inner join.++ Args:+ target: Desired weights.+ current: Weights held before the rebalance.++ Returns:+ Tuple of ``(target, current, index)`` on the union index.+ """+ index = target.index.union(current.index)+ return (+ target.reindex(index).fillna(0.0).astype(float),+ current.reindex(index).fillna(0.0).astype(float),+ index,+ )+++def apply_adv_capacity(+ target_weights: pd.Series,+ current_weights: pd.Series,+ adv_value: pd.Series,+ capital: float,+ max_participation: float = DEFAULT_MAX_PARTICIPATION,+) -> CapacityResult:+ """Cap each name's trade at a fraction of its average daily traded value.++ Args:+ target_weights: Desired weights by symbol, shorts negative.+ current_weights: Weights held before this rebalance.+ adv_value: Average daily traded VALUE by symbol, in the same currency as+ ``capital`` -- not a share count.+ capital: Portfolio capital in that currency.+ max_participation: Largest fraction of a name's ADV the strategy may be.++ Returns:+ A :class:`CapacityResult`. A symbol with no ADV entry, or a non-positive+ one, is treated as untradeable this period: its weight stays where it+ was and the whole requested change lands in ``unfilled_weights``. That+ is deliberately the conservative reading -- assuming a name with unknown+ volume is infinitely liquid is how a backtest acquires capacity it never+ had.++ Raises:+ ValueError: If ``capital`` is not positive or ``max_participation`` is+ outside ``(0, 1]``.+ """+ if not capital > 0:+ raise ValueError(f"capital must be positive, got {capital}")+ if not 0.0 < max_participation <= 1.0:+ raise ValueError(+ f"max_participation must be in (0, 1], got {max_participation}"+ )++ target, current, index = _as_aligned(target_weights, current_weights)+ adv = pd.Series(adv_value, dtype=float).reindex(index)++ requested_change = target - current+ # Largest weight change a name can absorb: participation x ADV, expressed+ # as a fraction of capital.+ capacity = (adv * max_participation / capital).fillna(0.0)+ capacity[~np.isfinite(capacity)] = 0.0+ capacity[capacity < 0.0] = 0.0++ allowed_change = requested_change.clip(lower=-capacity, upper=capacity)+ achieved = current + allowed_change+ unfilled = target - achieved++ capped = tuple(+ str(sym)+ for sym in index+ if abs(requested_change[sym]) > capacity[sym] + 1e-15+ and abs(requested_change[sym]) > 0.0+ )+ with np.errstate(divide="ignore", invalid="ignore"):+ participation = (allowed_change.abs() * capital / adv).replace(+ [np.inf, -np.inf], np.nan+ )++ return CapacityResult(+ achieved_weights=achieved,+ requested_weights=target,+ unfilled_weights=unfilled,+ capped_symbols=capped,+ participation=participation,+ max_participation=max_participation,+ )+++def borrow_cost(+ weights: pd.Series,+ periods_per_year: int,+ annual_rate: float | pd.Series | None = None,+ market: str | None = None,+) -> float:+ """Cost of borrowing the short leg for one period.++ Only negative weights are charged: a long position borrows nothing. The+ charge is the absolute short exposure times the pro-rated annual fee.++ Args:+ weights: Portfolio weights, shorts negative.+ periods_per_year: Rebalance periods in a year -- 252 for daily, 12 for+ monthly. No default: a daily and a monthly bench charging the same+ per-period rate differ by 21x, and nothing downstream would notice.+ annual_rate: Annual borrow fee as a decimal, either one rate for the+ whole book or a per-symbol Series. Takes precedence over ``market``.+ market: Key into :data:`MARKET_BORROW_RATES` when no explicit rate is+ supplied. Those values are indicative general-collateral rates, not+ measurements -- see the constant's own note.++ Returns:+ Positive cost as a fraction of capital.++ Raises:+ ValueError: If ``periods_per_year`` is not positive, if neither+ ``annual_rate`` nor ``market`` is supplied, if ``market`` is+ unknown, or if any rate is negative.+ """+ if periods_per_year <= 0:+ raise ValueError(f"periods_per_year must be positive, got {periods_per_year}")++ if annual_rate is None:+ if market is None:+ raise ValueError(+ "supply annual_rate, or market to fall back on an indicative "+ f"general-collateral rate from {sorted(MARKET_BORROW_RATES)}"+ )+ if market not in MARKET_BORROW_RATES:+ raise ValueError(+ f"unknown market {market!r}; known: {sorted(MARKET_BORROW_RATES)}"+ )+ annual_rate = MARKET_BORROW_RATES[market]++ shorts = pd.Series(weights, dtype=float)+ shorts = -shorts[shorts < 0.0]+ if shorts.empty:+ return 0.0++ if isinstance(annual_rate, pd.Series):+ rates = annual_rate.reindex(shorts.index)+ if rates.isna().any():+ missing = sorted(str(s) for s in rates.index[rates.isna()])+ raise ValueError(+ f"annual_rate is missing a rate for shorted symbol(s): {missing}"+ )+ else:+ rates = pd.Series(float(annual_rate), index=shorts.index)++ if (rates < 0.0).any():+ raise ValueError("borrow rates must be non-negative")++ return float((shorts * rates).sum() / periods_per_year)+++def rebalance_cost(+ target_weights: pd.Series,+ current_weights: pd.Series,+ capital: float,+ periods_per_year: int,+ adv_value: pd.Series | None = None,+ max_participation: float = DEFAULT_MAX_PARTICIPATION,+ impact_model: str = "sqrt",+ slippage_bps: float = DEFAULT_SLIPPAGE_BPS,+ impact_coefficient: float = 0.1,+ volatility: float | pd.Series | None = None,+ borrow_annual_rate: float | pd.Series | None = None,+ borrow_market: str | None = None,+) -> tuple[PeriodCost, CapacityResult | None]:+ """Price one rebalance: capacity, then impact, then borrow.++ Args:+ target_weights: Desired weights, shorts negative.+ current_weights: Weights held before the rebalance.+ capital: Portfolio capital.+ periods_per_year: Rebalance periods in a year, for the borrow charge.+ adv_value: Average daily traded VALUE by symbol. When None, no capacity+ cap is applied and ``capped_symbols`` comes back empty -- which is+ an assumption of infinite liquidity and should be stated wherever+ the result is reported.+ max_participation: Participation ceiling for the capacity cap.+ impact_model: One of :data:`IMPACT_MODELS`.+ slippage_bps: Half-spread plus fees, in basis points, charged on every+ unit of turnover regardless of model.+ impact_coefficient: Coefficient handed to the linear or sqrt model.+ volatility: Per-period volatility, required by the ``sqrt`` model.+ borrow_annual_rate: Annual borrow fee, decimal.+ borrow_market: Fallback market key when no explicit rate is given.++ Returns:+ Tuple of the :class:`PeriodCost` and the :class:`CapacityResult` (None+ when no ``adv_value`` was supplied).++ Raises:+ ValueError: If ``impact_model`` is unknown, if the ``sqrt`` model is+ chosen without ``volatility``, or from the functions this delegates+ to.+ """+ if impact_model not in IMPACT_MODELS:+ raise ValueError(+ f"impact_model must be one of {IMPACT_MODELS}, got {impact_model!r}"+ )++ target, current, index = _as_aligned(target_weights, current_weights)++ capacity: CapacityResult | None = None+ if adv_value is not None:+ capacity = apply_adv_capacity(+ target, current, adv_value, capital, max_participation+ )+ achieved = capacity.achieved_weights+ unfilled_turnover = float(capacity.unfilled_weights.abs().sum())+ capped = capacity.capped_symbols+ else:+ achieved = target+ unfilled_turnover = 0.0+ capped = ()++ traded = (achieved - current).abs()+ turnover = float(traded.sum())++ # Spread and fees are charged on every unit of turnover under every model.+ spread_cost = turnover * slippage_bps / 10_000.0++ if impact_model == "fixed" or turnover == 0.0:+ impact = 0.0+ elif impact_model == "linear":+ participation = (+ capacity.participation.reindex(index).fillna(0.0)+ if capacity is not None+ else pd.Series(0.0, index=index)+ )+ # linear_impact prices a fill; here it prices the weighted average+ # participation, and the drag scales with the traded fraction.+ impact = float((traded * participation * impact_coefficient).sum())+ else: # sqrt+ if volatility is None:+ raise ValueError(+ "the sqrt impact model needs a volatility; supply one or choose "+ "impact_model='linear' or 'fixed'"+ )+ vol = (+ pd.Series(volatility, dtype=float).reindex(index).fillna(0.0)+ if isinstance(volatility, pd.Series)+ else pd.Series(float(volatility), index=index)+ )+ participation = (+ capacity.participation.reindex(index).fillna(0.0)+ if capacity is not None+ else pd.Series(0.0, index=index)+ )+ impact = float(+ (traded * impact_coefficient * vol * np.sqrt(participation.clip(lower=0.0))).sum()+ )++ impact_cost = spread_cost + impact+ borrow = borrow_cost(+ achieved,+ periods_per_year=periods_per_year,+ annual_rate=borrow_annual_rate,+ market=borrow_market,+ ) if (borrow_annual_rate is not None or borrow_market is not None) else 0.0++ return (+ PeriodCost(+ impact_cost=impact_cost,+ borrow_cost=borrow,+ total_cost=impact_cost + borrow,+ turnover=turnover,+ unfilled_turnover=unfilled_turnover,+ capped_symbols=capped,+ impact_model=impact_model,+ ),+ capacity,+ )diff --git a/agent/src/entities/cashflow.py b/agent/src/entities/cashflow.pyindex b8259ebae..5fb168a0f 100644--- a/agent/src/entities/cashflow.py+++ b/agent/src/entities/cashflow.py@@ -50,9 +50,13 @@ __all__ = ["CashFlow","CashFlowSeries","CurrencyMismatchError",+ "FxRate",+ "FxRateTable","KIND_DIRECTION",+ "MissingExchangeRateError","VALUATION_KINDS","normalize_kind",+ "translate_cashflows",]#: Canonical kinds whose direction is definitional, mapped to the required sign@@ -416,3 +420,349 @@ class CashFlowSeries:if include_valuations or not flow.is_valuation))+++# ─────────────────────────────────────────────────────────────────────────+# FX translation: turn several single-currency flows into one pre_translated+# series, using each flow's OWN settlement-date rate (never a period-end+# rate -- see ``translate_cashflows``).+# ─────────────────────────────────────────────────────────────────────────+++class MissingExchangeRateError(ValueError):+ """Raised when a cash flow's settlement date has no usable exchange rate.++ Forward-filling silently across a rate gap is exactly the failure mode+ this module refuses by default: a large flow that happens to land inside+ the gap would be translated with the wrong rate, and nothing downstream+ could tell. The explicit, opt-in alternative is+ ``FxRateTable.get_rate(..., allow_stale=True)``.+ """+++@dataclass(frozen=True)+class FxRate:+ """One exchange-rate quote, in the standard FX BASE/QUOTE convention.++ Naming both currencies explicitly -- instead of accepting a bare+ ``rate`` float and a docstring nobody reads -- is the defense against the+ single most common bug in FX-translation code: silently applying the+ reciprocal rate. ``EURUSD = 1.08`` means ``base_currency="EUR"``,+ ``quote_currency="USD"``, ``rate=1.08``: 1 EUR converts to 1.08 USD,+ never the other way around.++ Attributes:+ base_currency: The currency being priced -- in a translation, the+ cash flow's own currency. Normalized to uppercase.+ quote_currency: The currency the rate is expressed in -- in a+ translation, the reporting currency. Normalized to uppercase.+ date: The date this quote applies to.+ rate: Units of ``quote_currency`` per 1 unit of ``base_currency``, so+ ``amount_in_quote = amount_in_base * rate``. Must be finite and+ strictly positive: a zero or negative rate would silently zero+ out, or flip the sign of, every flow translated with it.+ """++ base_currency: str+ quote_currency: str+ date: date+ rate: float++ def __post_init__(self) -> None:+ """Normalize the currencies and date, and validate the rate.++ Raises:+ ValueError: If either currency code is invalid, the date is+ unsupported, or the rate is not finite and strictly positive.+ """+ object.__setattr__(+ self,+ "base_currency",+ normalize_currency(self.base_currency, field_name="base_currency"),+ )+ object.__setattr__(+ self,+ "quote_currency",+ normalize_currency(self.quote_currency, field_name="quote_currency"),+ )+ object.__setattr__(self, "date", normalize_date(self.date))+ try:+ rate = float(self.rate)+ except (TypeError, ValueError) as exc:+ raise ValueError(f"rate must be numeric, got {self.rate!r}") from exc+ if not math.isfinite(rate) or rate <= 0:+ raise ValueError(+ f"rate must be finite and strictly positive -- it is "+ f"quote-per-base units -- got {rate!r}; a zero or negative "+ "rate would silently zero out or flip the sign of every flow "+ "translated with it"+ )+ object.__setattr__(self, "rate", rate)+++@dataclass(frozen=True)+class FxRateTable:+ """A lookup of FX rates, every entry quoted against one fixed currency.++ All entries must share the same ``quote_currency``: a table that mixed+ quote currencies would make "translate to X" ambiguous, so that is+ rejected at construction rather than left to whichever rate happens to be+ looked up first.++ Attributes:+ quote_currency: The single reporting currency every rate quotes+ against. Normalized to uppercase.+ rates: Mapping of ``(base_currency, date) -> FxRate``, keyed by the+ already-normalized currency code and date.+ """++ quote_currency: str+ rates: Mapping[tuple[str, date], FxRate] = field(default_factory=dict)++ def __post_init__(self) -> None:+ """Validate the quote currency and every entry's consistency.++ Raises:+ ValueError: If ``quote_currency`` is invalid, a value is not an+ ``FxRate``, an entry quotes against a different currency than+ the table's, or an entry is stored under a key that does not+ match its own ``(base_currency, date)``.+ """+ quote = normalize_currency(self.quote_currency, field_name="quote_currency")+ rates = dict(self.rates)+ for key, entry in rates.items():+ if not isinstance(entry, FxRate):+ raise ValueError(+ f"FxRateTable entries must be FxRate, got {type(entry).__name__}"+ )+ if entry.quote_currency != quote:+ raise ValueError(+ f"FxRate {entry.base_currency}/{entry.quote_currency}@"+ f"{entry.date} does not quote against this table's "+ f"currency {quote!r}; a table may only hold rates quoted "+ "against one reporting currency"+ )+ expected_key = (entry.base_currency, entry.date)+ if key != expected_key:+ raise ValueError(+ f"FxRate stored under key {key!r} does not match its own "+ f"(base_currency, date) = {expected_key!r}"+ )+ object.__setattr__(self, "quote_currency", quote)+ object.__setattr__(self, "rates", MappingProxyType(rates))++ @classmethod+ def from_rates(cls, rates: Iterable[FxRate], *, quote_currency: str) -> "FxRateTable":+ """Build a table from a sequence of individual quotes.++ Args:+ rates: The quotes, all against ``quote_currency``.+ quote_currency: The reporting currency of the table.++ Returns:+ A new ``FxRateTable`` keyed by ``(base_currency, date)``.++ Raises:+ ValueError: If a member is not an ``FxRate``, two quotes collide+ on the same ``(base_currency, date)`` with different rates,+ or a quote's ``quote_currency`` disagrees with the table's.+ """+ indexed: dict[tuple[str, date], FxRate] = {}+ for entry in rates:+ if not isinstance(entry, FxRate):+ raise ValueError(f"rates must contain FxRate, got {type(entry).__name__}")+ key = (entry.base_currency, entry.date)+ if key in indexed and indexed[key].rate != entry.rate:+ raise ValueError(+ f"conflicting rates for {key}: {indexed[key].rate!r} vs "+ f"{entry.rate!r}"+ )+ indexed[key] = entry+ return cls(quote_currency=quote_currency, rates=indexed)++ @classmethod+ def from_mapping(+ cls,+ mapping: Mapping[tuple[str, "date | datetime | str"], float],+ *,+ quote_currency: str,+ ) -> "FxRateTable":+ """Build a table from ``{(base_currency, date): rate}`` pairs.++ Args:+ mapping: Each value is units of ``quote_currency`` per 1 unit of+ the key's currency, exactly as ``FxRate.rate`` defines it.+ quote_currency: The reporting currency of the table.++ Returns:+ A new ``FxRateTable``.++ Raises:+ ValueError: If a currency code or date in a key is invalid, or a+ rate is not finite and strictly positive.+ """+ rows = [+ FxRate(base_currency=base, quote_currency=quote_currency, date=day, rate=rate)+ for (base, day), rate in mapping.items()+ ]+ return cls.from_rates(rows, quote_currency=quote_currency)++ def get_rate(+ self,+ base_currency: str,+ on_date: date,+ *,+ allow_stale: bool = False,+ max_staleness_days: int | None = None,+ ) -> tuple[FxRate, bool]:+ """Look up the rate to translate ``base_currency`` on ``on_date``.++ Only a same-day or an earlier quote is ever used: translating a flow+ with a rate quoted *after* it settled would leak future information+ into the past, which is worse than an outright missing rate.++ Args:+ base_currency: Currency being priced.+ on_date: The flow's own settlement date -- never a series end+ date. Applying one period-end rate to every flow is the+ classic mistake this table exists to prevent.+ allow_stale: When ``on_date`` has no exact quote, search backward+ for the most recent earlier one instead of raising. Off by+ default: reusing a stale rate without being asked is the+ silent forward-fill-through-a-gap failure mode this module+ refuses by default.+ max_staleness_days: With ``allow_stale=True``, how many days+ before ``on_date`` a reused quote may be. ``None`` means an+ unbounded backward search.++ Returns:+ A tuple of the ``FxRate`` used and whether it was stale (its+ ``date`` is earlier than ``on_date``).++ Raises:+ MissingExchangeRateError: If there is no exact same-day quote and+ either ``allow_stale`` is False, or no earlier quote exists+ (within ``max_staleness_days`` when given).+ """+ base = normalize_currency(base_currency, field_name="base_currency")+ day = normalize_date(on_date)++ exact = self.rates.get((base, day))+ if exact is not None:+ return exact, False++ if not allow_stale:+ raise MissingExchangeRateError(+ f"no {base}/{self.quote_currency} rate for {day}; pass "+ "allow_stale=True to reuse the most recent earlier rate "+ "instead -- stale reuse is flagged on the translated flow, "+ "never applied silently"+ )++ candidates = [+ entry+ for (entry_base, entry_date), entry in self.rates.items()+ if entry_base == base and entry_date <= day+ ]+ if max_staleness_days is not None:+ candidates = [+ entry+ for entry in candidates+ if (day - entry.date).days <= max_staleness_days+ ]+ if not candidates:+ bound = (+ f" within {max_staleness_days} days" if max_staleness_days is not None else ""+ )+ raise MissingExchangeRateError(+ f"no {base}/{self.quote_currency} rate on or before {day}{bound}"+ )+ best = max(candidates, key=lambda entry: entry.date)+ return best, True+++def translate_cashflows(+ flows: CashFlowSeries | Iterable[CashFlow],+ rate_table: FxRateTable,+ *,+ allow_stale_rates: bool = False,+ max_staleness_days: int | None = None,+) -> CashFlowSeries:+ """Convert flows in one or more currencies into ``rate_table``'s currency.++ Each flow is converted using the FX rate quoted on **that flow's own+ settlement date** -- never a single series-level or period-end rate.+ Applying one end-of-period rate to every flow is the most common+ real-world FX-translation bug: it looks correct on the aggregate total+ while silently mispricing every individual flow that did not happen to+ settle on that date.++ Translation is a lossy operation -- once flows are summed, the+ original-currency detail cannot be recovered from the total alone -- so+ every translated flow keeps its original amount, currency, and the exact+ rate and rate date used, recorded in+ ``metadata["fx_original_amount"]``, ``metadata["fx_original_currency"]``,+ ``metadata["fx_rate"]``, ``metadata["fx_rate_date"]``, and+ ``metadata["fx_rate_is_stale"]``.++ Args:+ flows: The source flows, in any mix of currencies.+ rate_table: Rates to translate with; see ``FxRateTable``. Its+ ``quote_currency`` becomes the returned series' currency.+ allow_stale_rates: Forwarded to ``FxRateTable.get_rate``. Off by+ default, so a settlement date with no exact quote raises rather+ than silently reusing an older one.+ max_staleness_days: Forwarded to ``FxRateTable.get_rate``.++ Returns:+ A ``CashFlowSeries`` with ``pre_translated=True`` and+ ``currency=rate_table.quote_currency``.++ Raises:+ MissingExchangeRateError: If a flow's currency has no usable rate for+ its settlement date; see ``allow_stale_rates``.+ ValueError: If ``flows`` contains a member that is not a ``CashFlow``.+ """+ translated: list[CashFlow] = []+ for flow in flows:+ if not isinstance(flow, CashFlow):+ raise ValueError(f"flows must contain CashFlow, got {type(flow).__name__}")++ if flow.currency == rate_table.quote_currency:+ converted_amount = flow.amount+ rate_used = 1.0+ rate_date = flow.date+ is_stale = False+ else:+ fx_rate, is_stale = rate_table.get_rate(+ flow.currency,+ flow.date,+ allow_stale=allow_stale_rates,+ max_staleness_days=max_staleness_days,+ )+ converted_amount = flow.amount * fx_rate.rate+ rate_used = fx_rate.rate+ rate_date = fx_rate.date++ metadata = dict(flow.metadata)+ metadata["fx_original_amount"] = flow.amount+ metadata["fx_original_currency"] = flow.currency+ metadata["fx_rate"] = rate_used+ metadata["fx_rate_date"] = rate_date+ metadata["fx_rate_is_stale"] = is_stale++ translated.append(+ CashFlow(+ date=flow.date,+ amount=converted_amount,+ kind=flow.kind,+ currency=rate_table.quote_currency,+ metadata=metadata,+ )+ )++ return CashFlowSeries(+ flows=tuple(translated),+ currency=rate_table.quote_currency,+ pre_translated=True,+ )diff --git a/agent/src/entities/ingest.py b/agent/src/entities/ingest.pyindex ae3eda7a7..683f3b57f 100644--- a/agent/src/entities/ingest.py+++ b/agent/src/entities/ingest.py@@ -23,16 +23,28 @@ from __future__ import annotationsimport csvimport logging+import math+from dataclasses import dataclass, fieldfrom datetime import date, datetimefrom pathlib import Path+from types import MappingProxyTypefrom typing import Any, Iterable, Mapping, Sequencefrom src.entities.cashflow import CashFlow, CashFlowSeries+from src.entities.cashflow import normalize_kindfrom src.entities.models import normalize_date+from src.entities.models import normalize_currencylogger = logging.getLogger(__name__)-__all__ = ["CashFlowIngestError", "load_cashflows"]+__all__ = [+ "CashFlowIngestError",+ "EntityPanel",+ "PanelIngestError",+ "PanelObservation",+ "load_cashflows",+ "load_panel",+]#: Canonical field -> the column names accepted for it without an explicit#: mapping. Matching is case-insensitive and ignores spaces and underscores.@@ -472,3 +484,824 @@ def load_cashflows(currency=currency,pre_translated=pre_translated,)+++# ─────────────────────────────────────────────────────────────────────────+# Entity x date x metric panels: the non-bar counterpart to load_cashflows+# for data that is not a signed cash movement (a NAV series, an exposure or+# headcount table, any per-entity time series a bar engine cannot hold).+# This path never touches ``backtest/loaders`` or ``backtest/runner`` -- see+# the module docstring and the ``src.entities`` package note on staying+# parallel to the bar engines.+# ─────────────────────────────────────────────────────────────────────────+++class PanelIngestError(ValueError):+ """Raised when an entity x date x metric panel file cannot be read.++ Mirrors ``CashFlowIngestError``'s contract: never return ``None`` or a+ silently-empty result to mean "could not read this"; name the file, the+ row or column, and the fix.+ """+++#: Canonical panel field -> column-name aliases accepted without an explicit+#: mapping. Reuses ``DEFAULT_COLUMN_ALIASES`` wherever the concept already+#: exists there (``date``, ``currency``, and ``value``/"amount"), so date and+#: currency columns are recognised by the exact same names as in+#: ``load_cashflows``.+_PANEL_ENTITY_ALIASES: tuple[str, ...] = (+ "entity",+ "entityid",+ "id",+ "ticker",+ "symbol",+ "instrument",+ "instrumentid",+)+_PANEL_METRIC_ALIASES: tuple[str, ...] = ("metric", "field", "measure", "item")+_PANEL_UNIT_ALIASES: tuple[str, ...] = ("unit", "units", "uom")++_PANEL_COLUMN_ALIASES: Mapping[str, tuple[str, ...]] = {+ "entity": _PANEL_ENTITY_ALIASES,+ "date": DEFAULT_COLUMN_ALIASES["date"],+ "metric": _PANEL_METRIC_ALIASES,+ "value": DEFAULT_COLUMN_ALIASES["amount"],+ "currency": DEFAULT_COLUMN_ALIASES["currency"],+ "unit": _PANEL_UNIT_ALIASES,+}++#: Layouts ``load_panel`` recognises; see its docstring for each shape.+_PANEL_LAYOUTS: tuple[str, ...] = ("long", "wide_dates_rows", "wide_entities_rows")+++@dataclass(frozen=True)+class PanelObservation:+ """One (entity, date, metric) observation in a non-bar data panel.++ The generic counterpart to ``CashFlow``: instead of a signed settled+ amount it carries an arbitrary metric value (a NAV level, an exposure, a+ headcount) for a named entity on a date. It has no ``open``/``high``/+ ``low``/``close`` fields and is not shaped like an OHLC bar, so it cannot+ be mistaken for one by a bar engine.++ Attributes:+ entity_id: Identifier of the entity or instrument this value belongs+ to, e.g. a fund id or a ticker.+ date: Observation date.+ metric: Canonical metric label, e.g. ``"nav"`` or ``"exposure"``.+ Normalized via ``normalize_kind`` so ``"NAV"``/``"Nav"``/``"nav"``+ are recognised as the same metric.+ value: The observed numeric value.+ currency: Required currency code for the value, normalized to+ uppercase.+ unit: Required free-form unit label, e.g. ``"USD"``, ``"shares"``,+ ``"pct"``, ``"headcount"``. An exposure or NAV figure with no+ unit label is exactly the kind of ambiguous number this loader+ refuses to produce.+ metadata: Unmapped source columns, preserved verbatim.+ """++ entity_id: str+ date: date+ metric: str+ value: float+ currency: str+ unit: str+ metadata: Mapping[str, Any] = field(default_factory=dict)++ def __post_init__(self) -> None:+ """Normalize every field and validate the required ones are present.++ Raises:+ PanelIngestError: If ``entity_id``, ``currency``, or ``unit`` is+ blank, or ``value`` is not a finite number.+ ValueError: If ``date`` is unsupported or ``metadata`` is not a+ mapping.+ """+ entity = self.entity_id.strip() if isinstance(self.entity_id, str) else ""+ if not entity:+ raise PanelIngestError("entity_id is required and cannot be empty")+ object.__setattr__(self, "entity_id", entity)+ object.__setattr__(self, "date", normalize_date(self.date))+ object.__setattr__(self, "metric", normalize_kind(self.metric))++ try:+ value = float(self.value)+ except (TypeError, ValueError) as exc:+ raise PanelIngestError(f"value must be numeric, got {self.value!r}") from exc+ if not math.isfinite(value):+ raise PanelIngestError(+ f"value must be a finite number, got {self.value!r}; a missing "+ "value must be fixed at the source, not carried as NaN"+ )+ object.__setattr__(self, "value", value)++ currency = self.currency.strip() if isinstance(self.currency, str) else ""+ if not currency:+ raise PanelIngestError("currency is required and cannot be empty")+ object.__setattr__(self, "currency", normalize_currency(currency))++ unit = self.unit.strip() if isinstance(self.unit, str) else ""+ if not unit:+ raise PanelIngestError("unit is required and cannot be empty")+ object.__setattr__(self, "unit", unit)++ if not isinstance(self.metadata, Mapping):+ raise ValueError(+ f"metadata must be a mapping, got {type(self.metadata).__name__}"+ )+ object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))+++@dataclass(frozen=True)+class EntityPanel:+ """An immutable, ordered collection of ``PanelObservation``.++ The panel counterpart to ``CashFlowSeries``, on the same non-bar+ ingestion path. Deliberately not a ``pandas.DataFrame`` shaped like an+ OHLC bar frame -- nothing in this class or ``load_panel`` reaches into+ ``backtest/loaders`` or ``backtest/runner``.++ Attributes:+ observations: The observations, ordered by ``(entity_id, date,+ metric)``.+ """++ observations: tuple[PanelObservation, ...] = ()++ def __post_init__(self) -> None:+ """Validate membership and impose a stable (entity, date) order.++ Raises:+ PanelIngestError: If a member is not a ``PanelObservation``.+ """+ obs = tuple(self.observations)+ for item in obs:+ if not isinstance(item, PanelObservation):+ raise PanelIngestError(+ f"EntityPanel members must be PanelObservation, got "+ f"{type(item).__name__}"+ )+ object.__setattr__(+ self,+ "observations",+ tuple(sorted(obs, key=lambda o: (o.entity_id, o.date, o.metric))),+ )++ def __iter__(self) -> Iterable[PanelObservation]:+ """Iterate the observations in ``(entity_id, date, metric)`` order.++ Returns:+ An iterator over ``PanelObservation``.+ """+ return iter(self.observations)++ def __len__(self) -> int:+ """Return the number of observations.++ Returns:+ Count of observations, zero for an empty panel.+ """+ return len(self.observations)++ @property+ def is_empty(self) -> bool:+ """Whether the panel holds no observations.++ Returns:+ True when there are zero observations.+ """+ return not self.observations++ def entities(self) -> tuple[str, ...]:+ """Return the distinct entity ids present, sorted.++ Returns:+ Tuple of entity ids; empty for an empty panel.+ """+ return tuple(sorted({o.entity_id for o in self.observations}))++ def metrics(self) -> tuple[str, ...]:+ """Return the distinct metric labels present, sorted.++ Returns:+ Tuple of canonical metric labels; empty for an empty panel.+ """+ return tuple(sorted({o.metric for o in self.observations}))+++def _resolve_panel_long_columns(+ header: Sequence[str],+ columns: Mapping[str, str] | None,+ path: Path,+) -> dict[str, str]:+ """Map canonical panel fields onto a long-layout file's column headers.++ Mirrors ``_resolve_columns``'s matching strategy (case-insensitive alias+ lookup via ``_canonical``, with explicit overrides taking precedence) for+ the panel's own field set. ``_resolve_columns`` itself is hard-wired to+ ``DEFAULT_COLUMN_ALIASES`` and cash-flow's ``date``/``amount``/``kind``/+ ``currency`` fields, so it cannot be reused directly for ``entity`` and+ ``metric``.++ Args:+ header: Column names as they appear in the file.+ columns: Explicit overrides, canonical field -> file column name.+ path: File path, used only for error messages.++ Returns:+ Mapping of canonical field name to the file's column name, containing+ only fields that were actually found.++ Raises:+ PanelIngestError: If an explicit override names a column the file+ does not contain, or overrides an unknown field.+ """+ resolved: dict[str, str] = {}+ lookup = {_canonical(col): col for col in header}++ if columns:+ for field_name, source_name in columns.items():+ if field_name not in _PANEL_COLUMN_ALIASES:+ known = ", ".join(sorted(_PANEL_COLUMN_ALIASES))+ raise PanelIngestError(+ f"{path}: unknown column mapping {field_name!r}; "+ f"mappable fields are: {known}"+ )+ if source_name not in header:+ raise PanelIngestError(+ f"{path}: mapped column {source_name!r} for field "+ f"{field_name!r} is not in the file. Columns present: "+ f"{', '.join(header)}"+ )+ resolved[field_name] = source_name++ for field_name, aliases in _PANEL_COLUMN_ALIASES.items():+ if field_name in resolved:+ continue+ for alias in aliases:+ if alias in lookup:+ resolved[field_name] = lookup[alias]+ break++ return resolved+++def _looks_like_date(text: str, date_format: str | None) -> bool:+ """Best-effort probe for whether a header cell parses as a date.++ Used only during layout inference, by reusing ``_parse_date`` itself+ rather than a second date-parsing routine. A parse failure here means+ "not a date" for inference purposes, not an error to surface.++ Args:+ text: Candidate header cell.+ date_format: ``strptime`` format to try, or ``None`` for ISO-8601.++ Returns:+ True if the text parses as a date under the given format.+ """+ try:+ _parse_date(text, date_format, Path("<layout-inference>"), 0)+ return True+ except CashFlowIngestError:+ return False+++def _infer_panel_layout(header: Sequence[str], date_format: str | None, path: Path) -> str:+ """Infer a panel file's layout from its header, or raise if ambiguous.++ A header naming entity/date/metric/value columns is read as ``"long"``.+ Otherwise, a header whose first column is date-like and whose remaining+ columns are not all dates is read as ``"wide_dates_rows"``; a header+ whose first column is entity-like and whose remaining columns are all+ parseable dates is read as ``"wide_entities_rows"``. A header naming a+ ``metric`` column is never read as wide, since a wide table has nowhere+ to put a metric column. Any header that does not unambiguously match one+ shape raises rather than guessing, since silently picking the wrong+ layout mislabels every value with the wrong entity or date.++ Args:+ header: Column names as they appear in the file.+ date_format: ``strptime`` format used to probe header cells for+ ``wide_entities_rows``, or ``None`` to require ISO-8601 there.+ path: File path, used only for error messages.++ Returns:+ One of ``_PANEL_LAYOUTS``.++ Raises:+ PanelIngestError: If the header matches none of the recognised+ shapes.+ """+ date_aliases = {_canonical(a) for a in DEFAULT_COLUMN_ALIASES["date"]}+ entity_aliases = {_canonical(a) for a in _PANEL_ENTITY_ALIASES}+ metric_aliases = {_canonical(a) for a in _PANEL_METRIC_ALIASES}+ value_aliases = {_canonical(a) for a in DEFAULT_COLUMN_ALIASES["amount"]}++ lookup = {_canonical(col) for col in header}+ has_entity = bool(lookup & entity_aliases)+ has_date = bool(lookup & date_aliases)+ has_metric = bool(lookup & metric_aliases)+ has_value = bool(lookup & value_aliases)+ if has_entity and has_date and has_metric and has_value:+ return "long"++ first = _canonical(header[0])+ rest = list(header[1:])+ first_is_date_like = first in date_aliases+ first_is_entity_like = first in entity_aliases+ rest_are_dates = bool(rest) and all(_looks_like_date(col, date_format) for col in rest)++ if first_is_date_like and rest and not rest_are_dates and not has_metric:+ return "wide_dates_rows"+ if first_is_entity_like and rest and rest_are_dates and not has_metric:+ return "wide_entities_rows"++ raise PanelIngestError(+ f"{path}: could not infer a panel layout from the header "+ f"({', '.join(header)}); pass layout='long', layout='wide_dates_rows', "+ "or layout='wide_entities_rows' explicitly"+ )+++def _parse_panel_amount(+ raw: str, path: Path, row_number: int, decimal_separator: str | None+) -> float:+ """Parse a panel value cell, reusing ``_parse_amount``.++ Args:+ raw: Raw cell text.+ path: File path, used only for error messages.+ row_number: 1-based data row number, used only for error messages.+ decimal_separator: Declared decimal separator, or ``None`` to infer.++ Returns:+ The parsed float.++ Raises:+ PanelIngestError: If the cell is blank, not numeric, or ambiguously+ grouped -- normalizes ``_parse_amount``'s ``CashFlowIngestError``+ so every error ``load_panel`` raises shares one type.+ """+ try:+ return _parse_amount(raw, path, row_number, decimal_separator)+ except CashFlowIngestError as exc:+ raise PanelIngestError(str(exc)) from exc+++def _parse_panel_date(+ raw: str, date_format: str | None, path: Path, row_number: int+) -> date:+ """Parse a panel date cell, reusing ``_parse_date``.++ Args:+ raw: Raw cell text.+ date_format: ``strptime`` format, or ``None`` to require ISO-8601.+ path: File path, used only for error messages.+ row_number: 1-based data row number, used only for error messages.++ Returns:+ The parsed ``datetime.date``.++ Raises:+ PanelIngestError: If the cell is blank or does not parse --+ normalizes ``_parse_date``'s ``CashFlowIngestError`` so every+ error ``load_panel`` raises shares one type.+ """+ try:+ return _parse_date(raw, date_format, path, row_number)+ except CashFlowIngestError as exc:+ raise PanelIngestError(str(exc)) from exc+++def _load_panel_long(+ path: Path,+ header: list[str],+ rows: list[dict[str, str]],+ *,+ columns: Mapping[str, str] | None,+ entity: str | None,+ metric: str | None,+ currency: str | None,+ unit: str | None,+ date_format: str | None,+ decimal_separator: str | None,+ metadata_columns: Iterable[str] | None,+) -> "EntityPanel":+ """Parse a long-layout (entity, date, metric, value) panel file.++ Args:+ path: File path, used only for error messages.+ header: Column names as they appear in the file.+ rows: Row dicts as read by ``_read_rows``.+ columns: Explicit column-name overrides; see ``load_panel``.+ entity: Fallback entity id for rows with no entity column.+ metric: Fallback metric label for rows with no metric column.+ currency: Fallback currency for rows with no currency column.+ unit: Fallback unit for rows with no unit column.+ date_format: ``strptime`` format for the date column.+ decimal_separator: Declared decimal separator, or ``None`` to infer.+ metadata_columns: Restrict preserved metadata to these columns.++ Returns:+ An ``EntityPanel``.++ Raises:+ PanelIngestError: If a required column/argument is missing or a row+ fails to parse.+ """+ resolved = _resolve_panel_long_columns(header, columns, path)++ for required in ("date", "value"):+ if required not in resolved:+ raise PanelIngestError(+ f"{path}: required column {required!r} not found. Columns "+ f"present: {', '.join(header)}. Pass columns={{{required!r}: "+ "'<your column>'}} to map it."+ )++ entity_column = resolved.get("entity")+ if entity_column is None and entity is None:+ raise PanelIngestError(+ f"{path}: no entity column found and no entity=... given. "+ f"Columns present: {', '.join(header)}."+ )++ metric_column = resolved.get("metric")+ if metric_column is None and metric is None:+ raise PanelIngestError(+ f"{path}: no metric column found and no metric=... given. "+ f"Columns present: {', '.join(header)}."+ )++ currency_column = resolved.get("currency")+ if currency_column is None and currency is None:+ raise PanelIngestError(+ f"{path}: no currency column found and no currency=... given. "+ "Currency is required; it is never defaulted, because an "+ "unlabelled figure silently corrupts every downstream use."+ )++ unit_column = resolved.get("unit")+ if unit_column is None and unit is None:+ raise PanelIngestError(+ f"{path}: no unit column found and no unit=... given. Unit is "+ "required; it is never defaulted, because an unlabelled figure "+ "silently corrupts every downstream use."+ )++ mapped_columns = set(resolved.values())+ if metadata_columns is None:+ extra_columns = [col for col in header if col not in mapped_columns]+ else:+ wanted = set(metadata_columns)+ missing = wanted - set(header)+ if missing:+ raise PanelIngestError(+ f"{path}: metadata_columns not in file: {', '.join(sorted(missing))}"+ )+ extra_columns = [col for col in header if col in wanted]++ observations: list[PanelObservation] = []+ for offset, row in enumerate(rows):+ row_number = offset + 1+ if all(not (value or "").strip() for value in row.values()):+ continue # trailing blank line++ row_entity = entity+ if entity_column is not None:+ raw_entity = (row.get(entity_column) or "").strip()+ if raw_entity:+ row_entity = raw_entity+ if not row_entity:+ raise PanelIngestError(+ f"{path} row {row_number}: entity is blank and no entity=... "+ "fallback was given"+ )++ row_metric = metric+ if metric_column is not None:+ raw_metric = (row.get(metric_column) or "").strip()+ if raw_metric:+ row_metric = raw_metric+ if not row_metric:+ raise PanelIngestError(+ f"{path} row {row_number}: metric is blank and no metric=... "+ "fallback was given"+ )++ row_currency = currency+ if currency_column is not None:+ raw_currency = (row.get(currency_column) or "").strip()+ if raw_currency:+ row_currency = raw_currency+ if not row_currency:+ raise PanelIngestError(+ f"{path} row {row_number}: currency is blank and no "+ "currency=... fallback was given"+ )++ row_unit = unit+ if unit_column is not None:+ raw_unit = (row.get(unit_column) or "").strip()+ if raw_unit:+ row_unit = raw_unit+ if not row_unit:+ raise PanelIngestError(+ f"{path} row {row_number}: unit is blank and no unit=... "+ "fallback was given"+ )++ value = _parse_panel_amount(+ row.get(resolved["value"], ""), path, row_number, decimal_separator+ )++ metadata: dict[str, Any] = {+ col: row[col] for col in extra_columns if (row.get(col) or "").strip()+ }+ metadata["source_file"] = str(path)+ metadata["source_row"] = row_number++ try:+ observations.append(+ PanelObservation(+ entity_id=row_entity,+ date=_parse_panel_date(+ row.get(resolved["date"], ""), date_format, path, row_number+ ),+ metric=row_metric,+ value=value,+ currency=row_currency,+ unit=row_unit,+ metadata=metadata,+ )+ )+ except PanelIngestError:+ raise+ except ValueError as exc:+ raise PanelIngestError(f"{path} row {row_number}: {exc}") from exc++ logger.info("loaded %d panel observations from %s (layout=long)", len(observations), path)+ return EntityPanel(observations=tuple(observations))+++def _load_panel_wide(+ path: Path,+ header: list[str],+ rows: list[dict[str, str]],+ *,+ layout: str,+ metric: str | None,+ currency: str | None,+ unit: str | None,+ date_format: str | None,+ decimal_separator: str | None,+) -> "EntityPanel":+ """Parse a wide-layout panel file.++ ``layout="wide_dates_rows"``: the first column is the observation date+ and every other column is an entity id. ``layout="wide_entities_rows"``:+ the first column is the entity id and every other column header is+ itself a date. A blank cell is treated as "no observation for that+ entity/date", not as zero or an error -- a wide grid legitimately has+ holes, and fabricating a value for one would be worse than omitting it.++ Args:+ path: File path, used only for error messages.+ header: Column names as they appear in the file.+ rows: Row dicts as read by ``_read_rows``.+ layout: ``"wide_dates_rows"`` or ``"wide_entities_rows"``.+ metric: The single metric label every cell in this file represents.+ currency: The currency for every value in this file.+ unit: The unit for every value in this file.+ date_format: ``strptime`` format for date cells/headers.+ decimal_separator: Declared decimal separator, or ``None`` to infer.++ Returns:+ An ``EntityPanel``.++ Raises:+ PanelIngestError: If ``metric``/``currency``/``unit`` is missing, the+ file has fewer than two columns, a column header in+ ``wide_entities_rows`` is not a usable date, or a cell fails to+ parse.+ """+ if metric is None:+ raise PanelIngestError(+ f"{path}: layout={layout!r} needs metric=... -- a wide table has "+ "nowhere to put a metric label; every cell already shares its "+ "row's and column's identity"+ )+ if currency is None:+ raise PanelIngestError(+ f"{path}: layout={layout!r} needs currency=... -- a wide table "+ "has no currency column, and currency is never defaulted"+ )+ if unit is None:+ raise PanelIngestError(+ f"{path}: layout={layout!r} needs unit=... -- a wide table has "+ "no unit column, and unit is never defaulted"+ )+ if len(header) < 2:+ raise PanelIngestError(+ f"{path}: layout={layout!r} needs at least one column besides "+ f"the first (row-label) column. Columns present: {', '.join(header)}"+ )++ row_label_column = header[0]+ series_columns = list(header[1:])++ column_dates: dict[str, date] = {}+ if layout == "wide_entities_rows":+ for column_name in series_columns:+ try:+ column_dates[column_name] = _parse_panel_date(+ column_name, date_format, path, row_number=0+ )+ except PanelIngestError as exc:+ raise PanelIngestError(+ f"{path}: column header {column_name!r} is not a usable "+ f"date ({exc}); wide_entities_rows requires every column "+ "after the first to be a date, or pass layout='long' "+ "with columns=... instead"+ ) from exc++ observations: list[PanelObservation] = []+ for offset, row in enumerate(rows):+ row_number = offset + 1+ if all(not (value or "").strip() for value in row.values()):+ continue # trailing blank line++ row_label_raw = (row.get(row_label_column) or "").strip()+ if not row_label_raw:+ raise PanelIngestError(f"{path} row {row_number}: {row_label_column!r} is blank")++ row_date = (+ _parse_panel_date(row_label_raw, date_format, path, row_number)+ if layout == "wide_dates_rows"+ else None+ )+ row_entity = row_label_raw if layout == "wide_entities_rows" else None++ for column_name in series_columns:+ raw_value = row.get(column_name, "")+ if not (raw_value or "").strip():+ continue # hole in the grid: no observation, not zero++ value = _parse_panel_amount(raw_value, path, row_number, decimal_separator)+ entity_id = column_name.strip() if layout == "wide_dates_rows" else row_entity+ obs_date = row_date if layout == "wide_dates_rows" else column_dates[column_name]++ metadata = {"source_file": str(path), "source_row": row_number}+ try:+ observations.append(+ PanelObservation(+ entity_id=entity_id,+ date=obs_date,+ metric=metric,+ value=value,+ currency=currency,+ unit=unit,+ metadata=metadata,+ )+ )+ except PanelIngestError:+ raise+ except ValueError as exc:+ raise PanelIngestError(f"{path} row {row_number}: {exc}") from exc++ logger.info(+ "loaded %d panel observations from %s (layout=%s)", len(observations), path, layout+ )+ return EntityPanel(observations=tuple(observations))+++def load_panel(+ path: str | Path,+ *,+ layout: str | None = None,+ columns: Mapping[str, str] | None = None,+ entity: str | None = None,+ metric: str | None = None,+ currency: str | None = None,+ unit: str | None = None,+ date_format: str | None = None,+ decimal_separator: str | None = None,+ delimiter: str | None = None,+ encoding: str = "utf-8",+ metadata_columns: Iterable[str] | None = None,+) -> EntityPanel:+ """Load an entity x date x metric panel file into an ``EntityPanel``.++ The ingest module's generic counterpart to ``load_cashflows``, for data+ that is not a signed cash movement -- a NAV series, an exposure or+ headcount table, any per-entity time series a bar engine cannot+ represent. It shares every parsing rule with ``load_cashflows``: dates+ must be ISO-8601 or given an explicit ``date_format``, numeric grouping+ that is genuinely ambiguous must be resolved with ``decimal_separator``,+ and a required field that is missing raises rather than returning+ ``None`` or a silently empty result.++ Three layouts are supported and never guessed silently:++ * ``"long"``: one row per (entity, date, metric[, currency, unit])+ observation, with a column for each.+ * ``"wide_dates_rows"``: one row per date, one column per entity, every+ value sharing a single ``metric`` (required via the ``metric``+ argument, since a wide table has nowhere to put a metric label).+ * ``"wide_entities_rows"``: one row per entity, one column per date,+ values sharing a single ``metric`` in the same way.++ When ``layout`` is omitted, it is inferred from the header -- see+ ``_infer_panel_layout``. Layout inference looks only at the raw header,+ not at ``columns=...``; a file with exotic column names should pass+ ``layout="long"`` explicitly together with ``columns=...`` rather than+ rely on inference.++ A wide layout's blank cell means "no observation for that entity/date"+ and is skipped, not treated as zero: a grid legitimately has holes.++ Args:+ path: Path to the file. ``.csv``, ``.tsv``, and ``.txt`` are+ recognised; any other suffix requires an explicit ``delimiter``.+ layout: ``"long"``, ``"wide_dates_rows"``, or ``"wide_entities_rows"``.+ ``None`` to infer from the header.+ columns: Explicit mapping of canonical field to file column name for+ the ``"long"`` layout. Canonical fields are ``entity``, ``date``,+ ``metric``, ``value``, ``currency``, ``unit``.+ entity: Fallback entity id for ``"long"`` rows with no entity column.+ Not used by the wide layouts, where each row/column already+ names its own entity.+ metric: Fallback metric label for ``"long"`` rows with no metric+ column; required for both wide layouts.+ currency: Currency for every row. Required when the file has no+ currency column (``"long"``) or always (wide layouts).+ unit: Unit label for every row. Required when the file has no unit+ column (``"long"``) or always (wide layouts).+ date_format: ``strptime`` format for date cells -- the date column in+ ``"long"``/``"wide_dates_rows"``, or the date-valued column+ headers in ``"wide_entities_rows"``. Omit only when the dates are+ ISO-8601.+ decimal_separator: ``"."`` or ``","``; needed only for ambiguous+ grouped numbers such as a bare ``"1,234"``.+ delimiter: Field delimiter; inferred from the suffix when omitted.+ encoding: Text encoding of the file.+ metadata_columns: Restrict preserved metadata to these ``"long"``+ columns. By default every unmapped column is preserved. Not+ applicable to wide layouts, which have no unmapped columns.++ Returns:+ An ``EntityPanel`` ordered by ``(entity_id, date, metric)``. A+ ``"long"`` file with a header but no data rows yields an empty panel,+ matching ``load_cashflows``.++ Raises:+ PanelIngestError: If the file is missing, unreadable, or has no+ header row; the layout cannot be determined or is invalid; a+ required column or argument is absent; or any cell fails to+ parse.+ ValueError: If ``decimal_separator`` is neither ``"."`` nor ``","``.+ """+ if decimal_separator is not None and decimal_separator not in _DECIMAL_SEPARATORS:+ raise ValueError(+ f"decimal_separator must be one of {_DECIMAL_SEPARATORS}, "+ f"got {decimal_separator!r}"+ )+ if layout is not None and layout not in _PANEL_LAYOUTS:+ raise PanelIngestError(f"layout must be one of {_PANEL_LAYOUTS}, got {layout!r}")++ path = Path(path).expanduser()+ try:+ header, rows = _read_rows(path, delimiter, encoding)+ except CashFlowIngestError as exc:+ raise PanelIngestError(str(exc)) from exc++ resolved_layout = layout or _infer_panel_layout(header, date_format, path)++ if resolved_layout == "long":+ return _load_panel_long(+ path,+ header,+ rows,+ columns=columns,+ entity=entity,+ metric=metric,+ currency=currency,+ unit=unit,+ date_format=date_format,+ decimal_separator=decimal_separator,+ metadata_columns=metadata_columns,+ )+ return _load_panel_wide(+ path,+ header,+ rows,+ layout=resolved_layout,+ metric=metric,+ currency=currency,+ unit=unit,+ date_format=date_format,+ decimal_separator=decimal_separator,+ )diff --git a/agent/src/governance/__init__.py b/agent/src/governance/__init__.pynew file mode 100644index 000000000..8bb96600c--- /dev/null+++ b/agent/src/governance/__init__.py@@ -0,0 +1,63 @@+"""Governance primitives: run manifests + a tamper-evident hash-chained ledger.++Two independent pieces, both standalone (no dependency on the protected+``src/agent/`` tree, no wall-clock reads):++- ``manifest``: :func:`build_run_manifest` fingerprints a run's methodology+ composition (system prompt hash, injected-skill content hashes, tool+ registry, key package versions) into one deterministic ``manifest_hash``,+ and :func:`diff_manifests` names exactly what changed between two runs.+- ``ledger``: :func:`append_record` / :func:`verify_chain` implement a+ generic hash-chained, fsynced, append-only JSONL ledger. ``src/live/audit.py``+ wires this in as an opt-in ``chain=True`` mode on its existing+ ``write_live_action`` — see that module's docstring for the integration.++Neither module writes into a real run directory or the live-action ledger+by itself; callers supply paths/composition data explicitly.+"""++from src.governance.ledger import (+ EXPORT_FORMAT,+ GENESIS_PREV_HASH,+ ChainBreak,+ ChainVerificationResult,+ LedgerCorruptionError,+ append_record,+ build_export,+ compute_record_hash,+ export_chain_to_file,+ verify_chain,+ verify_export,+)+from src.governance.manifest import (+ ManifestDiff,+ RunManifest,+ SkillRecord,+ ToolRegistrySnapshot,+ build_run_manifest,+ collect_key_package_versions,+ diff_manifests,+)++__all__ = [+ # ledger+ "EXPORT_FORMAT",+ "GENESIS_PREV_HASH",+ "ChainBreak",+ "ChainVerificationResult",+ "LedgerCorruptionError",+ "append_record",+ "build_export",+ "compute_record_hash",+ "export_chain_to_file",+ "verify_chain",+ "verify_export",+ # manifest+ "ManifestDiff",+ "RunManifest",+ "SkillRecord",+ "ToolRegistrySnapshot",+ "build_run_manifest",+ "collect_key_package_versions",+ "diff_manifests",+]diff --git a/agent/src/governance/ledger.py b/agent/src/governance/ledger.pynew file mode 100644index 000000000..e24e09456--- /dev/null+++ b/agent/src/governance/ledger.py@@ -0,0 +1,738 @@+"""Hash-chained, fsynced, append-only JSONL ledger.++A generic, domain-agnostic primitive for governance/compliance records: each+record embeds ``seq`` (1-based position) and ``prev_record_hash`` (the+previous record's own hash, or :data:`GENESIS_PREV_HASH` for the first+record), then commits to both plus its own payload in ``record_hash``.+Because every record's hash folds in its predecessor's hash, editing or+deleting ANY earlier record breaks the hash of every record chained after+it — that propagation, not a per-line checksum, is what makes tampering+detectable (:func:`verify_chain`).++**Why this exists.** ``src/live/audit.py`` (SPEC.md Consent §5) is the+compliance-grade ledger of every live-money action, but its original write+path was a bare ``open(path, "a").write(line)`` — no fsync (a host crash+could lose the last record while the diagnostic per-run trace, which+already fsyncs every write, would not), no sequencing, no prior-record hash,+and nothing to detect if a line were edited or deleted after the fact. This+module supplies the missing piece; ``src/live/audit.py`` wires it in as an+opt-in ``chain=True`` mode on ``write_live_action`` (see that module for+why it is opt-in and why it writes to a *separate* file rather than+retrofitting the pre-existing plain ``audit.jsonl``).++**Durability.** :func:`append_record` fsyncs the ledger file after every+write by default (mirroring ``src.agent.trace.TraceWriter.write``), and+fsyncs the parent directory the first time the ledger file is created (same+reasoning as ``TraceWriter.__init__``: the directory ENTRY for a brand new+file is itself not durable until the directory is fsynced).++**Concurrency.** A POSIX ``flock`` (``msvcrt`` byte-range lock on Windows)+is held across the read-tail + append critical section so two writers+cannot compute conflicting ``seq``/``prev_record_hash`` values for the same+next slot. This is a liveness optimization against accidental forks, not+the source of the tamper-evidence guarantee — :func:`verify_chain` would+still catch a fork or a corrupted tail even if the lock were bypassed.++**Refuse-to-extend-a-broken-chain.** :func:`append_record` verifies the+ENTIRE existing chain (not just its last line) before appending, and raises+:class:`LedgerCorruptionError` rather than silently building a valid-looking+suffix on top of an already-tampered history. This is O(n) per append,+trading write latency for the strongest available guarantee; the live-action+ledger this backs is low-volume by construction (one record per+order/mandate/breach/halt event, not per market tick — the same volume+argument ``TraceWriter`` makes for "one fsync per record is acceptable"), so+this is judged an acceptable cost rather than a premature optimization+target. A future change under real volume pressure could memoize the tail+state in a small companion file; deliberately not built here without a+demonstrated need for it.+"""++from __future__ import annotations++import hashlib+import json+import logging+import os+from dataclasses import dataclass+from pathlib import Path+from typing import Any, BinaryIO, Iterable, Iterator, Mapping++try: # POSIX advisory lock (Linux/macOS).+ import fcntl+except ImportError: # pragma: no cover - Windows+ fcntl = None # type: ignore[assignment]++try: # Windows advisory byte-range lock.+ import msvcrt+except ImportError: # pragma: no cover - POSIX+ msvcrt = None # type: ignore[assignment]++logger = logging.getLogger(__name__)++__all__ = [+ "GENESIS_PREV_HASH",+ "EXPORT_FORMAT",+ "ChainBreak",+ "ChainVerificationResult",+ "LedgerCorruptionError",+ "compute_record_hash",+ "append_record",+ "verify_chain",+ "build_export",+ "export_chain_to_file",+ "verify_export",+ "DEFAULT_ROTATE_BYTES",+ "archive_segments",+ "rotate_if_needed",+ "verify_chain_with_archives",+]++#: Sentinel ``prev_record_hash`` for the first record in a chain — there is+#: no predecessor to reference.+GENESIS_PREV_HASH = "sha256:genesis"++#: Reserved top-level keys written by :func:`append_record`. A caller+#: payload must not set any of these itself.+_CHAIN_FIELDS = frozenset({"seq", "prev_record_hash", "record_hash"})++#: Export envelope format tag (bump on any breaking export-shape change).+EXPORT_FORMAT = "vibe-trading-governance-ledger-export/v1"++_fsync_warned = False+++def _warn_fsync_failure(exc: OSError, target: Any) -> None:+ """Log the first fsync failure for this process, then stay quiet.++ Mirrors ``src.agent.trace.TraceWriter._warn_fsync_failure``: on an+ unsupported filesystem, durability degrades to flush-only rather than+ failing the caller (the ledger write already succeeded at the OS-cache+ level; refusing to record a compliance event because fsync is+ unsupported would be worse than a degraded durability guarantee).+ """+ global _fsync_warned+ if _fsync_warned:+ return+ _fsync_warned = True+ logger.warning(+ "governance ledger fsync failed on %s (%s); durability degraded to flush-only",+ target,+ exc,+ )+++def _canonical_json(obj: Any) -> str:+ """Serialize ``obj`` deterministically for hashing (sorted keys, compact)."""+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True, default=str)+++def _sha256_hex(text: str) -> str:+ return hashlib.sha256(text.encode("utf-8")).hexdigest()+++def compute_record_hash(seq: int, prev_record_hash: str, payload: Mapping[str, Any]) -> str:+ """Hash one ledger record so it commits to its position and predecessor.++ Args:+ seq: This record's 1-based position in the chain.+ prev_record_hash: The previous record's own ``record_hash``, or+ :data:`GENESIS_PREV_HASH` for the first record.+ payload: The record body (everything except the three chain fields).++ Returns:+ ``sha256:<hex>`` over the canonical JSON of ``{seq, prev_record_hash,+ payload}``.+ """+ body = _canonical_json(+ {"seq": seq, "prev_record_hash": prev_record_hash, "payload": payload}+ )+ return f"sha256:{_sha256_hex(body)}"+++@dataclass(frozen=True)+class ChainBreak:+ """Where and why :func:`verify_chain` / :func:`verify_export` stopped trusting the chain.++ Attributes:+ index: 0-based line index (within the source lines/records) where+ the break was detected.+ seq: The record's claimed ``seq`` value, when parseable (``None``+ for a line that failed to parse as JSON at all).+ reason: One of ``"malformed_json"``, ``"missing_chain_fields"``,+ ``"seq_gap"``, ``"prev_hash_mismatch"``, ``"record_hash_mismatch"``,+ ``"export_hash_mismatch"``.+ detail: Human-readable detail (expected vs. found).+ """++ index: int+ seq: int | None+ reason: str+ detail: str++ def to_dict(self) -> dict[str, Any]:+ """Return a JSON-serializable representation."""+ return {"index": self.index, "seq": self.seq, "reason": self.reason, "detail": self.detail}+++@dataclass(frozen=True)+class ChainVerificationResult:+ """Outcome of walking a chain end to end.++ Attributes:+ ok: ``True`` iff every record from the first to the last verified+ cleanly.+ record_count: Number of records verified before ``first_break`` (or+ the total record count when ``ok`` is ``True``).+ first_break: The first (earliest) :class:`ChainBreak` encountered, or+ ``None`` when ``ok`` is ``True``.+ """++ ok: bool+ record_count: int+ first_break: ChainBreak | None++ @property+ def broken(self) -> bool:+ """Convenience negation of :attr:`ok`."""+ return not self.ok++ def to_dict(self) -> dict[str, Any]:+ """Return a JSON-serializable representation."""+ return {+ "ok": self.ok,+ "record_count": self.record_count,+ "first_break": None if self.first_break is None else self.first_break.to_dict(),+ }+++class LedgerCorruptionError(RuntimeError):+ """Raised when :func:`append_record` finds the existing chain already broken.++ Refusing to extend a corrupted chain — rather than silently building a+ valid-looking suffix on top of it — is the point: a chain that "heals"+ itself after a break would defeat the entire tamper-evidence guarantee.+ """++ def __init__(self, chain_break: ChainBreak) -> None:+ super().__init__(+ f"ledger chain already broken at index={chain_break.index} "+ f"seq={chain_break.seq} reason={chain_break.reason}: {chain_break.detail}"+ )+ self.chain_break = chain_break+++def _iter_parsed_lines(lines: Iterable[str]) -> Iterator[tuple[int, dict[str, Any] | None, str | None]]:+ """Yield ``(index, parsed_record_or_None, parse_error_or_None)`` for non-blank lines.++ Stops (does not yield further lines) after the first unparsable line —+ content past a corrupted line is not trustworthy context for chain+ verification.+ """+ for index, raw in enumerate(lines):+ line = raw.strip()+ if not line:+ continue+ try:+ yield index, json.loads(line), None+ except json.JSONDecodeError as exc:+ yield index, None, str(exc)+ return+++def _walk_chain(+ record_source: Iterable[tuple[int, dict[str, Any] | None, str | None]],+ start_seq: int = 1,+ start_prev_hash: str = GENESIS_PREV_HASH,+) -> tuple[ChainVerificationResult, int, str]:+ """Walk parsed records once, verifying the chain invariant at each step.++ Args:+ record_source: Parsed records to walk.+ start_seq: Sequence number the first record must carry. Defaults to 1+ (a chain that starts at genesis). A ledger whose earlier segments+ have been sealed by :func:`rotate_if_needed` starts partway through+ the chain instead, and passing the continuation here is what stops+ a rotated file from looking like a corrupt one.+ start_prev_hash: ``prev_record_hash`` the first record must carry.++ Returns:+ ``(result, last_valid_seq, last_valid_record_hash)``. When the+ source is empty, these are ``start_seq - 1`` and ``start_prev_hash``.+ """+ expected_prev = start_prev_hash+ expected_seq = start_seq+ count = 0++ def _break(index: int, seq: int | None, reason: str, detail: str) -> ChainVerificationResult:+ return ChainVerificationResult(+ ok=False, record_count=count, first_break=ChainBreak(index, seq, reason, detail)+ )++ for index, record, parse_error in record_source:+ if parse_error is not None:+ return _break(index, None, "malformed_json", parse_error), expected_seq - 1, expected_prev++ assert record is not None # parse_error is None iff record is not None+ missing = sorted(_CHAIN_FIELDS - record.keys())+ if missing:+ return (+ _break(index, record.get("seq"), "missing_chain_fields", f"missing {missing}"),+ expected_seq - 1,+ expected_prev,+ )++ seq = record["seq"]+ prev_hash = record["prev_record_hash"]+ record_hash = record["record_hash"]++ if seq != expected_seq:+ detail = f"expected seq={expected_seq}, found {seq!r}"+ return _break(index, seq, "seq_gap", detail), expected_seq - 1, expected_prev++ if prev_hash != expected_prev:+ detail = f"expected prev_record_hash={expected_prev}, found {prev_hash!r}"+ return _break(index, seq, "prev_hash_mismatch", detail), expected_seq - 1, expected_prev++ payload = {k: v for k, v in record.items() if k not in _CHAIN_FIELDS}+ recomputed = compute_record_hash(seq, prev_hash, payload)+ if recomputed != record_hash:+ detail = f"stored record_hash={record_hash!r}, recomputed={recomputed!r}"+ return _break(index, seq, "record_hash_mismatch", detail), expected_seq - 1, expected_prev++ expected_prev = record_hash+ expected_seq += 1+ count += 1++ return ChainVerificationResult(ok=True, record_count=count, first_break=None), expected_seq - 1, expected_prev+++def verify_chain(path: Path) -> ChainVerificationResult:+ """Walk an on-disk ledger end to end, returning where (if anywhere) it broke.++ Args:+ path: Ledger JSONL file path. A missing file verifies as an empty,+ intact (``ok=True``, ``record_count=0``) chain.++ Returns:+ A :class:`ChainVerificationResult` pinpointing the first break, if any.+ """+ if not path.exists():+ result, _, _ = _walk_chain(iter(()))+ return result+ with path.open("r", encoding="utf-8") as handle:+ result, _, _ = _walk_chain(_iter_parsed_lines(handle))+ return result+++def _lock_exclusive(handle: BinaryIO) -> None:+ """Acquire a blocking, cross-process exclusive advisory lock on ``handle``."""+ if fcntl is not None:+ fcntl.flock(handle.fileno(), fcntl.LOCK_EX)+ return+ if msvcrt is not None: # pragma: no cover - exercised on Windows CI+ handle.seek(0, os.SEEK_END)+ if handle.tell() == 0:+ handle.write(b"\0")+ handle.flush()+ handle.seek(0)+ msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)+ return+ # No supported lock backend: proceed unlocked (single-writer assumption).+ # verify_chain still catches a corrupted/forked chain either way.+++def _unlock(handle: BinaryIO) -> None:+ """Release the lock acquired by :func:`_lock_exclusive`."""+ if fcntl is not None:+ fcntl.flock(handle.fileno(), fcntl.LOCK_UN)+ return+ if msvcrt is not None: # pragma: no cover - exercised on Windows CI+ handle.seek(0)+ msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)+++def _fsync_dir(directory: Path) -> None:+ """Fsync a directory so a new file's directory entry survives a crash."""+ try:+ dir_fd = os.open(directory, os.O_RDONLY)+ except OSError:+ return+ try:+ os.fsync(dir_fd)+ except OSError as exc:+ _warn_fsync_failure(exc, directory)+ finally:+ os.close(dir_fd)+++def append_record(+ path: Path,+ payload: Mapping[str, Any],+ *,+ fsync: bool = True,+ dir_mode: int = 0o700,+) -> dict[str, Any]:+ """Append one hash-chained record to a JSONL ledger, durably.++ Reads and verifies the ledger's ENTIRE existing chain under an exclusive+ advisory lock (see module docstring for the O(n)-per-append rationale),+ computes this record's ``seq``/``prev_record_hash``/``record_hash``,+ appends it as one JSON line, flushes, and (by default) fsyncs before+ releasing the lock.++ Args:+ path: Ledger JSONL file path. Parent directory is created (mode+ ``dir_mode``) on first write; the directory entry is itself+ fsynced the first time the file is created, unless ``fsync`` is+ ``False``.+ payload: This record's body. Must NOT contain the reserved keys+ ``seq`` / ``prev_record_hash`` / ``record_hash`` — those are+ chain metadata computed here, not caller-supplied.+ fsync: Fsync the ledger file after this write, AND fsync the parent+ directory the first time the file is created (default ``True``,+ matching ``TraceWriter``'s per-record durability guarantee — see+ module docstring for why the compliance ledger did not have this+ before). ``False`` issues no fsync syscalls at all.+ dir_mode: Permission bits for the parent directory when created.++ Returns:+ The full record as written: ``payload`` merged with ``seq``,+ ``prev_record_hash``, ``record_hash``.++ Raises:+ ValueError: ``payload`` sets a reserved chain-field key.+ LedgerCorruptionError: The ledger's existing chain is already broken+ (a prior record was edited or deleted) — the append is refused+ rather than silently extended on top of unknown history.+ """+ reserved_used = _CHAIN_FIELDS & payload.keys()+ if reserved_used:+ raise ValueError(f"payload must not set reserved chain fields: {sorted(reserved_used)}")++ path.parent.mkdir(parents=True, exist_ok=True, mode=dir_mode)+ created = not path.exists()++ handle = open(path, "a+b")+ try:+ _lock_exclusive(handle)+ try:+ handle.seek(0)+ existing_text = handle.read().decode("utf-8")+ # Sealed segments come first: after rotate_if_needed the active+ # file starts partway through the chain, and walking it as if it+ # began at genesis would report every rotated ledger as corrupt.+ # Continuing from the newest segment is also what makes deleting a+ # whole segment leave a detectable seam.+ start_seq, start_prev = 1, GENESIS_PREV_HASH+ segments = archive_segments(path)+ if segments:+ tail = _read_raw_records(segments[-1])+ if tail:+ start_seq = int(tail[-1]["seq"]) + 1+ start_prev = str(tail[-1]["record_hash"])++ verification, last_seq, last_hash = _walk_chain(+ _iter_parsed_lines(existing_text.splitlines()),+ start_seq=start_seq,+ start_prev_hash=start_prev,+ )+ if not verification.ok:+ assert verification.first_break is not None+ raise LedgerCorruptionError(verification.first_break)++ seq = last_seq + 1+ record_hash = compute_record_hash(seq, last_hash, payload)+ full_record: dict[str, Any] = {+ **payload,+ "seq": seq,+ "prev_record_hash": last_hash,+ "record_hash": record_hash,+ }+ line = (json.dumps(full_record, ensure_ascii=False) + "\n").encode("utf-8")++ handle.seek(0, os.SEEK_END)+ handle.write(line)+ handle.flush()+ if fsync:+ try:+ os.fsync(handle.fileno())+ except OSError as exc:+ _warn_fsync_failure(exc, path)+ finally:+ _unlock(handle)+ finally:+ handle.close()++ if created and fsync:+ _fsync_dir(path.parent)++ return full_record+++def _read_raw_records(path: Path) -> list[dict[str, Any]]:+ """Read every parseable JSON line from ``path`` in order.++ Used by :func:`build_export` after :func:`verify_chain` has already+ established (or reported) chain integrity — this is a plain re-read, not+ itself a second verification pass.+ """+ if not path.exists():+ return []+ records: list[dict[str, Any]] = []+ for line in path.read_text(encoding="utf-8").splitlines():+ stripped = line.strip()+ if not stripped:+ continue+ try:+ records.append(json.loads(stripped))+ except json.JSONDecodeError:+ # A malformed line is already surfaced by verify_chain's+ # "malformed_json" break; stop collecting records past it so the+ # export does not silently paper over the corruption.+ break+ return records+++def build_export(path: Path) -> dict[str, Any]:+ """Build a self-contained, offline-verifiable export of a chained ledger.++ The export embeds every parsed record plus the verification outcome+ computed while building it, and a hash over the envelope itself+ (``export_hash``) so a COPY of this dict — with no access to the+ original ledger file or path — can be independently re-verified end to+ end via :func:`verify_export`.++ Args:+ path: Ledger JSONL file path.++ Returns:+ A JSON-serializable export dict.+ """+ verification = verify_chain(path)+ records = _read_raw_records(path)+ envelope = {"format": EXPORT_FORMAT, "source_path": str(path), "records": records}+ export_hash = f"sha256:{_sha256_hex(_canonical_json(envelope))}"+ return {+ "format": EXPORT_FORMAT,+ "source_path": str(path),+ "record_count": len(records),+ "records": records,+ "verification": verification.to_dict(),+ "export_hash": export_hash,+ }+++def export_chain_to_file(path: Path, dest: Path) -> Path:+ """Write :func:`build_export`'s output to ``dest`` as pretty JSON.++ Args:+ path: Source ledger JSONL file path.+ dest: Destination file path for the export. Parent directory is+ created if needed.++ Returns:+ ``dest``, for chaining.+ """+ export = build_export(path)+ dest.parent.mkdir(parents=True, exist_ok=True)+ dest.write_text(+ json.dumps(export, sort_keys=True, ensure_ascii=False, indent=2), encoding="utf-8"+ )+ return dest+++def verify_export(export: Mapping[str, Any] | str | Path) -> ChainVerificationResult:+ """Re-verify a chain purely from an export — no source ledger file needed.++ First checks the export envelope itself (``export_hash``, recomputed the+ same way :func:`build_export` computed it) so a tampered EXPORT is+ caught even if the embedded records happen to still chain cleanly among+ themselves; only then walks the embedded records with the same+ verification routine :func:`verify_chain` uses.++ Args:+ export: A dict from :func:`build_export`, or a JSON string / file+ path to one.++ Returns:+ A :class:`ChainVerificationResult`. An envelope-level tamper reports+ ``first_break.reason == "export_hash_mismatch"`` at ``index=-1``.+ """+ if isinstance(export, Path):+ data: Mapping[str, Any] = json.loads(export.read_text(encoding="utf-8"))+ elif isinstance(export, str):+ data = json.loads(export)+ else:+ data = export++ records = list(data["records"])+ envelope = {+ "format": data.get("format", EXPORT_FORMAT),+ "source_path": data.get("source_path", ""),+ "records": records,+ }+ expected_export_hash = f"sha256:{_sha256_hex(_canonical_json(envelope))}"+ if expected_export_hash != data.get("export_hash"):+ detail = f"expected export_hash={expected_export_hash!r}, found {data.get('export_hash')!r}"+ return ChainVerificationResult(+ ok=False,+ record_count=0,+ first_break=ChainBreak(index=-1, seq=None, reason="export_hash_mismatch", detail=detail),+ )++ source = ((index, record, None) for index, record in enumerate(records))+ result, _, _ = _walk_chain(source)+ return result+++# ---------------------------------------------------------------------------+# Retention+# ---------------------------------------------------------------------------++#: Size at which :func:`rotate_if_needed` seals the active ledger. 64 MiB keeps+#: the O(n) verify-before-append (see the module docstring) bounded without+#: producing a directory full of tiny segments.+DEFAULT_ROTATE_BYTES: int = 64 * 1024 * 1024++#: Suffix given to a sealed segment: ``audit_chain.0001.jsonl``.+ARCHIVE_SUFFIX_WIDTH: int = 4+++def archive_segments(path: Path) -> list[Path]:+ """Sealed segments for a ledger, oldest first.++ Args:+ path: Active ledger path, e.g. ``.../audit_chain.jsonl``.++ Returns:+ Sorted archive paths. Sorting is lexicographic over a zero-padded+ counter, which is why the counter is padded.+ """+ return sorted(path.parent.glob(f"{path.stem}.[0-9]" + "[0-9]" * (ARCHIVE_SUFFIX_WIDTH - 1) + path.suffix))+++def rotate_if_needed(+ path: Path,+ max_bytes: int = DEFAULT_ROTATE_BYTES,+ *,+ fsync: bool = True,+) -> Path | None:+ """Seal the active ledger into an archive segment when it grows too large.++ **Nothing is ever deleted.** This project is not a regulated entity and has+ no statutory retention period to satisfy, and for an audit log the safe+ default in the absence of a policy is to keep everything: deleting an audit+ record is itself an auditable event, and a retention window invented by a+ library would silently destroy evidence nobody chose to destroy. Rotation+ here bounds the *active file*, not the history.++ The chain survives rotation. The sealed segment keeps its records unchanged,+ and the next record appended to the fresh active file continues from the+ sealed segment's final ``record_hash`` -- so a deletion of an entire segment+ is as detectable as an edit within one. Use+ :func:`verify_chain_with_archives` to check the whole history.++ Args:+ path: Active ledger path.+ max_bytes: Size at or above which the active file is sealed.+ fsync: Whether to fsync the directory after the rename.++ Returns:+ The archive path when a rotation happened, else None.++ Raises:+ ValueError: If ``max_bytes`` is not positive.+ LedgerCorruptionError: If the active chain is broken -- a corrupt+ ledger is sealed by nobody; fix or quarantine it deliberately.+ """+ if max_bytes <= 0:+ raise ValueError(f"max_bytes must be positive, got {max_bytes}")+ if not path.exists() or path.stat().st_size < max_bytes:+ return None++ result = verify_chain(path)+ if not result.ok:+ raise LedgerCorruptionError(result.first_break)++ counter = len(archive_segments(path)) + 1+ archive = path.with_name(f"{path.stem}.{counter:0{ARCHIVE_SUFFIX_WIDTH}d}{path.suffix}")+ path.rename(archive)+ if fsync:+ _fsync_dir(path.parent)+ return archive+++def verify_chain_with_archives(path: Path) -> ChainVerificationResult:+ """Verify a ledger's whole history, sealed segments included.++ Walks the archives oldest-first and then the active file, checking that each+ segment's first record continues from the previous segment's last+ ``record_hash``. A segment deleted wholesale therefore shows up as a break+ at the seam, which is exactly what plain per-file verification would miss.++ Args:+ path: Active ledger path.++ Returns:+ A :class:`ChainVerificationResult` over the concatenated history. The+ ``index`` of a break is its position in that concatenation, not in any+ one file.+ """+ records: list[dict[str, Any]] = []+ for segment in [*archive_segments(path), path]:+ if not segment.exists():+ continue+ for line in segment.read_text(encoding="utf-8").splitlines():+ if line.strip():+ records.append(json.loads(line))++ if not records:+ return ChainVerificationResult(ok=True, record_count=0, first_break=None)++ prev_hash = GENESIS_PREV_HASH+ for index, record in enumerate(records):+ expected_seq = index + 1+ if record.get("seq") != expected_seq:+ return ChainVerificationResult(+ ok=False,+ record_count=len(records),+ first_break=ChainBreak(+ index=index,+ seq=record.get("seq"),+ reason="seq_gap",+ detail=f"expected seq={expected_seq}, found {record.get('seq')!r}",+ ),+ )+ if record.get("prev_record_hash") != prev_hash:+ return ChainVerificationResult(+ ok=False,+ record_count=len(records),+ first_break=ChainBreak(+ index=index,+ seq=record.get("seq"),+ reason="prev_hash_mismatch",+ detail=(+ f"expected prev_record_hash={prev_hash!r}, "+ f"found {record.get('prev_record_hash')!r}"+ ),+ ),+ )+ payload = {+ k: v for k, v in record.items()+ if k not in ("seq", "prev_record_hash", "record_hash")+ }+ recomputed = compute_record_hash(record["seq"], record["prev_record_hash"], payload)+ if recomputed != record.get("record_hash"):+ return ChainVerificationResult(+ ok=False,+ record_count=len(records),+ first_break=ChainBreak(+ index=index,+ seq=record.get("seq"),+ reason="record_hash_mismatch",+ detail=f"stored {record.get('record_hash')!r}, recomputed {recomputed!r}",+ ),+ )+ prev_hash = record["record_hash"]++ return ChainVerificationResult(ok=True, record_count=len(records), first_break=None)diff --git a/agent/src/governance/manifest.py b/agent/src/governance/manifest.pynew file mode 100644index 000000000..151384350--- /dev/null+++ b/agent/src/governance/manifest.py@@ -0,0 +1,566 @@+"""Run manifest: a content-addressed fingerprint of "what produced this run".++A :class:`RunManifest` answers "under what methodology was that number+produced" without carrying the methodology's raw, possibly sensitive+content: the system prompt is stored only as a hash, each injected skill is+stored as ``(name, content_hash)`` so a later diff can name exactly which+skill's body changed, the tool registry is stored as its sorted name list+plus a hash, and a curated set of package versions pins the numeric/runtime+environment. Composition in, one deterministic hash out.++**Hash scope is the composition, not the instance.** ``timestamp`` and+``run_id`` are recorded on the manifest for provenance but are deliberately+EXCLUDED from ``manifest_hash``. Two runs on different days under the exact+same system prompt / skills / tools / package versions must hash identically+— that repeatability is the entire point (it lets you ask "did methodology+change between run A and run B", not just "did time pass between them"). If+timestamp were hashed, the manifest hash would never repeat and+:func:`diff_manifests` would report a spurious change on every single call.++**No hidden clock.** Per the governance task's hard requirement, this module+never calls ``datetime.now()`` / ``time.time()``. The caller (whoever builds+the manifest at the moment a run starts) supplies ``timestamp`` explicitly.++**This module is intentionally standalone.** It does not import+``src.agent.*`` (protected tree) or reach into a live tool registry / skills+loader itself — it accepts already-extracted composition data (raw system+prompt text to hash, a name->content mapping for skills, an iterable of tool+names, a package-version mapping) so it can be unit tested and reused+without any run-time wiring. Wiring this into the actual agent loop is+explicitly OUT OF SCOPE for this module (the loop lives under the protected+``src/agent/`` tree) — see "Mount points" below for where a future change+would plug in.++Mount points for a future integration (NOT implemented here)::++ 1. System prompt: wherever ``src/agent/context.py`` (or+ ``src/agent/loop.py``) finalizes the system prompt string for a run,+ pass that raw string as ``system_prompt=`` to+ :func:`build_run_manifest`. Only the hash is ever persisted.++ 2. Skills actually injected: the same context-building step (and/or+ ``src/tools/load_skill_tool.py`` for skills pulled in mid-run via the+ ``load_skill`` tool) knows which :class:`src.agent.skills.Skill`+ objects were injected this turn. Pass+ ``{skill.name: skill.body for skill in injected}`` as ``skills=``.++ 3. Tool registry composition: ``src.tools.build_registry(...)`` (this+ one lives under the OPEN ``src/tools/`` tree, not protected) already+ exposes ``ToolRegistry.tool_names`` — see+ ``agent/src/agent/tools.py:87`` and the project CLAUDE.md line+ "measured off ``build_registry().tool_names`` on a default checkout".+ Pass that list as ``tool_names=``.++ 4. Package versions: call :func:`collect_key_package_versions` once per+ process/run start and pass the result as ``package_versions=``.++ 5. Timestamp: the run/session start time the loop already tracks (e.g.+ a ``started_at`` captured when the run begins) should be passed as+ ``timestamp=``; this module must never generate it itself.++ 6. Persistence: analogous to how ``src.agent.trace.TraceWriter`` writes+ ``trace.jsonl`` durably next to a run, a future change could persist+ ``RunManifest.to_json()`` as ``manifest.json`` in the same run/session+ directory (fsync'd the same way trace records are). Not implemented+ here — that directory-resolution logic lives in the protected+ ``src/agent/`` tree.+"""++from __future__ import annotations++import hashlib+import json+import platform+from dataclasses import dataclass, field+from typing import Any, Iterable, Mapping, Sequence++__all__ = [+ "SkillRecord",+ "ToolRegistrySnapshot",+ "RunManifest",+ "ManifestDiff",+ "build_run_manifest",+ "diff_manifests",+ "collect_key_package_versions",+]++#: Curated distributions whose version can shift a computed number or change+#: available functionality. Rationale per package:+#: - "vibe-trading-ai": pins the code release itself.+#: - "numpy" / "pandas" / "scipy": the numeric kernel every metric,+#: optimizer, and quantlib formula (agent/src/quantlib/) runs on top of —+#: a minor version bump in any of them can silently shift a computed+#: number (e.g. a different BLAS path, a changed default ddof).+#: - "langchain" / "langchain-core": fix the tool-calling / message+#: contract the ReAct loop (agent/src/agent/loop.py) depends on.+#: - "statsmodels" / "arch": back the optional econometrics surface+#: (stationarity/cointegration/GARCH in agent/src/quantlib/) gated+#: behind the "stats" extra; recorded as ``None`` when not installed,+#: which is itself methodology-relevant (those functions were simply+#: unavailable for this run).+_KEY_PACKAGES: tuple[str, ...] = (+ "vibe-trading-ai",+ "langchain",+ "langchain-core",+ "numpy",+ "pandas",+ "scipy",+ "statsmodels",+ "arch",+)+++def _canonical_json(obj: Any) -> str:+ """Serialize ``obj`` deterministically for hashing (sorted keys, compact)."""+ return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)+++def _sha256_hex(text: str) -> str:+ """Return the hex SHA-256 digest of ``text``."""+ return hashlib.sha256(text.encode("utf-8")).hexdigest()+++def _hash_prefixed(text: str) -> str:+ """Return a self-describing ``sha256:<hex>`` digest of ``text``."""+ return f"sha256:{_sha256_hex(text)}"+++@dataclass(frozen=True)+class SkillRecord:+ """One injected skill's identity + content fingerprint.++ Only the hash is stored, never the body — a skill can carry arbitrary+ (possibly long, possibly sensitive-in-context) text, and the manifest is+ meant to be small and safe to persist/share.++ Attributes:+ name: Skill name (``Skill.name`` in ``src.agent.skills``).+ content_hash: ``sha256:<hex>`` of the exact body text that was+ injected for this run.+ """++ name: str+ content_hash: str++ @classmethod+ def from_content(cls, name: str, content: str) -> "SkillRecord":+ """Build a record by hashing ``content`` now.++ Args:+ name: Skill name.+ content: Full skill body text as actually injected.++ Returns:+ A new :class:`SkillRecord`.+ """+ return cls(name=name, content_hash=_hash_prefixed(content))+++@dataclass(frozen=True)+class ToolRegistrySnapshot:+ """The tool registry's composition for a run: sorted names + one hash.++ Attributes:+ tool_names: Deduplicated tool names, sorted for determinism.+ tools_hash: ``sha256:<hex>`` over the canonical JSON of+ ``tool_names`` — changes if any tool is added, removed, or+ renamed.+ """++ tool_names: tuple[str, ...]+ tools_hash: str++ @classmethod+ def from_names(cls, tool_names: Iterable[str]) -> "ToolRegistrySnapshot":+ """Build a snapshot from an (unordered, possibly duplicated) iterable.++ Args:+ tool_names: Tool names, e.g. ``ToolRegistry.tool_names``.++ Returns:+ A new :class:`ToolRegistrySnapshot` with names sorted.+ """+ names = tuple(sorted(set(tool_names)))+ digest = _hash_prefixed(_canonical_json(list(names)))+ return cls(tool_names=names, tools_hash=digest)+++def _pairs(mapping: Mapping[str, Any] | None) -> tuple[tuple[str, Any], ...]:+ """Return ``mapping`` as a sorted, hashable tuple of ``(key, value)`` pairs."""+ return tuple(sorted((mapping or {}).items()))+++def _compute_manifest_hash(+ *,+ system_prompt_hash: str,+ skills: tuple[SkillRecord, ...],+ tools: ToolRegistrySnapshot,+ package_versions: tuple[tuple[str, Any], ...],+ extra: tuple[tuple[str, Any], ...],+) -> str:+ """Hash the run composition (NOT ``run_id``/``timestamp`` — see module docstring).++ ``tools.tools_hash`` alone (rather than re-embedding the full name list)+ is sufficient input here: it is itself a deterministic hash of the+ sorted tool-name list, so any tool addition/removal/rename already+ changes ``tools_hash`` and therefore this hash too.+ """+ payload = {+ "system_prompt_hash": system_prompt_hash,+ "skills": [[record.name, record.content_hash] for record in skills],+ "tools_hash": tools.tools_hash,+ "package_versions": list(package_versions),+ "extra": list(extra),+ }+ return _hash_prefixed(_canonical_json(payload))+++@dataclass(frozen=True)+class RunManifest:+ """Immutable fingerprint of one run's methodology composition.++ Attributes:+ run_id: Caller-supplied run/session identifier. NOT part of+ ``manifest_hash``.+ timestamp: Caller-supplied ISO-8601 (or otherwise caller-defined)+ timestamp string. NOT part of ``manifest_hash`` — see module+ docstring for why.+ system_prompt_hash: ``sha256:<hex>`` of the exact system prompt text.+ skills: Sorted-by-name tuple of :class:`SkillRecord`.+ tools: :class:`ToolRegistrySnapshot` of the tool registry.+ package_versions: Sorted ``(name, version_or_None)`` pairs.+ extra: Sorted ``(key, value)`` pairs for caller-defined composition+ dimensions not covered above (e.g. provider/model name). Small,+ non-sensitive strings only — unlike the system prompt/skills,+ these are stored raw, not hashed, because they are meant to be+ directly readable in a diff.+ manifest_hash: ``sha256:<hex>`` over everything above except+ ``run_id``/``timestamp``. Two manifests with identical+ composition always produce the identical ``manifest_hash``.+ """++ run_id: str+ timestamp: str+ system_prompt_hash: str+ skills: tuple[SkillRecord, ...]+ tools: ToolRegistrySnapshot+ package_versions: tuple[tuple[str, Any], ...]+ extra: tuple[tuple[str, Any], ...]+ manifest_hash: str++ def verify_hash(self) -> bool:+ """Recompute ``manifest_hash`` from the other fields and compare.++ Useful after deserializing a persisted manifest (``from_dict`` /+ ``from_json`` trust the stored hash at load time; this method is the+ integrity check that actually re-derives it).++ Returns:+ ``True`` when the stored ``manifest_hash`` matches a fresh+ recomputation, ``False`` if the manifest was hand-edited/corrupted.+ """+ expected = _compute_manifest_hash(+ system_prompt_hash=self.system_prompt_hash,+ skills=self.skills,+ tools=self.tools,+ package_versions=self.package_versions,+ extra=self.extra,+ )+ return expected == self.manifest_hash++ def to_dict(self) -> dict[str, Any]:+ """Return a JSON-serializable representation.++ Returns:+ A plain dict; round-trips through :meth:`from_dict`.+ """+ return {+ "run_id": self.run_id,+ "timestamp": self.timestamp,+ "system_prompt_hash": self.system_prompt_hash,+ "skills": [+ {"name": record.name, "content_hash": record.content_hash}+ for record in self.skills+ ],+ "tools": {+ "tool_names": list(self.tools.tool_names),+ "tools_hash": self.tools.tools_hash,+ },+ "package_versions": dict(self.package_versions),+ "extra": dict(self.extra),+ "manifest_hash": self.manifest_hash,+ }++ @classmethod+ def from_dict(cls, data: Mapping[str, Any]) -> "RunManifest":+ """Reconstruct a manifest from :meth:`to_dict` output.++ The stored ``manifest_hash`` is trusted as-is (not recomputed) —+ call :meth:`verify_hash` afterward to check it was not tampered with.++ Args:+ data: A mapping produced by :meth:`to_dict` (or an equivalent+ deserialized JSON object).++ Returns:+ A new :class:`RunManifest`.+ """+ skills = tuple(+ sorted(+ (+ SkillRecord(name=item["name"], content_hash=item["content_hash"])+ for item in data["skills"]+ ),+ key=lambda record: record.name,+ )+ )+ tools = ToolRegistrySnapshot(+ tool_names=tuple(data["tools"]["tool_names"]),+ tools_hash=data["tools"]["tools_hash"],+ )+ return cls(+ run_id=data["run_id"],+ timestamp=data["timestamp"],+ system_prompt_hash=data["system_prompt_hash"],+ skills=skills,+ tools=tools,+ package_versions=_pairs(data.get("package_versions")),+ extra=_pairs(data.get("extra")),+ manifest_hash=data["manifest_hash"],+ )++ def to_json(self, *, indent: int | None = None) -> str:+ """Serialize to a JSON string.++ Args:+ indent: Optional pretty-print indent; compact when ``None``.++ Returns:+ JSON text; round-trips through :meth:`from_json`.+ """+ return json.dumps(self.to_dict(), sort_keys=True, ensure_ascii=False, indent=indent)++ @classmethod+ def from_json(cls, text: str) -> "RunManifest":+ """Deserialize from :meth:`to_json` output.++ Args:+ text: JSON text.++ Returns:+ A new :class:`RunManifest`.+ """+ return cls.from_dict(json.loads(text))+++def build_run_manifest(+ *,+ run_id: str,+ timestamp: str,+ system_prompt: str,+ skills: Mapping[str, str] | Sequence[SkillRecord] = (),+ tool_names: Iterable[str] = (),+ package_versions: Mapping[str, Any] | None = None,+ extra: Mapping[str, Any] | None = None,+) -> RunManifest:+ """Build a :class:`RunManifest` from raw run composition data.++ Args:+ run_id: Run/session identifier (provenance only, not hashed).+ timestamp: Caller-supplied timestamp string (provenance only, not+ hashed). This function never reads the wall clock itself.+ system_prompt: Full system prompt text; only its hash is kept.+ skills: Either a ``{name: content}`` mapping (the common case — the+ caller already has the injected skills' full bodies) or a+ pre-built sequence of :class:`SkillRecord`.+ tool_names: Tool registry names, e.g. ``ToolRegistry.tool_names``.+ package_versions: ``{package: version_or_None}``; see+ :func:`collect_key_package_versions` for a ready-made curated+ collector.+ extra: Small caller-defined composition dimensions (e.g.+ ``{"provider": "openrouter", "model": "deepseek/deepseek-v3.2"}``).++ Returns:+ A new :class:`RunManifest` with ``manifest_hash`` computed over the+ composition (excluding ``run_id``/``timestamp``).++ Raises:+ ValueError: ``run_id``/``timestamp`` is empty, or ``skills`` contains+ two records with the same name.+ """+ if not run_id or not run_id.strip():+ raise ValueError("run_id must not be empty")+ if not timestamp or not timestamp.strip():+ raise ValueError("timestamp must not be empty")++ if isinstance(skills, Mapping):+ skill_records = tuple(+ sorted(+ (SkillRecord.from_content(name, content) for name, content in skills.items()),+ key=lambda record: record.name,+ )+ )+ else:+ skill_records = tuple(sorted(skills, key=lambda record: record.name))+ names = [record.name for record in skill_records]+ if len(names) != len(set(names)):+ raise ValueError(f"duplicate skill names in manifest input: {names}")++ tools_snapshot = ToolRegistrySnapshot.from_names(tool_names)+ pv_pairs = _pairs(package_versions)+ extra_pairs = _pairs(extra)++ manifest_hash = _compute_manifest_hash(+ system_prompt_hash=_hash_prefixed(system_prompt),+ skills=skill_records,+ tools=tools_snapshot,+ package_versions=pv_pairs,+ extra=extra_pairs,+ )++ return RunManifest(+ run_id=run_id,+ timestamp=timestamp,+ system_prompt_hash=_hash_prefixed(system_prompt),+ skills=skill_records,+ tools=tools_snapshot,+ package_versions=pv_pairs,+ extra=extra_pairs,+ manifest_hash=manifest_hash,+ )+++@dataclass(frozen=True)+class ManifestDiff:+ """What changed between two :class:`RunManifest` instances.++ Attributes:+ system_prompt_changed: Whether ``system_prompt_hash`` differs.+ skills_added: Skill names present in ``b`` but not ``a``.+ skills_removed: Skill names present in ``a`` but not ``b``.+ skills_changed: Skill names present in both whose ``content_hash``+ differs — the direct answer to "which skill's content changed".+ tools_added: Tool names present in ``b`` but not ``a``.+ tools_removed: Tool names present in ``a`` but not ``b``.+ package_version_changes: ``(package, old_version, new_version)``+ triples for every package whose recorded version differs+ (``None`` on either side means added/removed/not-installed).+ extra_changes: Same shape as ``package_version_changes`` for the+ ``extra`` composition dimensions.+ manifest_hash_changed: Whether the overall ``manifest_hash`` differs.+ """++ system_prompt_changed: bool+ skills_added: tuple[str, ...]+ skills_removed: tuple[str, ...]+ skills_changed: tuple[str, ...]+ tools_added: tuple[str, ...]+ tools_removed: tuple[str, ...]+ package_version_changes: tuple[tuple[str, Any, Any], ...]+ extra_changes: tuple[tuple[str, Any, Any], ...]+ manifest_hash_changed: bool++ @property+ def unchanged(self) -> bool:+ """Whether nothing at all differs between the two manifests."""+ return not (+ self.system_prompt_changed+ or self.skills_added+ or self.skills_removed+ or self.skills_changed+ or self.tools_added+ or self.tools_removed+ or self.package_version_changes+ or self.extra_changes+ )+++def diff_manifests(a: RunManifest, b: RunManifest) -> ManifestDiff:+ """Diff two manifests, naming exactly what changed.++ Args:+ a: The earlier (or "baseline") manifest.+ b: The later (or "candidate") manifest.++ Returns:+ A :class:`ManifestDiff` describing every difference.+ """+ a_skills = {record.name: record.content_hash for record in a.skills}+ b_skills = {record.name: record.content_hash for record in b.skills}+ skills_added = tuple(sorted(set(b_skills) - set(a_skills)))+ skills_removed = tuple(sorted(set(a_skills) - set(b_skills)))+ skills_changed = tuple(+ sorted(+ name+ for name in set(a_skills) & set(b_skills)+ if a_skills[name] != b_skills[name]+ )+ )++ a_tools = set(a.tools.tool_names)+ b_tools = set(b.tools.tool_names)+ tools_added = tuple(sorted(b_tools - a_tools))+ tools_removed = tuple(sorted(a_tools - b_tools))++ a_pv = dict(a.package_versions)+ b_pv = dict(b.package_versions)+ pv_changes = tuple(+ (key, a_pv.get(key), b_pv.get(key))+ for key in sorted(set(a_pv) | set(b_pv))+ if a_pv.get(key) != b_pv.get(key)+ )++ a_extra = dict(a.extra)+ b_extra = dict(b.extra)+ extra_changes = tuple(+ (key, a_extra.get(key), b_extra.get(key))+ for key in sorted(set(a_extra) | set(b_extra))+ if a_extra.get(key) != b_extra.get(key)+ )++ return ManifestDiff(+ system_prompt_changed=a.system_prompt_hash != b.system_prompt_hash,+ skills_added=skills_added,+ skills_removed=skills_removed,+ skills_changed=skills_changed,+ tools_added=tools_added,+ tools_removed=tools_removed,+ package_version_changes=pv_changes,+ extra_changes=extra_changes,+ manifest_hash_changed=a.manifest_hash != b.manifest_hash,+ )+++def collect_key_package_versions(+ extra_packages: Iterable[str] = (),+) -> dict[str, str | None]:+ """Look up installed versions for the curated methodology-relevant set.++ See :data:`_KEY_PACKAGES` for the selection and per-package rationale.+ Also records the running interpreter's version under the ``"python"``+ key, since numeric/floating-point behavior is not guaranteed identical+ across CPython versions either.++ This performs filesystem/package-metadata lookups but never reads the+ wall clock, so it is safe to call from a hash-composition path.++ Args:+ extra_packages: Additional distribution names to look up alongside+ the curated list (e.g. a provider SDK selected at runtime, such+ as ``langchain-anthropic`` or ``langchain-deepseek``).++ Returns:+ ``{distribution_name: version}``, with ``None`` when a distribution+ is not installed (itself methodology-relevant: e.g. ``arch`` absent+ means GARCH-backed quantlib functions were unavailable this run).+ """+ from importlib.metadata import PackageNotFoundError, version++ names = tuple(dict.fromkeys((*_KEY_PACKAGES, *extra_packages)))+ result: dict[str, str | None] = {"python": platform.python_version()}+ for name in names:+ try:+ result[name] = version(name)+ except PackageNotFoundError:+ result[name] = None+ return resultdiff --git a/agent/src/quantlib/__init__.py b/agent/src/quantlib/__init__.pyindex fa7e1e305..a025b9313 100644--- a/agent/src/quantlib/__init__.py+++ b/agent/src/quantlib/__init__.py@@ -18,6 +18,11 @@ Submodules:credit Altman Z, Merton/KMV, spread analyticstimeseries Stationarity, cointegration, GARCH, bootstraprisk VaR/CVaR, drawdown, Monte Carlo, EVT tail fitting+ var_backtest Kupiec/Christoffersen coverage tests and the Basel traffic light+ multipletesting Deflated Sharpe, CSCV/PBO and BH-FDR search corrections+ crossvalidation Purged + embargoed splits for overlapping financial labels+ eventstudy Abnormal returns around dated events (CAR/CAAR, Patell, BMP)+ factormodel Cross-sectional style exposures, factor returns, style driftattribution Brinson-Fachler allocation/selection/interactionimpact Market-impact and slippage modelsfundmath Private-markets fund maths on the irregular cash-flow spinediff --git a/agent/src/quantlib/crossvalidation.py b/agent/src/quantlib/crossvalidation.pynew file mode 100644index 000000000..9394db071--- /dev/null+++ b/agent/src/quantlib/crossvalidation.py@@ -0,0 +1,473 @@+"""Purged and embargoed cross-validation for overlapping financial labels.++Plain K-fold assumes observations are independent. Financial labels are not: a+label formed at time ``t`` from the next 20 days of returns overlaps the labels+of the following 19 observations. Split such a sample naively and the training+set contains observations whose outcome window covers the test period. The model+is then evaluated on information it already saw, and the out-of-sample score is+not out of sample.++Two corrections, both from Lopez de Prado's treatment, and they fix different+leaks:++**Purging** removes from the training set any observation whose label interval+overlaps the test interval. This is the leak above, and it is *symmetric*: an+overlap matters whether the training observation starts before or after the test+window opens.++**Embargo** additionally removes training observations that begin shortly after+the test set ends. Purging alone does not catch this, because those labels do+not overlap -- they are merely serially correlated with the test period through+autocorrelated features and slow-moving state. The embargo is a blunt instrument+by design; its size is a judgement about how fast the series forgets.++THE OFF-BY-ONE IS THE WHOLE POINT+---------------------------------+The single most common implementation bug in this area is a boundary that leaks+exactly one bar: taking the test block as ``[start, end]`` and the training+block as everything outside ``[start, end)``, so the bar at ``end`` sits in both.+:func:`detect_boundary_leakage` exists to make that class of error assertable+rather than reviewable, and every splitter here is checked with it.++INTERVALS ARE CLOSED ON BOTH ENDS+---------------------------------+A label spanning ``[t0, t1]`` includes both endpoints. Two labels touching at a+single instant therefore *do* overlap. This is the conservative reading and it+is stated here because the alternative silently keeps one bar of contamination+at every boundary.+"""++from __future__ import annotations++from collections.abc import Iterator, Sequence+from dataclasses import dataclass++import numpy as np+import pandas as pd++__all__ = [+ "DEFAULT_EMBARGO_FRACTION",+ "MIN_FOLDS",+ "LeakageReport",+ "Split",+ "combinatorial_purged_splits",+ "detect_boundary_leakage",+ "purged_kfold_splits",+ "purged_walk_forward_splits",+]++#: Fraction of the total sample embargoed after each test block. 0.01 is the+#: published default; it is a judgement about serial correlation, not a constant+#: of nature, and a strongly autocorrelated feature set deserves more.+DEFAULT_EMBARGO_FRACTION: float = 0.01++#: Fewest folds that leave anything to train on.+MIN_FOLDS: int = 2+++@dataclass(frozen=True)+class Split:+ """One train/test partition of the sample.++ Attributes:+ train: Positional indices of the training observations, ascending.+ test: Positional indices of the test observations, ascending.+ purged: How many observations were removed from training for overlapping+ the test interval.+ embargoed: How many were removed for falling inside the embargo window.+ test_bounds: ``(first, last)`` positional index of the test block. For a+ combinatorial split with several blocks this is the outer hull.+ """++ train: np.ndarray+ test: np.ndarray+ purged: int+ embargoed: int+ test_bounds: tuple[int, int]+++@dataclass(frozen=True)+class LeakageReport:+ """Result of auditing a split for contamination.++ Attributes:+ overlapping: Positional indices of training observations whose label+ interval overlaps the test interval. Non-empty means purging failed.+ shared: Indices present in both the training and the test set. Non-empty+ means an off-by-one at the boundary.+ embargo_violations: Training indices that start inside the embargo+ window after the test block.+ clean: True when all three are empty.+ """++ overlapping: np.ndarray+ shared: np.ndarray+ embargo_violations: np.ndarray+ clean: bool+++def _as_label_spans(+ label_end_times: pd.Series | Sequence[int] | np.ndarray,+ n_samples: int | None = None,+) -> np.ndarray:+ """Normalise label end times into positional spans.++ Args:+ label_end_times: Either a pandas Series whose index is the label start+ time and whose values are the label end time, or a positional array+ where element ``i`` is the last positional index observation ``i``'s+ label depends on.+ n_samples: Expected number of samples, checked when supplied.++ Returns:+ Integer array ``ends`` where ``ends[i]`` is the last positional index+ that observation ``i``'s label covers. Always at least ``i``.++ Raises:+ ValueError: If the input is empty, not 1-D, holds a non-finite value, or+ declares a label ending before it starts.+ """+ if isinstance(label_end_times, pd.Series):+ if label_end_times.empty:+ raise ValueError("label_end_times is empty")+ starts = label_end_times.index+ ends = label_end_times.to_numpy()+ # searchsorted on the start index converts label end *times* into label+ # end *positions*; 'left' then clipping keeps a label that ends between+ # two observations attached to the earlier one.+ positions = np.searchsorted(starts, ends, side="left")+ positions = np.clip(positions, np.arange(len(starts)), len(starts) - 1)+ span_ends = positions.astype(int)+ else:+ span_ends = np.asarray(label_end_times, dtype=float)+ if span_ends.ndim != 1:+ raise ValueError(f"label_end_times must be 1-D, got shape {span_ends.shape}")+ if span_ends.size == 0:+ raise ValueError("label_end_times is empty")+ if not np.isfinite(span_ends).all():+ raise ValueError("label_end_times holds a non-finite value")+ span_ends = span_ends.astype(int)+ if (span_ends < np.arange(span_ends.size)).any():+ raise ValueError(+ "a label cannot end before the observation it belongs to starts"+ )++ if n_samples is not None and span_ends.size != n_samples:+ raise ValueError(+ f"label_end_times has {span_ends.size} entries but the sample has {n_samples}"+ )+ return span_ends+++def _apply_purge_and_embargo(+ label_ends: np.ndarray,+ test_mask: np.ndarray,+ embargo_size: int,+) -> tuple[np.ndarray, int, int]:+ """Build a training mask that is purged of overlap and embargoed after.++ Args:+ label_ends: Last positional index each observation's label covers.+ test_mask: Boolean mask of the test observations.+ embargo_size: Observations embargoed immediately after each test block.++ Returns:+ Tuple of ``(train_indices, purged_count, embargoed_count)``.+ """+ n = label_ends.size+ starts = np.arange(n)+ test_positions = np.flatnonzero(test_mask)+ first_test, last_test = int(test_positions[0]), int(test_positions[-1])++ # The test set's own footprint runs from its first observation to the last+ # index any of its labels reaches -- not merely to its last row.+ test_span_end = int(max(last_test, label_ends[test_positions].max()))++ candidate = ~test_mask+ # Closed intervals on both ends: [start_i, end_i] and [first_test, test_span_end]+ # overlap when start_i <= test_span_end and end_i >= first_test.+ overlaps = (starts <= test_span_end) & (label_ends >= first_test)+ purged_mask = candidate & overlaps+ candidate_after_purge = candidate & ~overlaps++ if embargo_size > 0:+ embargo_end = min(test_span_end + embargo_size, n - 1)+ in_embargo = (starts > test_span_end) & (starts <= embargo_end)+ else:+ in_embargo = np.zeros(n, dtype=bool)++ embargo_mask = candidate_after_purge & in_embargo+ train_mask = candidate_after_purge & ~in_embargo++ return (+ np.flatnonzero(train_mask),+ int(purged_mask.sum()),+ int(embargo_mask.sum()),+ )+++def purged_kfold_splits(+ n_samples: int,+ label_end_times: pd.Series | Sequence[int] | np.ndarray | None = None,+ n_folds: int = 5,+ embargo_fraction: float = DEFAULT_EMBARGO_FRACTION,+) -> Iterator[Split]:+ """K contiguous test blocks, each with training purged and embargoed.++ Folds are contiguous in time rather than shuffled: shuffling destroys the+ very ordering purging exists to respect.++ Args:+ n_samples: Number of observations.+ label_end_times: Where each label's outcome window ends. When None, each+ label is assumed to resolve within its own bar, so purging removes+ only the boundary and the embargo does the remaining work.+ n_folds: Number of folds, at least :data:`MIN_FOLDS`.+ embargo_fraction: Fraction of the sample embargoed after each test block.++ Yields:+ One :class:`Split` per fold, in chronological order of the test block.++ Raises:+ ValueError: If ``n_folds`` is below :data:`MIN_FOLDS`, exceeds the+ sample size, if ``embargo_fraction`` is negative or at least 1, or+ if ``label_end_times`` does not match the sample.+ """+ if n_folds < MIN_FOLDS:+ raise ValueError(f"n_folds must be at least {MIN_FOLDS}, got {n_folds}")+ if n_samples < n_folds:+ raise ValueError(f"{n_samples} samples cannot make {n_folds} folds")+ if not 0.0 <= embargo_fraction < 1.0:+ raise ValueError(+ f"embargo_fraction must be in [0, 1), got {embargo_fraction}"+ )++ if label_end_times is None:+ label_ends = np.arange(n_samples)+ else:+ label_ends = _as_label_spans(label_end_times, n_samples)++ embargo_size = int(round(n_samples * embargo_fraction))+ boundaries = np.linspace(0, n_samples, n_folds + 1).astype(int)++ for fold in range(n_folds):+ start, stop = int(boundaries[fold]), int(boundaries[fold + 1])+ if stop <= start:+ continue+ test_mask = np.zeros(n_samples, dtype=bool)+ test_mask[start:stop] = True++ train, purged, embargoed = _apply_purge_and_embargo(+ label_ends, test_mask, embargo_size+ )+ yield Split(+ train=train,+ test=np.arange(start, stop),+ purged=purged,+ embargoed=embargoed,+ test_bounds=(start, stop - 1),+ )+++def purged_walk_forward_splits(+ n_samples: int,+ label_end_times: pd.Series | Sequence[int] | np.ndarray | None = None,+ n_folds: int = 5,+ embargo_fraction: float = DEFAULT_EMBARGO_FRACTION,+ expanding: bool = True,+) -> Iterator[Split]:+ """Walk-forward splits that only ever train on the past.++ Purged K-fold trains on data from *after* the test block as well, which is+ correct for estimating generalisation but wrong for simulating a strategy+ that had to be run in real time. This variant keeps training strictly before+ the test block, and still purges the boundary, because the last training+ label can easily reach into the test window.++ Args:+ n_samples: Number of observations.+ label_end_times: Where each label's outcome window ends.+ n_folds: Number of test blocks; the first block of the sample is used+ only for training.+ embargo_fraction: Retained for signature symmetry with+ :func:`purged_kfold_splits`. An embargo *after* the test block is+ vacuous here because nothing after the test block is ever trained+ on, so this only affects the reported ``embargoed`` count.+ expanding: True for an expanding training window (all history so far),+ False for a rolling window the size of one fold.++ Yields:+ One :class:`Split` per test block, chronologically. A block whose+ training set would be empty is skipped.++ Raises:+ ValueError: Same conditions as :func:`purged_kfold_splits`.+ """+ if n_folds < MIN_FOLDS:+ raise ValueError(f"n_folds must be at least {MIN_FOLDS}, got {n_folds}")+ if n_samples < n_folds:+ raise ValueError(f"{n_samples} samples cannot make {n_folds} folds")+ if not 0.0 <= embargo_fraction < 1.0:+ raise ValueError(f"embargo_fraction must be in [0, 1), got {embargo_fraction}")++ if label_end_times is None:+ label_ends = np.arange(n_samples)+ else:+ label_ends = _as_label_spans(label_end_times, n_samples)++ boundaries = np.linspace(0, n_samples, n_folds + 1).astype(int)++ for fold in range(1, n_folds):+ start, stop = int(boundaries[fold]), int(boundaries[fold + 1])+ if stop <= start:+ continue++ train_start = 0 if expanding else int(boundaries[fold - 1])+ candidate = np.arange(train_start, start)+ if candidate.size == 0:+ continue++ # Purge: a past label whose outcome window reaches into the test block+ # has already seen the test period.+ reaches_in = label_ends[candidate] >= start+ train = candidate[~reaches_in]+ yield Split(+ train=train,+ test=np.arange(start, stop),+ purged=int(reaches_in.sum()),+ embargoed=0,+ test_bounds=(start, stop - 1),+ )+++def combinatorial_purged_splits(+ n_samples: int,+ label_end_times: pd.Series | Sequence[int] | np.ndarray | None = None,+ n_groups: int = 6,+ n_test_groups: int = 2,+ embargo_fraction: float = DEFAULT_EMBARGO_FRACTION,+) -> Iterator[Split]:+ """Every combination of ``n_test_groups`` blocks held out at once.++ A single K-fold gives one estimate of generalisation per fold; combinatorial+ splits give ``C(n_groups, n_test_groups)`` of them, from which a distribution+ of out-of-sample performance can be built rather than a point estimate. This+ is the sampler behind CSCV-style overfitting diagnostics.++ Args:+ n_samples: Number of observations.+ label_end_times: Where each label's outcome window ends.+ n_groups: Contiguous blocks the sample is divided into.+ n_test_groups: Blocks held out per split.+ embargo_fraction: Fraction embargoed after each held-out region.++ Yields:+ One :class:`Split` per combination, with ``test`` holding the union of+ the held-out blocks.++ Raises:+ ValueError: If ``n_test_groups`` is not in ``[1, n_groups - 1]``, if+ ``n_groups`` exceeds the sample size, or if ``embargo_fraction`` is+ out of range.+ """+ from itertools import combinations++ if n_groups > n_samples:+ raise ValueError(f"{n_samples} samples cannot make {n_groups} groups")+ if not 1 <= n_test_groups < n_groups:+ raise ValueError(+ f"n_test_groups must be in [1, {n_groups - 1}], got {n_test_groups}"+ )+ if not 0.0 <= embargo_fraction < 1.0:+ raise ValueError(f"embargo_fraction must be in [0, 1), got {embargo_fraction}")++ if label_end_times is None:+ label_ends = np.arange(n_samples)+ else:+ label_ends = _as_label_spans(label_end_times, n_samples)++ embargo_size = int(round(n_samples * embargo_fraction))+ boundaries = np.linspace(0, n_samples, n_groups + 1).astype(int)+ blocks = [+ np.arange(int(boundaries[i]), int(boundaries[i + 1])) for i in range(n_groups)+ ]++ for chosen in combinations(range(n_groups), n_test_groups):+ test = np.concatenate([blocks[i] for i in chosen])+ if test.size == 0:+ continue+ test_mask = np.zeros(n_samples, dtype=bool)+ test_mask[test] = True++ train, purged, embargoed = _apply_purge_and_embargo(+ label_ends, test_mask, embargo_size+ )+ yield Split(+ train=train,+ test=np.sort(test),+ purged=purged,+ embargoed=embargoed,+ test_bounds=(int(test.min()), int(test.max())),+ )+++def detect_boundary_leakage(+ split: Split,+ label_end_times: pd.Series | Sequence[int] | np.ndarray | None = None,+ n_samples: int | None = None,+ embargo_size: int = 0,+) -> LeakageReport:+ """Audit a split for the three ways training can see the test period.++ This is the assertion that makes the off-by-one class of bug testable. Point+ it at any splitter -- including one from another library -- and it reports+ contamination rather than requiring the boundary arithmetic to be reviewed+ by eye.++ Args:+ split: The split to audit.+ label_end_times: Where each label's outcome window ends. When None, each+ label is assumed to resolve within its own bar and only the shared+ index check is meaningful.+ n_samples: Total sample size, needed only when ``label_end_times`` is a+ positional array of a different length.+ embargo_size: Observations that should have been embargoed after the+ test block, for checking the embargo was actually applied.++ Returns:+ A :class:`LeakageReport`.++ Raises:+ ValueError: If ``label_end_times`` cannot be normalised.+ """+ shared = np.intersect1d(split.train, split.test)++ if label_end_times is None:+ overlapping = np.array([], dtype=int)+ else:+ label_ends = _as_label_spans(label_end_times, n_samples)+ first_test = int(split.test.min())+ test_span_end = int(max(split.test.max(), label_ends[split.test].max()))+ train_starts = split.train+ train_ends = label_ends[split.train]+ mask = (train_starts <= test_span_end) & (train_ends >= first_test)+ overlapping = train_starts[mask]++ if embargo_size > 0:+ if label_end_times is None:+ span_end = int(split.test.max())+ else:+ label_ends = _as_label_spans(label_end_times, n_samples)+ span_end = int(max(split.test.max(), label_ends[split.test].max()))+ violations = split.train[+ (split.train > span_end) & (split.train <= span_end + embargo_size)+ ]+ else:+ violations = np.array([], dtype=int)++ return LeakageReport(+ overlapping=overlapping,+ shared=shared,+ embargo_violations=violations,+ clean=overlapping.size == 0 and shared.size == 0 and violations.size == 0,+ )diff --git a/agent/src/quantlib/eventstudy.py b/agent/src/quantlib/eventstudy.pynew file mode 100644index 000000000..fa0b4ba54--- /dev/null+++ b/agent/src/quantlib/eventstudy.py@@ -0,0 +1,495 @@+"""Event study: abnormal returns around a dated corporate or macro event.++The question this answers is "did the market react to the event, beyond what it+would have done anyway", and the whole method is the *beyond* clause. A raw+return around an earnings date is not evidence of anything: the index moved too.+So a normal-return model is fitted on a window that ends before the event, and+what the model fails to explain during the event window is the abnormal return.++ AR_{i,t} = R_{i,t} - E[R_{i,t}] (abnormal return, one day)+ CAR_i = sum over the event window (one event's cumulative reaction)+ CAAR = mean CAR across events (the sample's average reaction)++THE ESTIMATION WINDOW MUST NOT TOUCH THE EVENT WINDOW+-----------------------------------------------------+If the event's own returns are inside the sample the model was fitted on, the+model has partly learned the event, the residual shrinks toward zero, and the+study under-reports its own finding. :data:`DEFAULT_ESTIMATION_GAP` puts rows+between the two windows, and an overlap is an error rather than a warning.++DAYS ARE ROWS, NOT CALENDAR DAYS+--------------------------------+Relative day ``-1`` means "the row before the event row" in the supplied return+frame. With daily bars that is the previous trading day, which is what event+studies mean by ``t-1``. A frame with gaps, or with a different bar size, shifts+that meaning; the caller owns the frame's spacing.++WHY THREE TEST STATISTICS+-------------------------+``t_statistic``+ Plain cross-sectional t-test on the CARs. Assumes the events are independent+ and equally variable. Fine for a quick read, wrong when a few volatile names+ dominate the sample.++``patell_z``+ Standardises each daily abnormal return by the standard error the estimation+ window implies for it, including the prediction-error term that accounts for+ the market return on that day sitting far from its estimation-window mean.+ Corrects for cross-sectional differences in volatility, but still assumes+ event-window variance equals estimation-window variance.++``bmp_z``+ Boehmer-Musumeci-Poulsen. Standardises like Patell, then takes the+ cross-sectional variance *of the standardised values*. This is the one that+ survives event-induced variance -- events routinely raise volatility, which+ inflates Patell's rejection rate. When the three disagree, BMP is the one to+ report.++None of the three fixes cross-sectional correlation from events that share a+date; clustered event dates need a calendar-time portfolio instead, and this+module says so via :attr:`EventStudyResult.shared_event_dates` rather than+silently reporting an over-confident z.+"""++from __future__ import annotations++from collections.abc import Sequence+from dataclasses import dataclass++import numpy as np+import pandas as pd+from scipy.stats import norm, t as student_t++__all__ = [+ "DEFAULT_ESTIMATION_GAP",+ "DEFAULT_ESTIMATION_WINDOW",+ "DEFAULT_EVENT_WINDOW",+ "MIN_ESTIMATION_OBSERVATIONS",+ "NORMAL_RETURN_MODELS",+ "EventOutcome",+ "EventStudyResult",+ "MarketModelFit",+ "estimate_market_model",+ "event_study",+]++#: Rows placed between the end of the estimation window and the start of the+#: event window, so no event-window return can inform the model fitted on it.+DEFAULT_ESTIMATION_GAP: int = 10++#: Rows used to fit the normal-return model.+DEFAULT_ESTIMATION_WINDOW: int = 120++#: Event window in relative rows, inclusive on both ends.+DEFAULT_EVENT_WINDOW: tuple[int, int] = (-5, 5)++#: Fewest estimation observations that still leave the residual variance and the+#: Patell correction meaningful. Below this an event is dropped, not fitted.+MIN_ESTIMATION_OBSERVATIONS: int = 30++#: Normal-return models understood by :func:`event_study`.+#:+#: ``market`` OLS of asset on market: E[R] = alpha + beta * R_m.+#: ``market_adjusted`` beta fixed at 1, alpha at 0: E[R] = R_m. No estimation+#: window is needed for the mean, but one is still required+#: for the residual variance the tests are scaled by.+#: ``mean_adjusted`` E[R] = mean of the estimation window. Ignores the market.+NORMAL_RETURN_MODELS: tuple[str, ...] = ("market", "market_adjusted", "mean_adjusted")+++@dataclass(frozen=True)+class MarketModelFit:+ """Normal-return model fitted on one asset's estimation window.++ Attributes:+ alpha: Intercept. Zero by construction for the non-OLS models.+ beta: Market sensitivity. One for ``market_adjusted``, zero for+ ``mean_adjusted``.+ residual_std: Standard deviation of the estimation-window residuals,+ with the model's degrees of freedom removed.+ observations: Estimation-window rows actually used.+ market_mean: Mean market return over the estimation window, needed by+ the Patell prediction-error correction.+ market_sum_squares: Sum of squared market deviations over the estimation+ window, likewise.+ model: Which entry of :data:`NORMAL_RETURN_MODELS` was fitted.+ """++ alpha: float+ beta: float+ residual_std: float+ observations: int+ market_mean: float+ market_sum_squares: float+ model: str+++@dataclass(frozen=True)+class EventOutcome:+ """One event's abnormal returns and cumulative reaction.++ Attributes:+ symbol: Asset the event belongs to.+ event_date: Index label the event was anchored on.+ abnormal_returns: Abnormal return per relative day, indexed by relative+ day, ordered from the window's first day to its last.+ car: Cumulative abnormal return over the whole event window.+ car_std_error: Standard error of ``car`` implied by the estimation+ window, including the Patell prediction-error term.+ standardised_car: ``car / car_std_error``. This is the quantity BMP+ takes a cross-sectional variance of.+ fit: The normal-return model behind these numbers.+ """++ symbol: str+ event_date: object+ abnormal_returns: pd.Series+ car: float+ car_std_error: float+ standardised_car: float+ fit: MarketModelFit+++@dataclass(frozen=True)+class EventStudyResult:+ """Aggregate reaction across every event that could be measured.++ Attributes:+ event_window: The ``(start, end)`` relative-row window, inclusive.+ events: Per-event outcomes, in input order, for events that survived.+ dropped: ``(symbol, event_date, reason)`` for each event that could not+ be measured. Never silently omitted -- a study over 40 events of+ which 18 were dropped is a different study.+ aar: Average abnormal return per relative day.+ caar: Cumulative average abnormal return per relative day, the running+ sum of ``aar`` across the window.+ caar_total: ``caar`` at the window's last day, the headline number.+ t_statistic: Cross-sectional t-test on the CARs.+ t_p_value: Two-sided p-value of ``t_statistic``.+ patell_z: Patell standardised-residual z.+ patell_p_value: Two-sided p-value of ``patell_z``.+ bmp_z: Boehmer-Musumeci-Poulsen standardised cross-sectional z.+ bmp_p_value: Two-sided p-value of ``bmp_z``.+ shared_event_dates: Event dates carried by more than one event. Non-empty+ means the events overlap in calendar time, the independence every+ statistic here assumes is violated, and the p-values are optimistic.+ """++ event_window: tuple[int, int]+ events: tuple[EventOutcome, ...]+ dropped: tuple[tuple[str, object, str], ...]+ aar: pd.Series+ caar: pd.Series+ caar_total: float+ t_statistic: float+ t_p_value: float+ patell_z: float+ patell_p_value: float+ bmp_z: float+ bmp_p_value: float+ shared_event_dates: tuple[object, ...]+++def estimate_market_model(+ asset_returns: pd.Series | np.ndarray | Sequence[float],+ market_returns: pd.Series | np.ndarray | Sequence[float],+ model: str = "market",+) -> MarketModelFit:+ """Fit a normal-return model on an estimation window.++ Args:+ asset_returns: Asset returns over the estimation window.+ market_returns: Market returns over the same window, same length and+ same order.+ model: One of :data:`NORMAL_RETURN_MODELS`.++ Returns:+ A :class:`MarketModelFit`.++ Raises:+ ValueError: If ``model`` is unknown, the two series differ in length,+ fewer than :data:`MIN_ESTIMATION_OBSERVATIONS` finite pairs survive,+ or the market series has no variation at all under the ``market``+ model (beta would be undefined).+ """+ if model not in NORMAL_RETURN_MODELS:+ raise ValueError(+ f"model must be one of {NORMAL_RETURN_MODELS}, got {model!r}"+ )++ asset = np.asarray(asset_returns, dtype=float).ravel()+ market = np.asarray(market_returns, dtype=float).ravel()+ if asset.size != market.size:+ raise ValueError(+ f"asset and market must be the same length, got {asset.size} and {market.size}"+ )++ keep = np.isfinite(asset) & np.isfinite(market)+ asset, market = asset[keep], market[keep]+ n = asset.size+ if n < MIN_ESTIMATION_OBSERVATIONS:+ raise ValueError(+ f"estimation window needs at least {MIN_ESTIMATION_OBSERVATIONS} "+ f"finite observations, got {n}"+ )++ market_mean = float(market.mean())+ market_sum_squares = float(np.sum((market - market_mean) ** 2))++ if model == "market":+ if market_sum_squares <= 0.0:+ raise ValueError(+ "market returns are constant over the estimation window, so beta "+ "is not identified; use model='mean_adjusted'"+ )+ beta = float(np.sum((market - market_mean) * (asset - asset.mean())) / market_sum_squares)+ alpha = float(asset.mean() - beta * market_mean)+ residuals = asset - (alpha + beta * market)+ dof = n - 2+ elif model == "market_adjusted":+ alpha, beta = 0.0, 1.0+ residuals = asset - market+ dof = n+ else: # mean_adjusted+ alpha, beta = float(asset.mean()), 0.0+ residuals = asset - alpha+ dof = n - 1++ residual_std = float(np.sqrt(np.sum(residuals**2) / dof)) if dof > 0 else float("nan")++ return MarketModelFit(+ alpha=alpha,+ beta=beta,+ residual_std=residual_std,+ observations=n,+ market_mean=market_mean,+ market_sum_squares=market_sum_squares,+ model=model,+ )+++def _patell_scale(fit: MarketModelFit, market_window: np.ndarray) -> np.ndarray:+ """Per-day standard error of an abnormal return, prediction error included.++ A forecast made far from the estimation window's average market return is+ less certain than one made near it, and Patell's correction is exactly that+ term. Dropping it understates the standard error and overstates significance.++ Args:+ fit: The fitted normal-return model.+ market_window: Market returns over the event window.++ Returns:+ Array of standard errors, one per event-window day.+ """+ if fit.model == "market" and fit.market_sum_squares > 0.0:+ prediction_error = (+ 1.0+ + 1.0 / fit.observations+ + (market_window - fit.market_mean) ** 2 / fit.market_sum_squares+ )+ elif fit.model == "mean_adjusted":+ prediction_error = np.full(market_window.shape, 1.0 + 1.0 / fit.observations)+ else: # market_adjusted has no estimated parameter to project+ prediction_error = np.ones(market_window.shape)+ return fit.residual_std * np.sqrt(prediction_error)+++def event_study(+ returns: pd.DataFrame,+ market_returns: pd.Series,+ events: Sequence[tuple[str, object]],+ event_window: tuple[int, int] = DEFAULT_EVENT_WINDOW,+ estimation_window: int = DEFAULT_ESTIMATION_WINDOW,+ estimation_gap: int = DEFAULT_ESTIMATION_GAP,+ model: str = "market",+) -> EventStudyResult:+ """Measure the abnormal return around a set of dated events.++ Args:+ returns: Simple returns, rows indexed by date, one column per symbol.+ market_returns: Market returns on the same index. Extra index labels are+ allowed; missing ones are not.+ events: ``(symbol, event_date)`` pairs. ``event_date`` must be present in+ the frame's index, or the nearest earlier row is used and the event+ is reported with the row it snapped to.+ event_window: Inclusive ``(start, end)`` in relative rows, e.g.+ ``(-5, 5)``. ``start`` may be positive if the window opens after the+ event, but must not exceed ``end``.+ estimation_window: Rows used to fit the normal-return model.+ estimation_gap: Rows left between the estimation window and the event+ window so the model cannot see the event.+ model: One of :data:`NORMAL_RETURN_MODELS`.++ Returns:+ An :class:`EventStudyResult`. Events that cannot be measured -- unknown+ symbol, event date before the frame starts, not enough estimation rows,+ an all-NaN window -- appear in ``dropped`` with a reason instead of+ being silently skipped.++ Raises:+ ValueError: If the window bounds are inconsistent, ``estimation_gap`` is+ negative, ``model`` is unknown, the market series does not cover the+ frame's index, or no event at all could be measured.+ """+ start, end = event_window+ if start > end:+ raise ValueError(f"event_window start must be <= end, got {event_window}")+ if estimation_gap < 0:+ raise ValueError(f"estimation_gap must be >= 0, got {estimation_gap}")+ if estimation_window < MIN_ESTIMATION_OBSERVATIONS:+ raise ValueError(+ f"estimation_window must be at least {MIN_ESTIMATION_OBSERVATIONS}, "+ f"got {estimation_window}"+ )+ if model not in NORMAL_RETURN_MODELS:+ raise ValueError(f"model must be one of {NORMAL_RETURN_MODELS}, got {model!r}")+ if not events:+ raise ValueError("events is empty")++ index = returns.index+ missing_market = index.difference(market_returns.index)+ if len(missing_market):+ raise ValueError(+ f"market_returns is missing {len(missing_market)} label(s) present in "+ "returns; align them before calling"+ )+ market_aligned = market_returns.reindex(index)++ relative_days = list(range(start, end + 1))+ window_len = len(relative_days)++ outcomes: list[EventOutcome] = []+ dropped: list[tuple[str, object, str]] = []++ for symbol, event_date in events:+ if symbol not in returns.columns:+ dropped.append((symbol, event_date, "symbol not in returns frame"))+ continue++ position = index.searchsorted(event_date)+ if position >= len(index):+ dropped.append((symbol, event_date, "event date is after the frame ends"))+ continue++ event_start = position + start+ event_end = position + end+ estimation_end = position + start - estimation_gap+ estimation_start = estimation_end - estimation_window++ if estimation_start < 0:+ dropped.append(+ (symbol, event_date, "not enough history before the estimation window")+ )+ continue+ if event_end >= len(index):+ dropped.append((symbol, event_date, "event window runs past the frame end"))+ continue++ asset_estimation = returns[symbol].iloc[estimation_start:estimation_end]+ market_estimation = market_aligned.iloc[estimation_start:estimation_end]+ try:+ fit = estimate_market_model(asset_estimation, market_estimation, model=model)+ except ValueError as exc:+ dropped.append((symbol, event_date, str(exc)))+ continue++ asset_window = returns[symbol].iloc[event_start : event_end + 1].to_numpy(dtype=float)+ market_window = market_aligned.iloc[event_start : event_end + 1].to_numpy(dtype=float)+ if not np.isfinite(asset_window).all() or not np.isfinite(market_window).all():+ dropped.append((symbol, event_date, "event window holds a non-finite return"))+ continue++ expected = fit.alpha + fit.beta * market_window+ abnormal = asset_window - expected+ car = float(abnormal.sum())++ daily_se = _patell_scale(fit, market_window)+ car_se = float(np.sqrt(np.sum(daily_se**2)))+ standardised = car / car_se if car_se > 0 else float("nan")++ outcomes.append(+ EventOutcome(+ symbol=symbol,+ event_date=index[position],+ abnormal_returns=pd.Series(abnormal, index=relative_days, name=symbol),+ car=car,+ car_std_error=car_se,+ standardised_car=standardised,+ fit=fit,+ )+ )++ if not outcomes:+ raise ValueError(+ "no event could be measured; reasons: "+ + "; ".join(f"{s}@{d}: {r}" for s, d, r in dropped)+ )++ n_events = len(outcomes)+ ar_matrix = np.vstack([o.abnormal_returns.to_numpy() for o in outcomes])+ aar = pd.Series(ar_matrix.mean(axis=0), index=relative_days, name="aar")+ caar = pd.Series(np.cumsum(aar.to_numpy()), index=relative_days, name="caar")++ cars = np.array([o.car for o in outcomes])+ if n_events > 1:+ car_sd = float(cars.std(ddof=1))+ t_stat = float(cars.mean() / (car_sd / np.sqrt(n_events))) if car_sd > 0 else float("nan")+ t_p = float(2 * student_t.sf(abs(t_stat), df=n_events - 1)) if np.isfinite(t_stat) else float("nan")+ else:+ t_stat, t_p = float("nan"), float("nan")++ standardised = np.array([o.standardised_car for o in outcomes])+ finite_scar = standardised[np.isfinite(standardised)]++ # Patell: the standardised CARs are unit-variance under the null, up to the+ # t-distribution correction for having estimated the residual variance.+ if finite_scar.size:+ corrections = np.array(+ [+ (o.fit.observations - 2) / (o.fit.observations - 4)+ if o.fit.observations > 4+ else np.nan+ for o in outcomes+ if np.isfinite(o.standardised_car)+ ]+ )+ variance = float(np.nansum(corrections))+ patell_z = float(finite_scar.sum() / np.sqrt(variance)) if variance > 0 else float("nan")+ else:+ patell_z = float("nan")+ patell_p = float(2 * norm.sf(abs(patell_z))) if np.isfinite(patell_z) else float("nan")++ # BMP: cross-sectional variance OF the standardised values, which is what+ # makes it robust to the event itself having raised volatility.+ if finite_scar.size > 1:+ scar_sd = float(finite_scar.std(ddof=1))+ bmp_z = (+ float(finite_scar.mean() / (scar_sd / np.sqrt(finite_scar.size)))+ if scar_sd > 0+ else float("nan")+ )+ else:+ bmp_z = float("nan")+ bmp_p = float(2 * norm.sf(abs(bmp_z))) if np.isfinite(bmp_z) else float("nan")++ seen: dict[object, int] = {}+ for outcome in outcomes:+ seen[outcome.event_date] = seen.get(outcome.event_date, 0) + 1+ shared = tuple(sorted((d for d, c in seen.items() if c > 1), key=str))++ return EventStudyResult(+ event_window=(start, end),+ events=tuple(outcomes),+ dropped=tuple(dropped),+ aar=aar,+ caar=caar,+ caar_total=float(caar.iloc[-1]),+ t_statistic=t_stat,+ t_p_value=t_p,+ patell_z=patell_z,+ patell_p_value=patell_p,+ bmp_z=bmp_z,+ bmp_p_value=bmp_p,+ shared_event_dates=shared,+ )diff --git a/agent/src/quantlib/factormodel.py b/agent/src/quantlib/factormodel.pynew file mode 100644index 000000000..66b11d1b7--- /dev/null+++ b/agent/src/quantlib/factormodel.py@@ -0,0 +1,515 @@+"""Cross-sectional style factor model: exposures, factor returns, drift.++This is the machinery behind "what is this portfolio actually betting on" --+whether a fund's outperformance came from a persistent tilt toward small, cheap,+high-momentum names, or from something the tilts do not explain.++IT IS NOT BARRA+---------------+Barra is a licensed commercial product from MSCI: their factor definitions,+their estimation universe, their covariance matrix. None of that is here and+none of it can be reproduced from public data. What is here is a+*Barra-style* cross-sectional model built from definitions stated in+:data:`STYLE_FACTOR_DEFINITIONS`, which are public-domain academic+constructions. Report the output as a style exposure from a named model. Never+present a number from this module as a Barra exposure -- they will not agree,+because they are not measuring the same thing.++THE STANDARDISATION IS THE MODEL+--------------------------------+An exposure is a cross-sectional z-score, so "value = 1.2" means *1.2 standard+deviations cheaper than the universe on this date*, not any absolute cheapness.+Three details make that number mean what it claims:++1. **Winsorise before standardising.** One delisting-bound name with a book/price+ of 40 will otherwise move the mean and inflate the standard deviation enough+ to compress every other name toward zero.+2. **Cap-weighted mean, equal-weighted standard deviation.** The mean is+ cap-weighted so that the *market portfolio* has zero exposure by construction+ -- which is what makes a portfolio's exposure readable as an active tilt away+ from the market rather than a level. The standard deviation is equal-weighted+ so a handful of megacaps cannot set the scale for the whole cross-section.+ This asymmetry is deliberate and is the convention commercial risk models use.+3. **A missing characteristic becomes exposure zero, i.e. the market average**,+ and the count of filled cells is reported. Dropping the name instead would+ silently change the universe between factors; imputing a nonzero value would+ invent a tilt.++FACTOR RETURNS COME FROM A CROSS-SECTIONAL REGRESSION+-----------------------------------------------------+For each date, regress that date's asset returns on the previous date's+exposures. The coefficients are the factor returns: what one unit of exposure+paid on that day. Weighting by square-root market cap is the standard choice --+it treats the regression as heteroskedastic in the way small caps actually are,+without letting megacaps dominate as full-cap weighting would.++The intercept is the market factor. It must be present: dropping it forces every+factor to absorb the market's return, and the "value factor" then reports the+market's direction.+"""++from __future__ import annotations++from collections.abc import Mapping, Sequence+from dataclasses import dataclass++import numpy as np+import pandas as pd++__all__ = [+ "DEFAULT_WINSORISE",+ "MARKET_FACTOR",+ "MIN_CROSS_SECTION",+ "STYLE_FACTOR_DEFINITIONS",+ "FactorReturnFit",+ "StyleDrift",+ "standardise_exposures",+ "build_style_exposures",+ "cross_sectional_factor_returns",+ "portfolio_style_exposure",+ "style_drift",+ "factor_return_attribution",+]++#: Fraction trimmed from each tail before standardising.+DEFAULT_WINSORISE: float = 0.025++#: Name of the regression intercept, which is the market factor.+MARKET_FACTOR: str = "market"++#: Fewest assets a cross-section needs before a z-score or a regression on it+#: means anything. Below this the standard deviation is noise.+MIN_CROSS_SECTION: int = 10++#: Style factors and the raw characteristics each is built from.+#:+#: Each entry maps a factor name to ``{characteristic: sign}``. The+#: characteristic names are what :func:`build_style_exposures` expects as+#: columns; ``sign`` is ``+1`` when a larger raw value means a larger exposure+#: and ``-1`` when it means a smaller one. Every characteristic is standardised+#: on its own before the signed average, so factors built from several inputs+#: are not dominated by whichever input happens to have the widest spread.+#:+#: These are public academic definitions, restated here so that a reader can+#: check what a reported exposure actually measured. They are deliberately+#: simple: a defensible published construction beats an unverifiable proprietary+#: one when the alternative is having no model at all.+STYLE_FACTOR_DEFINITIONS: Mapping[str, Mapping[str, int]] = {+ # Fama-French SMB direction: small minus big, so smaller cap = larger exposure.+ "size": {"log_market_cap": -1},+ # HML: book-to-price and earnings-to-price, both larger when cheaper.+ "value": {"book_to_price": 1, "earnings_to_price": 1},+ "growth": {"sales_growth": 1, "earnings_growth": 1},+ # Jegadeesh-Titman: 12-month return skipping the most recent month, because+ # the skipped month carries short-term reversal, not momentum.+ "momentum": {"return_12m_ex_1m": 1},+ "quality": {"return_on_equity": 1, "gross_profitability": 1},+ # Low-volatility anomaly: less volatile = larger exposure.+ "low_volatility": {"realised_volatility": -1},+ "leverage": {"debt_to_equity": 1},+ # Amihud illiquidity inverted, so larger exposure = more liquid.+ "liquidity": {"turnover": 1},+}+++@dataclass(frozen=True)+class FactorReturnFit:+ """One date's cross-sectional regression of returns on exposures.++ Attributes:+ date: Label of the return date.+ factor_returns: Estimated return per unit of exposure, indexed by factor+ name. Includes :data:`MARKET_FACTOR` as the intercept.+ t_statistics: Coefficient t-statistics on the same index.+ residuals: Per-asset specific return, indexed by asset.+ r_squared: Fraction of the cross-sectional return variance explained.+ observations: Assets in the regression.+ """++ date: object+ factor_returns: pd.Series+ t_statistics: pd.Series+ residuals: pd.Series+ r_squared: float+ observations: int+++@dataclass(frozen=True)+class StyleDrift:+ """How much a portfolio's exposures moved over the observed history.++ Attributes:+ mean_exposure: Average exposure per factor across the history.+ std_exposure: Standard deviation of exposure per factor -- the drift+ measure itself.+ first_exposure: Exposure at the first observed date.+ last_exposure: Exposure at the last observed date.+ total_change: ``last_exposure - first_exposure``.+ max_abs_change: Largest absolute period-on-period move per factor. A+ fund can end where it started having gone somewhere else entirely,+ and this is the column that shows it.+ """++ mean_exposure: pd.Series+ std_exposure: pd.Series+ first_exposure: pd.Series+ last_exposure: pd.Series+ total_change: pd.Series+ max_abs_change: pd.Series+++def standardise_exposures(+ values: pd.Series,+ market_caps: pd.Series | None = None,+ winsorise: float = DEFAULT_WINSORISE,+) -> pd.Series:+ """Turn a raw characteristic into a cross-sectional exposure.++ Winsorises both tails, then subtracts a cap-weighted mean and divides by an+ equal-weighted standard deviation. See the module docstring for why those+ two weightings differ.++ Args:+ values: Raw characteristic, indexed by asset. NaN entries survive as NaN+ and are the caller's to fill (:func:`build_style_exposures` fills+ them with zero and counts them).+ market_caps: Market capitalisation on the same index, used for the mean.+ When None, the mean is equal-weighted.+ winsorise: Fraction trimmed from each tail, in ``[0, 0.5)``.++ Returns:+ Standardised exposures on the input index.++ Raises:+ ValueError: If ``winsorise`` is outside ``[0, 0.5)``, if fewer than+ :data:`MIN_CROSS_SECTION` finite values are present, or if+ ``market_caps`` does not cover the same index.+ """+ if not 0.0 <= winsorise < 0.5:+ raise ValueError(f"winsorise must be in [0, 0.5), got {winsorise}")++ series = pd.Series(values, dtype=float)+ finite = series.dropna()+ if finite.size < MIN_CROSS_SECTION:+ raise ValueError(+ f"a cross-section needs at least {MIN_CROSS_SECTION} finite values to "+ f"standardise, got {finite.size}"+ )++ if winsorise > 0:+ lower, upper = finite.quantile(winsorise), finite.quantile(1.0 - winsorise)+ clipped = series.clip(lower=lower, upper=upper)+ else:+ clipped = series++ if market_caps is None:+ centre = float(clipped.dropna().mean())+ else:+ caps = pd.Series(market_caps, dtype=float)+ missing = series.index.difference(caps.index)+ if len(missing):+ raise ValueError(+ f"market_caps is missing {len(missing)} asset(s) present in values"+ )+ aligned_caps = caps.reindex(clipped.index)+ usable = clipped.notna() & aligned_caps.notna() & (aligned_caps > 0)+ if not usable.any():+ raise ValueError("no asset has both a finite value and a positive market cap")+ weights = aligned_caps[usable]+ centre = float((clipped[usable] * weights).sum() / weights.sum())++ spread = float(clipped.dropna().std(ddof=1))+ if not np.isfinite(spread) or spread <= 0.0:+ raise ValueError(+ "the characteristic has no cross-sectional variation, so a z-score "+ "would divide by zero"+ )+ return (clipped - centre) / spread+++def build_style_exposures(+ characteristics: pd.DataFrame,+ market_caps: pd.Series | None = None,+ definitions: Mapping[str, Mapping[str, int]] = STYLE_FACTOR_DEFINITIONS,+ winsorise: float = DEFAULT_WINSORISE,+) -> tuple[pd.DataFrame, dict[str, int]]:+ """Assemble a style exposure matrix from raw characteristics.++ Args:+ characteristics: Raw values, rows indexed by asset, one column per+ characteristic named in ``definitions``. Columns a definition asks+ for but the frame does not carry cause that factor to be skipped,+ reported through the returned fill counts.+ market_caps: Market capitalisation by asset, for the cap-weighted mean.+ definitions: Factor construction map; defaults to+ :data:`STYLE_FACTOR_DEFINITIONS`.+ winsorise: Fraction trimmed from each tail before standardising.++ Returns:+ Tuple of ``(exposures, filled)``. ``exposures`` has one row per asset+ and one column per constructible factor. ``filled`` maps each factor to+ the number of assets whose exposure was imputed as zero because the+ underlying characteristic was missing -- a factor with most of its cells+ filled is not a measurement and the caller must be able to see that.++ Raises:+ ValueError: If ``characteristics`` is empty, or if no factor at all can+ be built from the columns supplied.+ """+ if characteristics.empty:+ raise ValueError("characteristics frame is empty")++ columns: dict[str, pd.Series] = {}+ filled: dict[str, int] = {}++ for factor, recipe in definitions.items():+ available = {c: s for c, s in recipe.items() if c in characteristics.columns}+ if not available:+ continue++ parts = []+ for characteristic, sign in available.items():+ raw = characteristics[characteristic]+ try:+ standardised = standardise_exposures(+ raw, market_caps=market_caps, winsorise=winsorise+ )+ except ValueError:+ # A single unusable characteristic must not take the whole factor+ # down when the factor has other inputs.+ continue+ parts.append(standardised * sign)++ if not parts:+ continue++ combined = pd.concat(parts, axis=1).mean(axis=1)+ filled[factor] = int(combined.isna().sum())+ columns[factor] = combined.fillna(0.0)++ if not columns:+ raise ValueError(+ "no factor could be built; characteristics carries none of the "+ f"columns any definition needs: {sorted(characteristics.columns)}"+ )+ return pd.DataFrame(columns), filled+++def cross_sectional_factor_returns(+ returns: pd.Series,+ exposures: pd.DataFrame,+ market_caps: pd.Series | None = None,+ date: object = None,+) -> FactorReturnFit:+ """Regress one date's asset returns on their exposures.++ The coefficients are that date's factor returns. Weighting is by square-root+ market cap when caps are supplied, which is the standard choice: it respects+ that small-cap residuals are noisier without letting megacaps set the fit.++ Args:+ returns: Asset returns for the date being explained, indexed by asset.+ exposures: Exposure matrix from the *previous* date, rows indexed by+ asset. Using the same date's exposures would be a look-ahead: the+ characteristic and the return would share information.+ market_caps: Market capitalisation by asset for the regression weights.+ When None the regression is unweighted.+ date: Label recorded on the result. Purely informational.++ Returns:+ A :class:`FactorReturnFit`.++ Raises:+ ValueError: If fewer than :data:`MIN_CROSS_SECTION` assets are common to+ the inputs, if the design matrix has more columns than rows, or if+ the exposures are perfectly collinear.+ """+ common = returns.dropna().index.intersection(exposures.dropna(how="any").index)+ if len(common) < MIN_CROSS_SECTION:+ raise ValueError(+ f"cross-sectional regression needs at least {MIN_CROSS_SECTION} assets "+ f"with both a return and full exposures, got {len(common)}"+ )++ y = returns.loc[common].to_numpy(dtype=float)+ factor_names = list(exposures.columns)+ design = np.column_stack(+ [np.ones(len(common)), exposures.loc[common].to_numpy(dtype=float)]+ )+ names = [MARKET_FACTOR, *factor_names]++ if design.shape[1] > design.shape[0]:+ raise ValueError(+ f"{design.shape[1]} regressors but only {design.shape[0]} assets; "+ "the fit would be exactly determined and meaningless"+ )++ if market_caps is None:+ weights = np.ones(len(common))+ else:+ caps = pd.Series(market_caps, dtype=float).reindex(common)+ if caps.isna().any() or (caps <= 0).any():+ raise ValueError(+ "market_caps must be positive and defined for every asset in the "+ "regression"+ )+ weights = np.sqrt(caps.to_numpy(dtype=float))++ sqrt_w = np.sqrt(weights)+ design_w = design * sqrt_w[:, None]+ y_w = y * sqrt_w++ rank = np.linalg.matrix_rank(design_w)+ if rank < design_w.shape[1]:+ raise ValueError(+ "the exposure matrix is collinear with the market factor or with "+ "itself, so the coefficients are not identified"+ )++ coefficients, *_ = np.linalg.lstsq(design_w, y_w, rcond=None)+ fitted = design @ coefficients+ residuals = y - fitted++ dof = len(common) - design.shape[1]+ weighted_residuals = y_w - design_w @ coefficients+ sigma_squared = float(weighted_residuals @ weighted_residuals / dof) if dof > 0 else np.nan+ try:+ covariance = sigma_squared * np.linalg.inv(design_w.T @ design_w)+ standard_errors = np.sqrt(np.diag(covariance))+ except np.linalg.LinAlgError: # pragma: no cover - guarded by the rank check+ standard_errors = np.full(design.shape[1], np.nan)++ with np.errstate(divide="ignore", invalid="ignore"):+ t_stats = np.where(standard_errors > 0, coefficients / standard_errors, np.nan)++ total_variance = float(np.sum((y - y.mean()) ** 2))+ r_squared = (+ 1.0 - float(residuals @ residuals) / total_variance if total_variance > 0 else np.nan+ )++ return FactorReturnFit(+ date=date,+ factor_returns=pd.Series(coefficients, index=names, name="factor_return"),+ t_statistics=pd.Series(t_stats, index=names, name="t_statistic"),+ residuals=pd.Series(residuals, index=common, name="specific_return"),+ r_squared=r_squared,+ observations=len(common),+ )+++def portfolio_style_exposure(+ holdings: pd.Series,+ exposures: pd.DataFrame,+ benchmark: pd.Series | None = None,+) -> pd.Series:+ """Aggregate asset exposures into a portfolio exposure.++ Args:+ holdings: Portfolio weights by asset. Need not sum to 1; the weights are+ used as supplied, so a book that is 60% invested reports a 60%-scaled+ exposure, which is the honest reading.+ exposures: Exposure matrix, rows indexed by asset.+ benchmark: Benchmark weights by asset. When supplied, the result is the+ ACTIVE exposure (portfolio minus benchmark), which is what an+ attribution conversation is about.++ Returns:+ Exposure per factor. Assets held but absent from ``exposures`` are+ reported through the ``unmatched_weight`` entry rather than dropped, so+ a portfolio half of whose weight had no exposure data cannot read as a+ clean measurement.++ Raises:+ ValueError: If ``holdings`` is empty or ``exposures`` has no columns.+ """+ weights = pd.Series(holdings, dtype=float).dropna()+ if weights.empty:+ raise ValueError("holdings is empty")+ if exposures.shape[1] == 0:+ raise ValueError("exposures has no factor columns")++ matched = weights.index.intersection(exposures.index)+ unmatched_weight = float(weights.drop(matched).abs().sum())+ result = exposures.loc[matched].mul(weights.loc[matched], axis=0).sum()++ if benchmark is not None:+ bench = pd.Series(benchmark, dtype=float).dropna()+ bench_matched = bench.index.intersection(exposures.index)+ unmatched_weight += float(bench.drop(bench_matched).abs().sum())+ result = result - exposures.loc[bench_matched].mul(+ bench.loc[bench_matched], axis=0+ ).sum()++ result["unmatched_weight"] = unmatched_weight+ return result+++def style_drift(exposure_history: pd.DataFrame) -> StyleDrift:+ """Summarise how a portfolio's exposures moved over time.++ Args:+ exposure_history: Rows indexed by date in chronological order, one+ column per factor, each cell a portfolio-level exposure from+ :func:`portfolio_style_exposure`.++ Returns:+ A :class:`StyleDrift`.++ Raises:+ ValueError: If fewer than two dates are supplied -- drift is a change,+ and one observation cannot express one.+ """+ if exposure_history.shape[0] < 2:+ raise ValueError(+ f"style drift needs at least 2 dates, got {exposure_history.shape[0]}"+ )++ frame = exposure_history.drop(columns=["unmatched_weight"], errors="ignore")+ return StyleDrift(+ mean_exposure=frame.mean(),+ std_exposure=frame.std(ddof=1),+ first_exposure=frame.iloc[0],+ last_exposure=frame.iloc[-1],+ total_change=frame.iloc[-1] - frame.iloc[0],+ max_abs_change=frame.diff().abs().max(),+ )+++def factor_return_attribution(+ portfolio_exposures: pd.Series,+ factor_returns: pd.Series,+ portfolio_return: float,+) -> pd.Series:+ """Split a portfolio return into factor contributions plus a specific residual.++ Args:+ portfolio_exposures: Portfolio exposure per factor.+ factor_returns: Factor return per factor over the same period.+ portfolio_return: The realised portfolio return being explained.++ Returns:+ Contribution per factor (exposure times factor return), plus a+ ``specific`` entry holding the unexplained remainder and a ``total``+ entry equal to ``portfolio_return``. The parts sum to the total by+ construction: the residual is defined as what is left, never estimated+ separately, so no reconciliation gap can appear.++ Raises:+ ValueError: If the two inputs share no factor.+ """+ exposures = pd.Series(portfolio_exposures, dtype=float).drop(+ labels=["unmatched_weight"], errors="ignore"+ )+ returns = pd.Series(factor_returns, dtype=float)+ shared = exposures.index.intersection(returns.index)+ if shared.empty:+ raise ValueError(+ "portfolio_exposures and factor_returns share no factor; "+ f"exposures={sorted(exposures.index)} returns={sorted(returns.index)}"+ )++ contributions = exposures.loc[shared] * returns.loc[shared]+ explained = float(contributions.sum())+ contributions["specific"] = portfolio_return - explained+ contributions["total"] = portfolio_return+ return contributionsdiff --git a/agent/src/quantlib/fundmath.py b/agent/src/quantlib/fundmath.pyindex a3b1b3b07..64597a082 100644--- a/agent/src/quantlib/fundmath.py+++ b/agent/src/quantlib/fundmath.py@@ -32,10 +32,12 @@ from __future__ import annotationsimport datetime as _dtimport math-from collections.abc import Iterable, Sequence+from collections.abc import Iterable, Mapping, Sequencefrom dataclasses import dataclass+from types import MappingProxyTypeimport numpy as np+import pandas as pdfrom scipy.optimize import brentq, newtonfrom src.entities.cashflow import CashFlow, CashFlowSeries@@ -75,6 +77,14 @@ __all__ = ["preferred_return_amount","waterfall_split","european_waterfall",+ "PMEPlusResult",+ "ks_pme",+ "pme_plus",+ "direct_alpha",+ "AmericanWaterfallResult",+ "american_waterfall",+ "ClawbackResult",+ "gp_clawback",]#: Kinds treated as capital going into the fund. A parameter everywhere it is@@ -1296,3 +1306,1026 @@ def european_waterfall(carry_rate=carry_rate,catch_up_rate=catch_up_rate,)+++# ---------------------------------------------------------------------------+# Public market equivalent (PME)+# ---------------------------------------------------------------------------+#+# All three functions below answer the same question -- "did this fund beat a+# public index?" -- from the same two inputs (a CashFlowSeries and a public+# index level series), but they are not interchangeable and answer it in+# different units:+#+# ks_pme a multiple. >1 means the fund beat the index; the number+# itself is not a rate and cannot be annualized.+# pme_plus an IRR, but one that is only meaningful *relative to the+# fund's own realised IRR* -- it is the rate an index-tracking+# portfolio would have posted had it been forced to end at the+# fund's actual NAV. Comparing it to another fund's PME+ IRR+# is not valid; comparing it to *this fund's own* xirr() is.+# direct_alpha an annualized excess return, directly interpretable on its+# own: positive means the fund beat the index by that many+# points a year, negative means it lagged. This is the only+# one of the three that is a standalone number.+#+# All three require the public index to have a level on every date they touch+# and refuse to forward-fill a gap, because a cash flow landing inside a+# missing stretch would otherwise be discounted against a silently wrong+# price. Terminal NAV is handled the same way fund_multiples() already+# handles it -- via residual_value(), i.e. only the single latest valuation+# mark counts, per the existing VALUATION_POLICIES convention. direct_alpha is+# the one exception: it hands every flow to xirr() unchanged and lets the+# caller's own valuations= policy decide, exactly like npv()/xirr() already+# do, so it is the most flexible of the three but also the one that needs the+# index to cover every mark in the series, not only the terminal one.+++def _index_levels_by_date(index_levels: pd.Series) -> dict[_dt.date, float]:+ """Build a date -> level lookup table from a public index series.++ Args:+ index_levels: Public-market index levels, a ``pandas.Series`` whose+ index is date-like (``DatetimeIndex``, or labels accepted by+ :func:`~src.entities.models.normalize_date`) and whose values are+ the index's level on each date (a price or a total-return index+ value, not a return).++ Returns:+ Mapping from ``datetime.date`` to the index level on that date.++ Raises:+ TypeError: If ``index_levels`` is not a ``pandas.Series``.+ ValueError: If it is empty, a level is not finite and positive, or two+ entries normalize to the same date (an ambiguous lookup, refused+ rather than guessed at by taking the first or last).+ """+ if not isinstance(index_levels, pd.Series):+ raise TypeError(+ "index_levels must be a pandas Series of index levels indexed by "+ f"date, got {type(index_levels).__name__}"+ )+ if index_levels.empty:+ raise ValueError(+ "index_levels is empty; a public market equivalent needs a "+ "benchmark to compare against"+ )+ lookup: dict[_dt.date, float] = {}+ for raw_date, raw_level in index_levels.items():+ day = normalize_date(raw_date, field_name="index_levels date")+ if day in lookup:+ raise ValueError(+ f"index_levels has more than one entry for {day}; resolve the "+ "duplicate before calling, rather than have this function "+ "guess which one is authoritative"+ )+ level = float(raw_level)+ if not math.isfinite(level) or level <= 0.0:+ raise ValueError(+ f"index level on {day} is {raw_level!r}; index levels must be "+ "finite and positive to serve as a growth-factor denominator"+ )+ lookup[day] = level+ return lookup+++def _index_level_at(+ lookup: Mapping[_dt.date, float], day: _dt.date, *, flow_description: str+) -> float:+ """Look up one date in an index lookup table, or fail loudly.++ Args:+ lookup: Table built by :func:`_index_levels_by_date`.+ day: Date to look up.+ flow_description: Human-readable description of what needed this+ date, quoted in the error message.++ Returns:+ The index level on ``day``.++ Raises:+ ValueError: If ``day`` has no entry. Forward-filling across the gap+ is deliberately not attempted: a flow that lands inside a missing+ stretch would then be discounted against a price that was never+ actually observed on that date.+ """+ try:+ return lookup[day]+ except KeyError as exc:+ raise ValueError(+ f"index_levels has no entry for {day} (needed for {flow_description}); "+ "forward-filling across the gap is not done automatically, because "+ "it would price a flow that lands inside a missing stretch against "+ "a level that was never actually observed on that date. Supply an "+ "index level for every cash-flow date this calculation touches."+ ) from exc+++def _terminal_mark(series: CashFlowSeries) -> CashFlow | None:+ """The most recent valuation record in a series, if any.++ Selects the same record :func:`residual_value` would report the amount+ of, but also returns the record itself so its date is available -- which+ :func:`residual_value` has no reason to expose, but the PME functions+ need in order to look up an index level for it.++ Args:+ series: The cash flows.++ Returns:+ The latest ``CashFlow`` with ``is_valuation`` True, date-ordered same+ as the series; ``None`` if the series carries no valuation record.+ """+ marks = [flow for flow in series if flow.is_valuation]+ return marks[-1] if marks else None+++def _default_as_of(series: CashFlowSeries) -> _dt.date:+ """Default measurement date for a PME calculation.++ Uses the terminal valuation mark's own date when the series carries one,+ because that mark is already "as of" some date, and growing it further+ with the index would assume the market kept the index's pace past the+ point somebody actually priced the fund. Falls back to the latest flow+ date when there is no mark at all -- the same rule+ :func:`preferred_return_amount` already uses for its own ``as_of=None``.++ Args:+ series: The cash flows.++ Returns:+ The date to measure at when the caller does not name one explicitly.++ Raises:+ ValueError: If the series is empty.+ """+ if series.is_empty:+ raise ValueError("as_of is required for an empty series")+ mark = _terminal_mark(series)+ return mark.date if mark is not None else max(series.dates())+++def ks_pme(+ series: CashFlowSeries,+ index_levels: pd.Series,+ *,+ as_of: _dt.date | _dt.datetime | str | None = None,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> float:+ """Kaplan-Schoar public market equivalent.++ Every contribution and distribution is grown to a single common date+ (``as_of``) using the *public index's* realised growth between the flow's+ own date and ``as_of`` -- i.e. each flow is asking "what would this dollar+ be worth today if it had instead been invested in the index on this+ date". Terminal NAV, via :func:`residual_value` (only the latest mark+ counts, matching how :func:`fund_multiples` already treats it), is added+ to the distributions side unchanged in kind but likewise grown from its+ own mark date to ``as_of``::++ KS-PME = (FV(distributions) + FV(NAV)) / FV(contributions)++ A result above 1 means the fund returned more than the index would have+ over the same capital deployment schedule; below 1 means it returned+ less. KS-PME is a multiple, not a rate -- it says nothing about *how+ fast* the outperformance happened, which is what :func:`direct_alpha`+ is for.++ Args:+ series: The fund's cash flows.+ index_levels: Public index levels. Must have an entry for every+ contribution date, every distribution date, the terminal+ valuation's date (if any), and ``as_of`` itself.+ as_of: Common date to grow every flow to. ``None`` uses+ :func:`_default_as_of` (the terminal mark's date, or the latest+ flow date).+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ The KS-PME multiple.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``, or+ ``index_levels`` is not a ``pandas.Series``.+ ValueError: If ``index_levels`` is empty or has a non-positive level,+ if it lacks an entry for a date this calculation needs, if no+ contributions were found (or their future value is zero -- KS-PME+ has nothing to divide by), or if a contribution/distribution's+ sign contradicts the holder-perspective convention.+ """+ _require_series(series)+ lookup = _index_levels_by_date(index_levels)+ measurement = (+ normalize_date(as_of, field_name="as_of")+ if as_of is not None+ else _default_as_of(series)+ )+ index_as_of = _index_level_at(lookup, measurement, flow_description="as_of")++ contributions = tuple(series.filter(kind=contribution_kinds))+ fv_contributions = 0.0+ for flow in contributions:+ if flow.amount > 0.0:+ raise ValueError(+ f"contribution on {flow.date} has a positive amount "+ f"{flow.amount!r}; under the holder-perspective sign "+ "convention capital going into a fund is negative"+ )+ index_then = _index_level_at(+ lookup, flow.date, flow_description=f"contribution on {flow.date}"+ )+ fv_contributions += (-flow.amount) * (index_as_of / index_then)+ if fv_contributions <= 0.0:+ raise ValueError(+ "no contributions were found (or their future value at as_of is "+ "zero); KS-PME is undefined with nothing paid in"+ )++ distributions = tuple(series.filter(kind=distribution_kinds))+ fv_distributions = 0.0+ for flow in distributions:+ if flow.amount < 0.0:+ raise ValueError(+ f"distribution on {flow.date} has a negative amount "+ f"{flow.amount!r}; under the holder-perspective sign "+ "convention capital coming out of a fund is positive"+ )+ index_then = _index_level_at(+ lookup, flow.date, flow_description=f"distribution on {flow.date}"+ )+ fv_distributions += flow.amount * (index_as_of / index_then)++ nav_amount = residual_value(series)+ fv_nav = 0.0+ if nav_amount > 0.0:+ terminal_mark = _terminal_mark(series)+ assert terminal_mark is not None # residual_value > 0 implies a mark exists+ index_then = _index_level_at(+ lookup, terminal_mark.date, flow_description="terminal valuation"+ )+ fv_nav = nav_amount * (index_as_of / index_then)++ return (fv_distributions + fv_nav) / fv_contributions+++@dataclass(frozen=True)+class PMEPlusResult:+ """Outcome of a Kaplan-Schoar PME+ (Rouvinez) benchmark.++ Attributes:+ scaling_factor: The multiplier applied to every actual distribution+ so that an index-tracking portfolio -- built from the fund's+ actual, unscaled contributions and these scaled distributions --+ ends at exactly the fund's actual terminal NAV. Below 1 means the+ fund's real distributions were larger than an index-tracking+ portfolio would have needed to reach the same ending NAV (the+ fund outran the index); above 1 means the opposite.+ irr: The money-weighted return of the fund's actual contributions,+ the *scaled* distributions, and the actual terminal NAV. This+ rate is only meaningful next to the fund's own realised+ :func:`xirr` -- a lower PME+ IRR than the fund's own IRR means+ the fund beat the index; a higher one means it lagged. It is not+ comparable across two different funds.+ """++ scaling_factor: float+ irr: float+++def pme_plus(+ series: CashFlowSeries,+ index_levels: pd.Series,+ *,+ as_of: _dt.date | _dt.datetime | str | None = None,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+ guess: float = 0.1,+ rate_bounds: tuple[float, float] = DEFAULT_RATE_BOUNDS,+ grid_points: int = DEFAULT_GRID_POINTS,+ residual_tolerance: float = _DEFAULT_RESIDUAL_TOLERANCE,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> PMEPlusResult:+ """Kaplan-Schoar "PME+" (Rouvinez) -- a comparable IRR, not a multiple.++ KS-PME reports a multiple, which cannot be annualized and cannot be+ compared to the fund's own IRR. PME+ instead solves for a single scaling+ factor ``lambda`` applied to every actual distribution such that an+ index-replicating portfolio -- fed the fund's real, unscaled+ contributions and the scaled distributions -- ends up with exactly the+ fund's real terminal NAV::++ FV(contributions) = lambda * FV(distributions) + FV(NAV)+ lambda = (FV(contributions) - FV(NAV)) / FV(distributions)++ where every FV(...) grows a flow from its own date to ``as_of`` using the+ public index, the same growth :func:`ks_pme` uses (and NAV is read via+ :func:`residual_value`, so only the latest mark counts). The scaled+ distributions, unchanged contributions and unchanged terminal NAV are+ then handed to :func:`xirr` to solve a rate directly comparable to the+ fund's own realised IRR -- see :class:`PMEPlusResult`.++ Only flows matching ``contribution_kinds`` or ``distribution_kinds``+ participate, plus the terminal valuation mark; a flow of some other kind+ (an out-of-band fee, say) is invisible to this calculation exactly as it+ already is to :func:`dpi`/:func:`tvpi` unless the caller widens the kind+ set.++ Args:+ series: The fund's cash flows.+ index_levels: Public index levels. Must have an entry for every+ contribution date, every distribution date, the terminal+ valuation's date (if any), and ``as_of`` itself.+ as_of: Common date to grow every flow to. ``None`` uses+ :func:`_default_as_of`.+ days_per_year: Day basis passed to the final :func:`xirr` call.+ guess: Newton fallback starting rate passed to :func:`xirr`.+ rate_bounds: Rate window passed to :func:`xirr`.+ grid_points: Grid resolution passed to :func:`xirr`.+ residual_tolerance: Root tolerance passed to :func:`xirr`.+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ A :class:`PMEPlusResult` with the scaling factor and the comparable+ IRR.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``, or+ ``index_levels`` is not a ``pandas.Series``.+ ValueError: If ``index_levels`` lacks a needed date, if there are no+ contributions or their future value is zero, if there are no+ distributions or their future value is zero (the scaling factor+ would divide by zero), if a sign contradicts the+ holder-perspective convention, or if the resulting scaled series+ has no usable IRR (see :func:`xirr`).+ """+ _require_series(series)+ lookup = _index_levels_by_date(index_levels)+ measurement = (+ normalize_date(as_of, field_name="as_of")+ if as_of is not None+ else _default_as_of(series)+ )+ index_as_of = _index_level_at(lookup, measurement, flow_description="as_of")++ contributions = tuple(series.filter(kind=contribution_kinds))+ if not contributions:+ raise ValueError(+ "no contributions were found; PME+ is undefined with nothing "+ "paid in"+ )+ fv_contributions = 0.0+ for flow in contributions:+ if flow.amount > 0.0:+ raise ValueError(+ f"contribution on {flow.date} has a positive amount "+ f"{flow.amount!r}; under the holder-perspective sign "+ "convention capital going into a fund is negative"+ )+ index_then = _index_level_at(+ lookup, flow.date, flow_description=f"contribution on {flow.date}"+ )+ fv_contributions += (-flow.amount) * (index_as_of / index_then)+ if fv_contributions <= 0.0:+ raise ValueError(+ "contributions have zero future value at as_of; PME+ is "+ "undefined with nothing paid in"+ )++ distributions = tuple(series.filter(kind=distribution_kinds))+ if not distributions:+ raise ValueError(+ "no distributions were found; PME+ solves a scaling factor for "+ "the distributions, and there is nothing to scale"+ )+ fv_distributions = 0.0+ for flow in distributions:+ if flow.amount < 0.0:+ raise ValueError(+ f"distribution on {flow.date} has a negative amount "+ f"{flow.amount!r}; under the holder-perspective sign "+ "convention capital coming out of a fund is positive"+ )+ index_then = _index_level_at(+ lookup, flow.date, flow_description=f"distribution on {flow.date}"+ )+ fv_distributions += flow.amount * (index_as_of / index_then)+ if fv_distributions <= 0.0:+ raise ValueError(+ "distributions have zero future value at as_of; PME+ cannot "+ "solve a scaling factor by dividing by zero"+ )++ nav_amount = residual_value(series)+ terminal_mark = _terminal_mark(series)+ fv_nav = 0.0+ if nav_amount > 0.0:+ assert terminal_mark is not None+ index_then = _index_level_at(+ lookup, terminal_mark.date, flow_description="terminal valuation"+ )+ fv_nav = nav_amount * (index_as_of / index_then)++ scaling_factor = (fv_contributions - fv_nav) / fv_distributions++ scaled_flows: list[CashFlow] = [+ CashFlow(+ date=flow.date,+ amount=flow.amount,+ kind=flow.kind,+ currency=flow.currency,+ metadata=flow.metadata,+ )+ for flow in contributions+ ]+ scaled_flows.extend(+ CashFlow(+ date=flow.date,+ amount=flow.amount * scaling_factor,+ kind=flow.kind,+ currency=flow.currency,+ metadata=flow.metadata,+ )+ for flow in distributions+ )+ if terminal_mark is not None:+ scaled_flows.append(terminal_mark)+ scaled_series = CashFlowSeries(+ tuple(scaled_flows), currency=series.currency, pre_translated=series.pre_translated+ )+ irr = xirr(+ scaled_series,+ days_per_year=days_per_year,+ guess=guess,+ rate_bounds=rate_bounds,+ grid_points=grid_points,+ residual_tolerance=residual_tolerance,+ )+ return PMEPlusResult(scaling_factor=scaling_factor, irr=irr)+++def direct_alpha(+ series: CashFlowSeries,+ index_levels: pd.Series,+ *,+ valuations: str = DEFAULT_VALUATION_POLICY,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+ guess: float = 0.1,+ rate_bounds: tuple[float, float] = DEFAULT_RATE_BOUNDS,+ grid_points: int = DEFAULT_GRID_POINTS,+ residual_tolerance: float = _DEFAULT_RESIDUAL_TOLERANCE,+) -> float:+ """Direct Alpha -- an annualized excess return over a public index.++ Every flow, of every kind (contribution, distribution or valuation+ mark), is deflated by the public index level on its own date and left at+ its own date::++ CF'_i = CF_i / I(t_i)++ and :func:`xirr` is then run on the deflated series unchanged, valuation+ policy and all. Direct Alpha is the rate that solves this.++ Why this is "alpha" and not just a rescaled IRR: write the index level as+ ``I(t) = I(t0) * (1+g)**years`` for a constant realised index CAGR ``g``+ between two flow dates. Substituting into the NPV equation the deflated+ series satisfies shows the deflator and the discount rate combine+ multiplicatively -- solving ``sum CF_i / I(t_i) / (1+alpha)**t_i == 0`` is+ algebraically the same as solving ``sum CF_i / (1+alpha)**t_i / (1+g)**t_i+ == 0``, i.e. ``sum CF_i / ((1+alpha)(1+g))**t_i == 0``. The rate that+ zeroes *that* equation is, by definition, the fund's own plain+ :func:`xirr`, call it ``rho``. So ``(1+alpha)(1+g) = (1+rho)``, i.e.+ ``alpha = (1+rho)/(1+g) - 1`` -- the geometric excess of the fund's own+ realised IRR over the index's realised CAGR. Using actual index *levels*+ rather than one flat CAGR is what lets this hold even when the index's+ growth rate varies over the fund's life, and it is also why, unlike+ :func:`ks_pme` and :func:`pme_plus`, this function takes no ``as_of`` --+ the reference date cancels out of the equation algebraically, so the+ result cannot depend on one.++ Positive means the fund beat the index by that many annualized points;+ negative means it lagged. Unlike PME+'s IRR, this number needs no+ companion fund IRR to be interpreted -- it already is the excess.++ Args:+ series: The fund's cash flows.+ index_levels: Public index levels. Must have an entry for every flow+ in ``series``, including every intermediate valuation mark --+ not only the one ``valuations`` ultimately keeps, because the+ deflation happens before the policy is applied.+ valuations: One of :data:`VALUATION_POLICIES`, passed through to the+ final :func:`xirr` call unchanged.+ days_per_year: Day basis passed to :func:`xirr`.+ guess: Newton fallback starting rate passed to :func:`xirr`.+ rate_bounds: Rate window passed to :func:`xirr`.+ grid_points: Grid resolution passed to :func:`xirr`.+ residual_tolerance: Root tolerance passed to :func:`xirr`.++ Returns:+ The annualized excess return as a decimal (``0.05`` is 5 points of+ annual alpha over the index).++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``, or+ ``index_levels`` is not a ``pandas.Series``.+ ValueError: If ``index_levels`` lacks an entry for any flow's date,+ or if the deflated series has no usable IRR -- see :func:`xirr`+ for the full list (no sign change, too few flows, an unknown+ policy, and so on).+ """+ _require_series(series)+ lookup = _index_levels_by_date(index_levels)+ scaled_flows = []+ for flow in series:+ index_then = _index_level_at(+ lookup, flow.date, flow_description=f"{flow.kind} on {flow.date}"+ )+ scaled_flows.append(+ CashFlow(+ date=flow.date,+ amount=flow.amount / index_then,+ kind=flow.kind,+ currency=flow.currency,+ metadata=flow.metadata,+ )+ )+ scaled_series = CashFlowSeries(+ tuple(scaled_flows), currency=series.currency, pre_translated=series.pre_translated+ )+ return xirr(+ scaled_series,+ valuations=valuations,+ days_per_year=days_per_year,+ guess=guess,+ rate_bounds=rate_bounds,+ grid_points=grid_points,+ residual_tolerance=residual_tolerance,+ )+++# ---------------------------------------------------------------------------+# American (deal-by-deal) waterfall + GP clawback+# ---------------------------------------------------------------------------+#+# european_waterfall() above is whole-of-fund: every dollar of contributed+# capital and the whole preferred return must be paid back before the GP sees+# any carry. That structurally protects LPs from the failure mode below,+# which is exactly why a European fund essentially never triggers a+# clawback -- see gp_clawback()'s docstring for the one-line reason it is+# still not literally impossible.+#+# An American (deal-by-deal) waterfall pays carry per investment as it exits,+# without waiting for the rest of the fund. That is what makes "distribute+# early, lose money later" representable: the GP can collect carry on a+# profitable exit in year 2 while a different investment in the same fund+# loses money in year 5, and there is no mechanism inside the deal-by-deal+# structure itself that hands that carry back. A clawback provision is the+# LPA's fix -- a true-up at fund termination that compares carry actually+# received against what a whole-of-fund calculation says the GP earned once+# every deal is counted, and requires the GP to return the difference.+++def _validate_deals(deals: Mapping[str, CashFlowSeries]) -> Mapping[str, CashFlowSeries]:+ """Check a deal-by-deal input before any arithmetic touches it.++ Args:+ deals: Deal-id -> that deal's own cash flows.++ Returns:+ The same mapping, unchanged.++ Raises:+ TypeError: If ``deals`` is not a mapping, or a value is not a+ ``CashFlowSeries``.+ ValueError: If ``deals`` is empty, or the deals span more than one+ currency.+ """+ if not isinstance(deals, Mapping):+ raise TypeError(+ f"deals must be a mapping of deal_id -> CashFlowSeries, got "+ f"{type(deals).__name__}"+ )+ if not deals:+ raise ValueError(+ "deals is empty; a deal-by-deal waterfall needs at least one deal"+ )+ currencies: set[str] = set()+ for deal_id, series in deals.items():+ _require_series(series, name=f"deals[{deal_id!r}]")+ if series.currency is not None:+ currencies.add(series.currency)+ if len(currencies) > 1:+ raise ValueError(+ f"deals span multiple currencies ({', '.join(sorted(currencies))}); "+ "convert them to one reporting currency before pooling -- the same "+ "discipline CashFlowSeries itself enforces within a single series"+ )+ return deals+++def _pool_deals(deals: Mapping[str, CashFlowSeries]) -> CashFlowSeries:+ """Combine every deal's flows into one whole-of-fund series.++ Args:+ deals: Deal-id -> that deal's cash flows. Assumed already validated+ by :func:`_validate_deals` (non-empty, one currency).++ Returns:+ A single ``CashFlowSeries`` holding every flow from every deal.+ """+ all_flows: list[CashFlow] = []+ for series in deals.values():+ all_flows.extend(series)+ currency = next(iter(deals.values())).currency+ return CashFlowSeries(tuple(all_flows), currency=currency)+++@dataclass(frozen=True)+class AmericanWaterfallResult:+ """Deal-by-deal waterfall outcome, aggregated across every investment.++ Attributes:+ deals: Each deal's own :class:`WaterfallResult`, keyed by the same+ deal id the caller supplied to :func:`american_waterfall`.+ lp_total: Sum of every deal's ``lp_total``.+ gp_total: Sum of every deal's ``gp_total`` -- the GP's total carry+ actually paid out across every deal, i.e. carry *received*.+ distributable: Sum of every deal's ``distributable`` amount.+ """++ deals: Mapping[str, WaterfallResult]+ lp_total: float+ gp_total: float+ distributable: float++ def __post_init__(self) -> None:+ """Check that the per-deal results sum to the reported totals.++ Raises:+ ValueError: If ``deals`` is empty, or a reported total does not+ match the sum of the per-deal results.+ """+ if not self.deals:+ raise ValueError(+ "an American waterfall result must hold at least one deal"+ )+ checks = (+ ("lp_total", sum(r.lp_total for r in self.deals.values()), self.lp_total),+ ("gp_total", sum(r.gp_total for r in self.deals.values()), self.gp_total),+ (+ "distributable",+ sum(r.distributable for r in self.deals.values()),+ self.distributable,+ ),+ )+ for label, computed, expected in checks:+ if not math.isclose(+ computed, expected, rel_tol=_ALLOCATION_TOLERANCE, abs_tol=_ALLOCATION_TOLERANCE+ ):+ raise ValueError(+ f"American waterfall result does not reconcile on {label}: "+ f"deals give {computed!r}, expected {expected!r}"+ )+++def american_waterfall(+ deals: Mapping[str, CashFlowSeries],+ *,+ preferred_rate: float,+ carry_rate: float,+ catch_up_rate: float = 1.0,+ as_of: Mapping[str, _dt.date | _dt.datetime | str] | None = None,+ compounding: str = DEFAULT_PREFERRED_COMPOUNDING,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+ include_residual: bool = False,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> AmericanWaterfallResult:+ """Run a deal-by-deal (American) waterfall.++ Each deal is its own miniature fund: its own contributed capital, its own+ preferred return accrued from its own contribution dates, and its own+ return-of-capital / preferred / catch-up / carry-split tiers, computed by+ calling :func:`european_waterfall` once per deal with that deal's own+ series. Nothing about the tier mechanics is reimplemented here -- a+ single-deal call to this function reproduces :func:`european_waterfall`+ on that same series exactly. What makes the result "American" is that+ carry crystallizes independently on each deal, at that deal's own exit,+ with no visibility into how the fund's other deals are doing -- which is+ also exactly the property that makes a clawback representable at all; see+ :func:`gp_clawback`.++ The GP catch-up tier is unchanged from :func:`waterfall_split`: it lets+ the GP catch up *to* its target carry percentage on that deal's own+ profit, not an extra bonus on top of it.++ Args:+ deals: Deal-id -> that deal's own cash flows. Every deal must share+ one currency.+ preferred_rate: Annual hurdle rate as a decimal, applied identically+ to every deal.+ carry_rate: GP share of profit above the hurdle, in ``[0, 1)``,+ applied identically to every deal.+ catch_up_rate: GP share of each catch-up dollar; ``0.0`` for no+ catch-up.+ as_of: Per-deal override for the preferred-return measurement date,+ as a mapping from deal id to a date. A deal absent from the+ mapping (or ``as_of=None`` entirely) uses that deal's own latest+ flow date -- the natural exit-date accrual for a deal that has+ actually closed.+ compounding: One of :data:`PREFERRED_COMPOUNDING`, applied to every+ deal.+ days_per_year: Day basis for the preferred accrual.+ include_residual: Passed through to each deal's+ :func:`european_waterfall` call; see that function.+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ An :class:`AmericanWaterfallResult` aggregating every deal.++ Raises:+ TypeError: If ``deals`` is not a mapping, or a value is not a+ ``CashFlowSeries``.+ ValueError: If ``deals`` is empty, spans more than one currency, or+ any deal raises the errors :func:`european_waterfall` already+ documents (bad rate, contribution after ``as_of``, sign-+ convention violation, and so on).+ """+ deals = _validate_deals(deals)+ per_deal: dict[str, WaterfallResult] = {}+ for deal_id, series in deals.items():+ deal_as_of = as_of.get(deal_id) if isinstance(as_of, Mapping) else None+ per_deal[deal_id] = european_waterfall(+ series,+ preferred_rate=preferred_rate,+ carry_rate=carry_rate,+ catch_up_rate=catch_up_rate,+ as_of=deal_as_of,+ compounding=compounding,+ days_per_year=days_per_year,+ include_residual=include_residual,+ contribution_kinds=contribution_kinds,+ distribution_kinds=distribution_kinds,+ )+ return AmericanWaterfallResult(+ deals=MappingProxyType(dict(per_deal)),+ lp_total=sum(result.lp_total for result in per_deal.values()),+ gp_total=sum(result.gp_total for result in per_deal.values()),+ distributable=sum(result.distributable for result in per_deal.values()),+ )+++def _pooled_entitlement(+ deals: Mapping[str, CashFlowSeries],+ *,+ preferred_rate: float,+ carry_rate: float,+ catch_up_rate: float,+ as_of: _dt.date | _dt.datetime | str | None,+ compounding: str,+ days_per_year: float,+ include_residual: bool,+ contribution_kinds: Iterable[str],+ distribution_kinds: Iterable[str],+) -> WaterfallResult:+ """The whole-of-fund (European) split every deal's cash would have earned.++ This is the entitlement side of a clawback test: pool every deal's+ contributions and distributions, accrue one preferred return over the+ pooled contribution schedule, and run one :func:`waterfall_split`.++ Residual value is summed *per deal* -- via :func:`residual_value` called+ once on each deal's own series -- rather than read off the pooled series+ directly. :func:`residual_value` keeps only the single latest valuation+ mark in a series, which is correct for one fund's own evolving NAV but+ wrong for a pool of several deals' independent marks: reading it off the+ pooled series would keep whichever deal happens to carry the latest-dated+ mark and silently drop every other still-open deal's NAV.++ Args:+ deals: Deal-id -> that deal's cash flows. Assumed already validated.+ preferred_rate: Annual hurdle rate as a decimal.+ carry_rate: GP share of profit above the hurdle.+ catch_up_rate: GP share of each catch-up dollar.+ as_of: Measurement date for the pooled preferred accrual. ``None``+ uses the latest date anywhere across every deal.+ compounding: One of :data:`PREFERRED_COMPOUNDING`.+ days_per_year: Day basis for the preferred accrual.+ include_residual: Whether to add each still-open deal's own residual+ value to the pooled distributable amount.+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ The pooled :class:`WaterfallResult`.+ """+ pooled = _pool_deals(deals)+ contributed = paid_in_capital(pooled, contribution_kinds=contribution_kinds)+ distributed = distributed_capital(pooled, distribution_kinds=distribution_kinds)+ residual = (+ sum(residual_value(series) for series in deals.values())+ if include_residual+ else 0.0+ )+ preferred = preferred_return_amount(+ pooled,+ rate=preferred_rate,+ as_of=as_of,+ compounding=compounding,+ days_per_year=days_per_year,+ contribution_kinds=contribution_kinds,+ )+ return waterfall_split(+ distributed + residual,+ contributed,+ preferred,+ carry_rate=carry_rate,+ catch_up_rate=catch_up_rate,+ )+++@dataclass(frozen=True)+class ClawbackResult:+ """Outcome of a GP clawback test at fund termination.++ Attributes:+ carry_received: Carry the GP actually collected -- the sum of every+ deal's own realised carry under the deal-by-deal structure+ (:func:`american_waterfall`'s ``gp_total``, with+ ``include_residual=False`` always, because unrealised NAV is not+ carry anyone has been paid).+ carry_entitled: Carry the GP is entitled to once every deal's cash+ flows are pooled and run through one whole-of-fund waterfall --+ the number a European structure would actually have paid; see+ :func:`_pooled_entitlement`.+ clawback_amount: ``max(0, carry_received - carry_entitled)``, scaled+ down for tax already paid when ``tax_adjusted`` is True.+ tax_adjusted: Whether ``clawback_amount`` reflects a net-of-tax cap.+ gp_tax_rate: The rate used when ``tax_adjusted`` is True, else+ ``None``.+ """++ carry_received: float+ carry_entitled: float+ clawback_amount: float+ tax_adjusted: bool+ gp_tax_rate: float | None++ def __post_init__(self) -> None:+ """Check the reported figures are internally consistent.++ Raises:+ ValueError: If any dollar figure is negative, or if+ ``tax_adjusted`` and ``gp_tax_rate`` disagree about whether a+ tax adjustment was applied.+ """+ for label, value in (+ ("carry_received", self.carry_received),+ ("carry_entitled", self.carry_entitled),+ ("clawback_amount", self.clawback_amount),+ ):+ if value < -_ALLOCATION_TOLERANCE:+ raise ValueError(f"{label} cannot be negative, got {value!r}")+ if self.tax_adjusted and self.gp_tax_rate is None:+ raise ValueError("tax_adjusted is True but gp_tax_rate is None")+ if not self.tax_adjusted and self.gp_tax_rate is not None:+ raise ValueError(+ f"gp_tax_rate={self.gp_tax_rate!r} is set but tax_adjusted is False"+ )+++def gp_clawback(+ deals: Mapping[str, CashFlowSeries],+ *,+ preferred_rate: float,+ carry_rate: float,+ catch_up_rate: float = 1.0,+ termination_date: _dt.date | _dt.datetime | str | None = None,+ compounding: str = DEFAULT_PREFERRED_COMPOUNDING,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+ include_unrealized_in_entitlement: bool = False,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+ gp_tax_rate: float | None = None,+) -> ClawbackResult:+ """Test whether a deal-by-deal GP owes money back at fund termination.++ Compares carry actually received (summed deal by deal, each deal's carry+ crystallized at that deal's own exit -- see :func:`american_waterfall`)+ against carry the GP is entitled to once every deal is pooled into one+ whole-of-fund waterfall (see :func:`_pooled_entitlement`). The GP owes+ back the positive difference, if any.++ This is a genuinely different number from zero specifically *because*+ the two sides are computed two different ways: "received" is a sum of+ independent per-deal waterfalls, each blind to how the fund's other+ deals perform, while "entitled" is one waterfall over the pooled total.+ A European (whole-of-fund) structure never has this gap in the first+ place, because there carry is only ever paid once, off the same pooled+ totals used here as "entitled" -- so "received" and "entitled" are the+ same computation by construction and a clawback is structurally+ (near-)impossible. Running :func:`european_waterfall` once on the pooled+ series and comparing its ``gp_total`` to itself demonstrates this+ directly; see the test suite.++ Tax treatment of the clawback amount is deliberately not defaulted to a+ net-of-tax figure, even though many LPAs contractually cap the GP's+ payback obligation at what remains after the tax already paid on the+ excess carry. Computing that net figure needs the GP's actual effective+ tax rate on the carry, which this module has no way to know -- assuming+ one (a US corporate rate, a "typical" GP rate, anything) would be exactly+ the kind of invented number this codebase's evidence-first standard+ forbids. The default is therefore the gross, pre-tax clawback; passing+ ``gp_tax_rate`` opts into the net-of-tax figure the LPA actually specifies+ for this fund.++ Args:+ deals: Deal-id -> that deal's own cash flows. Every deal must share+ one currency.+ preferred_rate: Annual hurdle rate as a decimal, applied identically+ to every deal and to the pooled entitlement calculation.+ carry_rate: GP share of profit above the hurdle, in ``[0, 1)``.+ catch_up_rate: GP share of each catch-up dollar; ``0.0`` for no+ catch-up.+ termination_date: Measurement date for the pooled entitlement's+ preferred accrual. ``None`` uses the latest date anywhere across+ every deal -- the natural "fund winds up now" default. This does+ not affect the "received" side, which always uses each deal's own+ historical exit date, because carry already paid is a fact, not a+ modelling choice.+ compounding: One of :data:`PREFERRED_COMPOUNDING`.+ days_per_year: Day basis for the preferred accrual.+ include_unrealized_in_entitlement: Whether the pooled entitlement+ calculation adds each still-open deal's current NAV to the+ distributable amount -- an "if the fund wound up today" stress+ test. The "received" side never includes unrealised NAV, because+ unpaid carry cannot have been received.+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.+ gp_tax_rate: If given, scales ``clawback_amount`` down to the+ net-of-tax figure by multiplying the gross clawback by+ ``(1 - gp_tax_rate)``. Must be in ``[0, 1)``. ``None`` (the+ default) reports the gross, pre-tax clawback -- see above for why+ that is the default rather than an assumed tax rate.++ Returns:+ A :class:`ClawbackResult`.++ Raises:+ TypeError: If ``deals`` is not a mapping, or a value is not a+ ``CashFlowSeries``.+ ValueError: If ``deals`` is empty or spans more than one currency, if+ ``gp_tax_rate`` is outside ``[0, 1)``, or if a deal raises any+ error :func:`european_waterfall` already documents.+ """+ deals = _validate_deals(deals)++ received = american_waterfall(+ deals,+ preferred_rate=preferred_rate,+ carry_rate=carry_rate,+ catch_up_rate=catch_up_rate,+ as_of=None,+ compounding=compounding,+ days_per_year=days_per_year,+ include_residual=False,+ contribution_kinds=contribution_kinds,+ distribution_kinds=distribution_kinds,+ )+ carry_received = received.gp_total++ entitled = _pooled_entitlement(+ deals,+ preferred_rate=preferred_rate,+ carry_rate=carry_rate,+ catch_up_rate=catch_up_rate,+ as_of=termination_date,+ compounding=compounding,+ days_per_year=days_per_year,+ include_residual=include_unrealized_in_entitlement,+ contribution_kinds=contribution_kinds,+ distribution_kinds=distribution_kinds,+ )+ carry_entitled = entitled.gp_total++ gross_clawback = max(0.0, carry_received - carry_entitled)+ if gp_tax_rate is None:+ return ClawbackResult(+ carry_received=carry_received,+ carry_entitled=carry_entitled,+ clawback_amount=gross_clawback,+ tax_adjusted=False,+ gp_tax_rate=None,+ )+ if not 0.0 <= gp_tax_rate < 1.0:+ raise ValueError(f"gp_tax_rate must be in [0, 1), got {gp_tax_rate!r}")+ return ClawbackResult(+ carry_received=carry_received,+ carry_entitled=carry_entitled,+ clawback_amount=gross_clawback * (1.0 - gp_tax_rate),+ tax_adjusted=True,+ gp_tax_rate=gp_tax_rate,+ )diff --git a/agent/src/quantlib/multipletesting.py b/agent/src/quantlib/multipletesting.pynew file mode 100644index 000000000..d76ffed16--- /dev/null+++ b/agent/src/quantlib/multipletesting.py@@ -0,0 +1,568 @@+"""Multiple-testing control: how much of a backtest's edge is search luck?++Run 462 factors over one history, keep the best Sharpe, and you have not+measured an edge -- you have measured the maximum of 462 draws. Under a null+where every factor is worthless, that maximum is comfortably positive, and it+grows with how many you tried. Reporting it without saying how many were tried+is the single most common way a research process fools itself.++This module supplies the three corrections, in increasing order of what they+demand of the caller:++``probabilistic_sharpe_ratio``+ The confidence that one strategy's true Sharpe exceeds a benchmark, given+ the sample length and the return distribution's skew and kurtosis. No trial+ count involved. This is the building block.++``deflated_sharpe_ratio``+ The same statement, but with the benchmark raised to the Sharpe you would+ expect the *best of N trials* to reach by luck alone. Needs the number of+ trials and the dispersion of their Sharpes. This is the number to publish+ beside any "best factor" claim.++``probability_of_backtest_overfitting``+ CSCV. Needs the full return matrix of every trial, not just summary+ statistics, and answers a different question: across many in-sample /+ out-of-sample splits, how often does the in-sample winner land below the+ out-of-sample median? A PBO above 0.5 means the selection procedure itself+ is anti-predictive.++``benjamini_hochberg``+ When the question is "which of these N are real" rather than "is the best+ one real", control the false discovery rate instead of deflating a maximum.++TWO CONVENTIONS THAT SILENTLY BREAK THESE FORMULAS+--------------------------------------------------+**Sharpe must be per-observation, not annualised.** Every formula here pairs the+Sharpe with the observation count ``T``. Feeding an annualised Sharpe with a+daily ``T`` inflates the statistic by roughly sqrt(252) and turns a coin flip+into a certainty. :func:`probabilistic_sharpe_ratio` cannot detect this, so it+is stated here and repeated in each docstring.++**Kurtosis is non-excess.** The Bailey-Lopez de Prado derivation uses the fourth+standardised moment, which is **3** for a Gaussian, not 0. ``scipy.stats.kurtosis``+returns the *excess* form by default and ``pandas.Series.kurt`` likewise. Passing+excess kurtosis makes the variance term ``1 - skew*SR + (gamma4-1)/4 * SR^2``+too small and the resulting confidence too high. :data:`GAUSSIAN_KURTOSIS` is+provided as the default so the common case is right without thinking about it.+"""++from __future__ import annotations++import math+from collections.abc import Sequence+from dataclasses import dataclass+from itertools import combinations++import numpy as np+import pandas as pd+from scipy.stats import norm++__all__ = [+ "DEFAULT_CSCV_SPLITS",+ "EULER_MASCHERONI",+ "GAUSSIAN_KURTOSIS",+ "MIN_OBSERVATIONS",+ "CSCVResult",+ "DeflatedSharpeResult",+ "FDRResult",+ "benjamini_hochberg",+ "deflated_sharpe_ratio",+ "expected_maximum_sharpe",+ "probabilistic_sharpe_ratio",+ "probability_of_backtest_overfitting",+ "sharpe_ratio",+]++#: Euler-Mascheroni constant, from the expected-maximum-of-N-Gaussians result.+EULER_MASCHERONI: float = 0.5772156649015329++#: Fourth standardised moment of a Gaussian. NOT zero -- see the module+#: docstring. The default wherever a kurtosis argument is optional.+GAUSSIAN_KURTOSIS: float = 3.0++#: Subsets the CSCV procedure splits the sample into. Must be even; 16 gives+#: C(16,8) = 12,870 splits, which is the published choice and runs in seconds.+DEFAULT_CSCV_SPLITS: int = 16++#: Fewest return observations for which these statistics mean anything. The+#: ``sqrt(T - 1)`` scaling is not the binding constraint -- the skew and+#: kurtosis estimates are, and they are hopeless on a short sample.+MIN_OBSERVATIONS: int = 30+++@dataclass(frozen=True)+class DeflatedSharpeResult:+ """Outcome of deflating an observed Sharpe for the number of trials.++ Attributes:+ observed_sharpe: The Sharpe that was actually observed, per-observation.+ expected_maximum_sharpe: The Sharpe the best of ``n_trials`` would be+ expected to reach under a null where none of them has any edge.+ This is the bar the observed Sharpe has to clear.+ deflated_sharpe_ratio: Probability in ``[0, 1]`` that the true Sharpe+ exceeds ``expected_maximum_sharpe``. Read it as a confidence: 0.95+ means the result survives the search correction at 95%.+ n_trials: How many strategies were searched over.+ n_observations: Length of the return sample.+ trial_sharpe_std: Dispersion of the trial Sharpes that set the bar.+ skew: Return skewness used.+ kurtosis: Non-excess kurtosis used.+ survives: True when ``deflated_sharpe_ratio`` exceeds ``confidence``.+ confidence: Threshold ``survives`` was judged at.+ """++ observed_sharpe: float+ expected_maximum_sharpe: float+ deflated_sharpe_ratio: float+ n_trials: int+ n_observations: int+ trial_sharpe_std: float+ skew: float+ kurtosis: float+ survives: bool+ confidence: float+++@dataclass(frozen=True)+class FDRResult:+ """Benjamini-Hochberg false-discovery-rate control over many hypotheses.++ Attributes:+ rejected: Boolean array, True where the null is rejected.+ adjusted_p_values: BH-adjusted p-values, monotone non-decreasing in the+ sorted order and clipped at 1.+ n_rejected: Count of rejections.+ threshold: Largest raw p-value that was rejected, or 0.0 if none were.+ fdr: The false-discovery rate the procedure controlled at.+ """++ rejected: np.ndarray+ adjusted_p_values: np.ndarray+ n_rejected: int+ threshold: float+ fdr: float+++@dataclass(frozen=True)+class CSCVResult:+ """Combinatorially-symmetric cross-validation overfitting diagnostic.++ Attributes:+ pbo: Probability of backtest overfitting -- the fraction of splits in+ which the in-sample best strategy landed below the out-of-sample+ median. Above 0.5 the selection rule is worse than picking at random.+ logits: Logit of the out-of-sample relative rank, one per split.+ n_splits: Number of in-sample/out-of-sample combinations evaluated.+ n_strategies: Strategies compared.+ n_observations: Rows actually used.+ dropped_observations: Rows trimmed from the end so the sample divides+ evenly into subsets. Reported, never silent.+ in_sample_sharpes: In-sample Sharpe of the selected strategy per split.+ out_of_sample_sharpes: Out-of-sample Sharpe of that same strategy.+ performance_degradation: Slope of out-of-sample on in-sample Sharpe+ across splits. A negative slope means better in-sample selection+ produced worse out-of-sample results, which is overfitting in its+ purest observable form.+ """++ pbo: float+ logits: np.ndarray+ n_splits: int+ n_strategies: int+ n_observations: int+ dropped_observations: int+ in_sample_sharpes: np.ndarray+ out_of_sample_sharpes: np.ndarray+ performance_degradation: float+++def sharpe_ratio(+ returns: pd.Series | np.ndarray | Sequence[float],+ risk_free: float = 0.0,+ ddof: int = 1,+) -> float:+ """Per-observation Sharpe ratio.++ Deliberately NOT annualised: every other function in this module pairs the+ Sharpe with an observation count, and mixing an annualised numerator with a+ per-period count is the error the module docstring warns about.++ Args:+ returns: Return observations.+ risk_free: Risk-free rate per observation, in the same units.+ ddof: Delta degrees of freedom for the standard deviation. Defaults to 1+ to match ``src.quantlib.timeseries.bootstrap_sharpe``; pass 0 to+ match a population-convention implementation. The two differ by+ ``sqrt(T/(T-1))``, which is immaterial at T=1000 and is not at T=30.++ Returns:+ ``mean(excess) / std(excess)``, or ``nan`` when the excess returns have+ no dispersion.++ Raises:+ ValueError: If fewer than two finite observations are supplied.+ """+ values = np.asarray(returns, dtype=float).ravel()+ values = values[np.isfinite(values)]+ if values.size < 2:+ raise ValueError(f"sharpe_ratio needs at least 2 observations, got {values.size}")+ excess = values - risk_free+ spread = float(excess.std(ddof=ddof))+ if not np.isfinite(spread) or spread <= 0.0:+ return float("nan")+ return float(excess.mean() / spread)+++def probabilistic_sharpe_ratio(+ observed_sharpe: float,+ n_observations: int,+ benchmark_sharpe: float = 0.0,+ skew: float = 0.0,+ kurtosis: float = GAUSSIAN_KURTOSIS,+) -> float:+ """Confidence that a strategy's true Sharpe exceeds a benchmark.++ ``PSR = Z[ (SR - SR*) * sqrt(T - 1) / sqrt(1 - g3*SR + (g4 - 1)/4 * SR^2) ]``++ The denominator is why this is not just a t-test: negative skew and fat+ tails both make a given Sharpe less trustworthy, and both are routine in+ strategy returns.++ Args:+ observed_sharpe: Observed Sharpe, **per-observation** and matched to+ ``n_observations``. An annualised Sharpe here inflates the result.+ n_observations: Number of return observations behind the Sharpe.+ benchmark_sharpe: Sharpe to beat, per-observation. Zero asks "is this+ better than nothing"; :func:`deflated_sharpe_ratio` raises it to the+ expected best-of-N instead.+ skew: Third standardised moment of the returns.+ kurtosis: Fourth standardised moment, **non-excess** (3 for Gaussian).++ Returns:+ Probability in ``[0, 1]``.++ Raises:+ ValueError: If ``n_observations`` is below :data:`MIN_OBSERVATIONS`, if+ ``kurtosis`` is below 1 (impossible for any distribution), or if the+ variance term is non-positive, which means the supplied moments are+ mutually inconsistent rather than merely extreme.+ """+ if n_observations < MIN_OBSERVATIONS:+ raise ValueError(+ f"need at least {MIN_OBSERVATIONS} observations, got {n_observations}"+ )+ if kurtosis < 1.0:+ raise ValueError(+ f"kurtosis must be the non-excess fourth moment (>= 1, 3 for a "+ f"Gaussian), got {kurtosis}. Excess kurtosis was probably passed."+ )+ if not np.isfinite(observed_sharpe):+ raise ValueError(f"observed_sharpe must be finite, got {observed_sharpe}")++ variance_term = (+ 1.0 - skew * observed_sharpe + (kurtosis - 1.0) / 4.0 * observed_sharpe**2+ )+ if variance_term <= 0.0:+ raise ValueError(+ f"the Sharpe variance term is {variance_term:.4f}, which is not "+ "positive; the supplied skew and kurtosis are mutually inconsistent "+ "with this Sharpe"+ )++ statistic = (+ (observed_sharpe - benchmark_sharpe)+ * math.sqrt(n_observations - 1)+ / math.sqrt(variance_term)+ )+ return float(norm.cdf(statistic))+++def expected_maximum_sharpe(n_trials: int, trial_sharpe_std: float) -> float:+ """Sharpe the best of ``n_trials`` reaches by luck alone.++ From the expected maximum of ``N`` independent Gaussians::++ E[max] ~ std * [ (1 - g) * Z^-1(1 - 1/N) + g * Z^-1(1 - 1/(N*e)) ]++ with ``g`` the Euler-Mascheroni constant. This is the bar an observed Sharpe+ has to clear before "we tried 462 factors and this was the best" says+ anything at all.++ Args:+ n_trials: Number of strategies searched over. Must be at least 2 -- with+ one trial there is no maximum to correct for and the answer is 0.+ trial_sharpe_std: Standard deviation of the Sharpes across those trials,+ per-observation.++ Returns:+ The expected maximum Sharpe under the null, per-observation. Zero when+ ``trial_sharpe_std`` is zero.++ Raises:+ ValueError: If ``n_trials`` is below 1 or ``trial_sharpe_std`` is+ negative.+ """+ if n_trials < 1:+ raise ValueError(f"n_trials must be at least 1, got {n_trials}")+ if trial_sharpe_std < 0.0:+ raise ValueError(f"trial_sharpe_std must be >= 0, got {trial_sharpe_std}")+ if n_trials == 1 or trial_sharpe_std == 0.0:+ return 0.0++ quantile_a = norm.ppf(1.0 - 1.0 / n_trials)+ quantile_b = norm.ppf(1.0 - 1.0 / (n_trials * math.e))+ return float(+ trial_sharpe_std+ * ((1.0 - EULER_MASCHERONI) * quantile_a + EULER_MASCHERONI * quantile_b)+ )+++def deflated_sharpe_ratio(+ observed_sharpe: float,+ n_trials: int,+ n_observations: int,+ trial_sharpe_std: float,+ skew: float = 0.0,+ kurtosis: float = GAUSSIAN_KURTOSIS,+ confidence: float = 0.95,+) -> DeflatedSharpeResult:+ """Deflate an observed Sharpe by the number of strategies searched.++ Args:+ observed_sharpe: Best observed Sharpe, per-observation.+ n_trials: How many strategies were searched. This is the number a+ research process usually fails to record; without it no correction+ is possible and the reported Sharpe is not interpretable.+ n_observations: Length of the return sample.+ trial_sharpe_std: Standard deviation of the Sharpes across the trials.+ skew: Third standardised moment of the winning strategy's returns.+ kurtosis: Fourth standardised moment, non-excess.+ confidence: Level at which ``survives`` is decided.++ Returns:+ A :class:`DeflatedSharpeResult`.++ Raises:+ ValueError: Propagated from :func:`expected_maximum_sharpe` and+ :func:`probabilistic_sharpe_ratio`.+ """+ if not 0.0 < confidence < 1.0:+ raise ValueError(f"confidence must be in (0, 1), got {confidence}")++ bar = expected_maximum_sharpe(n_trials, trial_sharpe_std)+ dsr = probabilistic_sharpe_ratio(+ observed_sharpe=observed_sharpe,+ n_observations=n_observations,+ benchmark_sharpe=bar,+ skew=skew,+ kurtosis=kurtosis,+ )+ return DeflatedSharpeResult(+ observed_sharpe=observed_sharpe,+ expected_maximum_sharpe=bar,+ deflated_sharpe_ratio=dsr,+ n_trials=n_trials,+ n_observations=n_observations,+ trial_sharpe_std=trial_sharpe_std,+ skew=skew,+ kurtosis=kurtosis,+ survives=dsr > confidence,+ confidence=confidence,+ )+++def benjamini_hochberg(+ p_values: Sequence[float] | np.ndarray,+ fdr: float = 0.05,+) -> FDRResult:+ """Control the false discovery rate across many simultaneous tests.++ Bonferroni controls the probability of *any* false positive and is far too+ strict when hundreds of factors are screened; BH instead bounds the expected+ *fraction* of rejections that are false, which is the quantity a research+ pipeline actually cares about.++ Args:+ p_values: Raw p-values, one per hypothesis. Must all lie in ``[0, 1]``.+ fdr: False discovery rate to control at.++ Returns:+ An :class:`FDRResult` whose ``rejected`` and ``adjusted_p_values`` are in+ the caller's original order.++ Raises:+ ValueError: If ``p_values`` is empty, holds a value outside ``[0, 1]``+ or a non-finite value, or if ``fdr`` is not in ``(0, 1)``.+ """+ if not 0.0 < fdr < 1.0:+ raise ValueError(f"fdr must be in (0, 1), got {fdr}")++ values = np.asarray(p_values, dtype=float).ravel()+ if values.size == 0:+ raise ValueError("p_values is empty")+ if not np.isfinite(values).all():+ raise ValueError("p_values holds a non-finite value")+ if ((values < 0.0) | (values > 1.0)).any():+ raise ValueError("every p-value must lie in [0, 1]")++ n = values.size+ order = np.argsort(values, kind="stable")+ sorted_p = values[order]+ ranks = np.arange(1, n + 1)++ # Step-up: the largest rank whose p-value clears its own threshold, and+ # everything below it, is rejected.+ below = sorted_p <= (ranks / n) * fdr+ if below.any():+ cutoff_rank = int(ranks[below].max())+ threshold = float(sorted_p[cutoff_rank - 1])+ else:+ cutoff_rank = 0+ threshold = 0.0++ rejected_sorted = ranks <= cutoff_rank++ # Adjusted p-values are the running minimum from the largest rank down, so+ # they cannot decrease as the raw p-value increases.+ adjusted_sorted = np.minimum.accumulate((n / ranks * sorted_p)[::-1])[::-1]+ adjusted_sorted = np.clip(adjusted_sorted, 0.0, 1.0)++ rejected = np.empty(n, dtype=bool)+ adjusted = np.empty(n, dtype=float)+ rejected[order] = rejected_sorted+ adjusted[order] = adjusted_sorted++ return FDRResult(+ rejected=rejected,+ adjusted_p_values=adjusted,+ n_rejected=int(rejected.sum()),+ threshold=threshold,+ fdr=fdr,+ )+++def probability_of_backtest_overfitting(+ performance: pd.DataFrame | np.ndarray,+ n_splits: int = DEFAULT_CSCV_SPLITS,+ ddof: int = 1,+) -> CSCVResult:+ """Combinatorially-symmetric cross-validation (CSCV) overfitting diagnostic.++ Splits the sample into ``n_splits`` contiguous subsets, then for every way of+ choosing half of them as in-sample, picks the strategy with the best+ in-sample Sharpe and records where it ranks out-of-sample. If selection+ carried information, the in-sample winner would tend to rank high+ out-of-sample; if the process is fitting noise, it lands anywhere, and below+ the median about half the time.++ Args:+ performance: Returns per strategy, rows as observations and columns as+ strategies. A DataFrame's column labels are preserved only for the+ caller's convenience; this function returns no per-strategy output.+ n_splits: Number of subsets. Must be even and at least 4; the number of+ combinations is ``C(n_splits, n_splits/2)``, so 16 gives 12,870.+ ddof: Delta degrees of freedom for the Sharpe standard deviation,+ forwarded to :func:`sharpe_ratio`.++ Returns:+ A :class:`CSCVResult`.++ Raises:+ ValueError: If ``n_splits`` is odd or below 4, if fewer than 2+ strategies are supplied (a rank needs competitors), if the sample+ cannot give each subset at least 2 rows, or if every strategy has+ zero variance so no Sharpe is defined.+ """+ if n_splits < 4 or n_splits % 2 != 0:+ raise ValueError(f"n_splits must be an even number >= 4, got {n_splits}")++ frame = pd.DataFrame(performance)+ matrix = frame.to_numpy(dtype=float)+ if matrix.ndim != 2:+ raise ValueError(f"performance must be 2-D, got shape {matrix.shape}")++ n_rows, n_strategies = matrix.shape+ if n_strategies < 2:+ raise ValueError(+ f"CSCV ranks strategies against each other and needs at least 2, "+ f"got {n_strategies}"+ )++ subset_size = n_rows // n_splits+ if subset_size < 2:+ raise ValueError(+ f"{n_rows} rows split {n_splits} ways gives {subset_size} row(s) per "+ "subset; each subset needs at least 2 for a Sharpe"+ )++ used_rows = subset_size * n_splits+ dropped = n_rows - used_rows+ trimmed = matrix[:used_rows]+ subsets = [+ trimmed[i * subset_size : (i + 1) * subset_size] for i in range(n_splits)+ ]++ logits: list[float] = []+ in_sample_sharpes: list[float] = []+ out_sample_sharpes: list[float] = []+ all_indices = set(range(n_splits))++ for chosen in combinations(range(n_splits), n_splits // 2):+ rest = sorted(all_indices - set(chosen))+ in_sample = np.vstack([subsets[i] for i in chosen])+ out_sample = np.vstack([subsets[i] for i in rest])++ in_scores = np.array(+ [sharpe_ratio(in_sample[:, j], ddof=ddof) for j in range(n_strategies)]+ )+ if not np.isfinite(in_scores).any():+ continue+ best = int(np.nanargmax(np.where(np.isfinite(in_scores), in_scores, -np.inf)))++ out_scores = np.array(+ [sharpe_ratio(out_sample[:, j], ddof=ddof) for j in range(n_strategies)]+ )+ finite_out = np.isfinite(out_scores)+ if not finite_out[best] or finite_out.sum() < 2:+ continue++ # Relative rank of the selected strategy among all strategies OOS, on+ # (0, 1). Ties are resolved by average rank so a plateau does not push+ # the logit to an endpoint.+ ranked = pd.Series(np.where(finite_out, out_scores, np.nan)).rank(+ method="average"+ )+ omega = float(ranked.iloc[best] / (finite_out.sum() + 1))+ omega = min(max(omega, 1e-12), 1.0 - 1e-12)++ logits.append(math.log(omega / (1.0 - omega)))+ in_sample_sharpes.append(float(in_scores[best]))+ out_sample_sharpes.append(float(out_scores[best]))++ if not logits:+ raise ValueError(+ "no split produced a usable Sharpe; every strategy may have zero "+ "variance within the subsets"+ )++ logit_array = np.array(logits)+ in_array = np.array(in_sample_sharpes)+ out_array = np.array(out_sample_sharpes)++ if in_array.size >= 2 and float(in_array.std()) > 0:+ degradation = float(np.polyfit(in_array, out_array, 1)[0])+ else:+ degradation = float("nan")++ return CSCVResult(+ pbo=float((logit_array <= 0).mean()),+ logits=logit_array,+ n_splits=len(logits),+ n_strategies=n_strategies,+ n_observations=used_rows,+ dropped_observations=dropped,+ in_sample_sharpes=in_array,+ out_of_sample_sharpes=out_array,+ performance_degradation=degradation,+ )diff --git a/agent/src/quantlib/timeseries.py b/agent/src/quantlib/timeseries.pyindex 441a2901a..822265ecd 100644--- a/agent/src/quantlib/timeseries.py+++ b/agent/src/quantlib/timeseries.py@@ -46,6 +46,7 @@ __all__ = ["compute_half_life","granger_test","fit_garch",+ "fit_markov_regime","heteroscedasticity_test","autocorrelation_test","vif_test",@@ -383,6 +384,137 @@ def fit_garch(returns: pd.Series, horizon: int = 5) -> dict:}+def fit_markov_regime(+ returns: pd.Series,+ n_regimes: int = 2,+ switching_variance: bool = True,+) -> dict:+ """Fit a Markov regime-switching model and label the current regime.++ A GARCH model says how volatile tomorrow is. This says *which state the+ market is in* and how likely it is to stay there, which is the question a+ regime section of a risk report is actually asking. The states are latent:+ they are inferred from the return series, never labelled by hand.++ Two implementation choices matter and neither is cosmetic.++ **Regimes are relabelled by volatility, ascending.** The EM fit returns+ states in an arbitrary order, so the same data can come back as "regime 0 is+ calm" on one run and "regime 0 is turbulent" on the next. That is the+ classic label-switching problem, and left alone it makes every downstream+ number non-reproducible. Here regime 0 is always the calmest and the last is+ always the most turbulent, with the transition matrix and the smoothed+ probabilities permuted to match.++ **The transition matrix is returned row-stochastic**: ``transition[i][j]`` is+ ``P(regime j tomorrow | regime i today)`` and every row sums to 1.+ ``statsmodels`` returns the transpose of this, and reading it the wrong way+ round silently swaps the two regimes' persistence.++ Args:+ returns: Return series as *fractions* (0.01 = 1%). Scaled to percent+ internally for optimiser stability and converted back on the way+ out, so every reported mean and volatility is a fraction again.+ n_regimes: Number of latent states, at least 2. Three is occasionally+ defensible (calm / normal / crisis); beyond that the states stop+ being interpretable and the fit stops being stable.+ switching_variance: Let volatility differ across regimes. Leaving this+ False fits regimes that differ only in mean return, which for asset+ returns is nearly always the wrong model -- regimes in markets are a+ volatility phenomenon first.++ Returns:+ Dict with keys ``n_regimes`` (int), ``regime_means`` and ``regime_vols``+ (numpy arrays, ascending volatility, daily fractions),+ ``transition_matrix`` (2-D numpy array, row-stochastic),+ ``expected_durations`` (numpy array, ``1 / (1 - p_ii)`` in periods),+ ``smoothed_probabilities`` (DataFrame on the input index, one column per+ regime), ``current_regime`` (int) and ``current_regime_probability``+ (float) for the last observation, ``converged`` (bool), and ``llf``,+ ``aic``, ``bic`` (float).++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ ValueError: If ``n_regimes`` is below 2, or fewer than 50 finite+ observations survive -- an EM fit on a shorter series produces+ regimes that are numerically fine and substantively meaningless.+ """+ markov = _require(+ "statsmodels.tsa.regime_switching.markov_regression",+ "statsmodels",+ "fit_markov_regime",+ )+ if n_regimes < 2:+ raise ValueError(f"n_regimes must be at least 2, got {n_regimes}")++ series = pd.Series(returns, dtype=float).dropna()+ if series.size < 50:+ raise ValueError(+ f"fit_markov_regime needs at least 50 finite observations, got {series.size}"+ )++ # Passed as a Series, not an array: statsmodels only names the fitted+ # parameters (``const[k]``, ``sigma2[k]``) when the input is pandas, and+ # positional unpacking of that vector would silently break if the package+ # ever reorders it.+ model = markov.MarkovRegression(+ series * 100,+ k_regimes=n_regimes,+ trend="c",+ switching_variance=switching_variance,+ )+ with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):+ result = model.fit()++ means = np.array(+ [float(result.params[f"const[{k}]"]) / 100 for k in range(n_regimes)]+ )+ if switching_variance:+ variances = np.array([float(result.params[f"sigma2[{k}]"]) for k in range(n_regimes)])+ else:+ variances = np.full(n_regimes, float(result.params["sigma2"]))+ vols = np.sqrt(np.maximum(variances, 0.0)) / 100++ # Canonical order: calmest regime first. Everything below is permuted to it.+ order = np.argsort(vols, kind="stable")++ # statsmodels gives P(to i | from j); transpose to the conventional+ # P(from i | to j) reading, then permute rows and columns together.+ raw_transition = np.asarray(result.regime_transition, dtype=float)+ if raw_transition.ndim == 3:+ raw_transition = raw_transition[:, :, 0]+ transition = raw_transition.T[np.ix_(order, order)]++ diagonal = np.clip(np.diag(transition), None, 1.0 - 1e-12)+ expected_durations = 1.0 / (1.0 - diagonal)++ smoothed = np.asarray(result.smoothed_marginal_probabilities, dtype=float)+ if smoothed.ndim == 1:+ smoothed = smoothed.reshape(-1, 1)+ smoothed = smoothed[:, order]+ smoothed_frame = pd.DataFrame(+ smoothed, index=series.index, columns=[f"regime_{k}" for k in range(n_regimes)]+ )++ last_row = smoothed[-1]+ current_regime = int(np.argmax(last_row))++ return {+ "n_regimes": n_regimes,+ "regime_means": means[order],+ "regime_vols": vols[order],+ "transition_matrix": transition,+ "expected_durations": expected_durations,+ "smoothed_probabilities": smoothed_frame,+ "current_regime": current_regime,+ "current_regime_probability": float(last_row[current_regime]),+ "converged": bool(result.mle_retvals.get("converged", False)),+ "llf": float(result.llf),+ "aic": float(result.aic),+ "bic": float(result.bic),+ }++def heteroscedasticity_test(model_result: Any, significance: float = 0.05) -> dict:"""Test regression residuals for heteroskedasticity (White and Breusch-Pagan).diff --git a/agent/src/quantlib/valuation/__init__.py b/agent/src/quantlib/valuation/__init__.pynew file mode 100644index 000000000..fbecaaeac--- /dev/null+++ b/agent/src/quantlib/valuation/__init__.py@@ -0,0 +1,24 @@+"""Valuation models: DCF, comparable companies, three-statement projection.++The audit that motivated this package found no executable DCF, WACC, terminal+value or comps engine anywhere in the repository -- only markdown describing+them. These modules are the executable form.++Import submodules directly, so a missing optional dependency in one cannot+break the others::++ from src.quantlib.valuation.dcf import run_dcf+ from src.quantlib.valuation.comps import run_comps++Submodules:+ contracts Shared input discipline -- missing inputs stop the model+ dcf FCFF bridge, WACC build, dual terminal value, sensitivity grid+ comps Peer set, calendarisation, EV bridge, multiple matrix+ threestatement Linked P&L / cash flow / balance sheet with a hard balance check++The one rule every module here obeys is in :mod:`contracts`: a missing input+makes a model NOT RUNNABLE and is never silently defaulted. A valuation built+on quietly-chosen constants is indistinguishable, downstream, from one built on+filed statements -- and that is exactly the failure this package exists to make+impossible.+"""diff --git a/agent/src/quantlib/valuation/artifact.py b/agent/src/quantlib/valuation/artifact.pynew file mode 100644index 000000000..772a5d8e2--- /dev/null+++ b/agent/src/quantlib/valuation/artifact.py@@ -0,0 +1,1615 @@+"""Versioned model artifacts for DCF / comps / three-statement, plus export.++:mod:`dcf`, :mod:`comps` and :mod:`threestatement` each answer "what is this+worth" for one run. None of them answer three questions every real valuation+practice needs answered on top of that: *which* inputs produced this number,+*can I tell if someone changed one*, and *can I hand this to someone who was+not in the room*. This module exists only for those three questions -- it does+not recompute anything the three model modules already compute, and it never+imports anything from them that isn't already public (:class:`DCFResult`,+:class:`CompsResult`, :class:`ThreeStatementProjection` and their nested+dataclasses, plus :class:`~.contracts.Assumption`).++THE ARTIFACT+------------+:func:`build_dcf_artifact`, :func:`build_comps_artifact` and+:func:`build_three_statement_artifact` each wrap one completed model run (the+raw inputs the caller fed the model, plus the call-level knobs such as+``discounting_convention`` that also determine the output, plus the model's+own result object) into one :class:`ModelArtifact`. Four things happen on the+way in:++1. **Input hash.** Every input -- the raw mapping/dataclasses the caller+ passed AND the call-level configuration knobs, because a knob like+ ``discounting_convention`` changes the output just as much as a number in+ ``inputs`` does -- is walked into a flat set of ``(dotted.path, value)``+ leaves (:func:`_flatten`), each leaf's number canonicalised+ (:func:`_normalize_number`: fixed 12-significant-digit scientific+ notation, ``-0.0`` collapsed to ``0.0``, ``int``/``float`` treated as the+ same economic value), then hashed with ``sha256`` over a+ ``sort_keys=True`` JSON encoding so the result depends on the *content* of+ the inputs and nothing about how they were typed in (dict key order,+ ``int`` vs ``float``, ``-0.0`` vs ``0.0``). Change one number anywhere in+ the input tree and the hash changes; two calls with the same inputs in a+ different key order produce the identical hash. See :func:`compute_input_hash`.+2. **Model version.** :func:`_module_version` hashes the producing module's+ own source file together with :mod:`.contracts`'s (every model in this+ package depends on ``contracts.py``'s input discipline, so a change there+ is a change to what produced the artifact even if the model file's own+ text is untouched). This is content-addressed on purpose: there is no+ ``__version__`` anywhere in :mod:`src.quantlib` to defer to (checked before+ writing this module), and a hand-maintained version string goes stale the+ first time someone edits the model and forgets to bump it. A content hash+ cannot go stale.+3. **Assumptions.** The same flatten pass that builds the input hash also+ walks the *result* object (not the raw inputs -- see+ :func:`build_dcf_artifact`'s docstring for why) collecting every+ :class:`~.contracts.Assumption` it finds, with the dotted path it was found+ at. Only :mod:`dcf` requires callers to pass :class:`Assumption` objects+ (``terminal_growth``, ``exit_multiple``); :mod:`comps` and+ :mod:`threestatement` take bare numbers for everything and therefore+ produce artifacts with an empty ``assumptions`` tuple. That is not a bug in+ this module -- it is an accurate report of what those two models do and do+ not ask the caller to justify, and every export below says so explicitly+ rather than leaving the section blank.+4. **Timestamp, supplied not invented.** ``generated_at`` is a required+ keyword argument of ``datetime`` type with no default anywhere in this+ file. This module never calls ``datetime.now()`` or ``time.time()`` --+ omitting the argument is a ``TypeError`` from Python's own argument+ binding, and passing a naive (non-timezone-aware) datetime is a+ ``ValueError`` from :func:`_require_generated_at`. A caller who wants a+ real-time artifact passes ``datetime.now(timezone.utc)`` themselves; this+ module has no opinion on "now" and cannot silently manufacture one, which+ is exactly what makes ``input_hash`` and every export below reproducible+ in a test.++DIFFING+-------+:func:`diff_artifacts` compares two artifacts of the same ``model_name`` by+set-comparing their flattened input and output leaf paths: paths present in+both but changed get a :class:`FieldChange` (with a numeric ``delta`` when+both sides are numbers), paths only on one side are reported separately as+additions/removals. This is the only way to answer "did the OUTPUT move+because an INPUT moved, or because the model code changed" -- which is why+``input_hash`` is computed from inputs and configuration only, never from+``model_version`` or ``generated_at``: two artifacts built from identical+inputs on different days, or by different code versions, must still hash+identically on the input side, or that comparison is not possible.++EXPORTS DO NOT HIDE THE UGLY PARTS+-----------------------------------+Every ``export_*`` function writes an "Assumptions & Data Quality" sheet (xlsx)+or a "Data Quality Notes" section (pptx) carrying, verbatim: every+:class:`~.contracts.Assumption` with its ``basis``, the ``input_hash`` and+``model_version`` that produced the run, and ``ModelArtifact.excluded`` --+which for :mod:`comps` includes every peer dropped from a multiple+(:class:`~.comps.ExcludedMultiple`) and every EV-bridge component a peer or+the target did not supply (:class:`~.comps.EVBridgeResult.omitted_components`),+and for :mod:`threestatement` includes every period where the revolver had to+draw or repay (the model's one declared plug) plus the convergence diagnostics+:class:`~.threestatement.PeriodResult` already carries. An export that only+shows the numbers that make the model look clean is not an export of the+model -- it is a different, dishonest document that happens to share some+numbers with it.++WHAT THIS MODULE DOES NOT DO+------------------------------+It does not validate valuation inputs (that is :mod:`.contracts`'s job,+already done by the time a result object exists) and it does not recompute a+sensitivity grid on the caller's behalf -- :func:`export_dcf_workbook`+requires the caller to pass one (e.g. from+:func:`src.quantlib.valuation.dcf.sensitivity_grid`) rather than inventing a+WACC/growth sweep range, because a sweep range is itself a judgement call+this package does not make silently for the same reason+:mod:`.contracts` refuses to default a terminal growth rate.+"""++from __future__ import annotations++import dataclasses+import hashlib+import json+import math+from collections.abc import Mapping, Sequence+from dataclasses import dataclass+from datetime import datetime+from pathlib import Path+from types import MappingProxyType, ModuleType+from typing import Any++import numpy as np+import pandas as pd+from openpyxl import Workbook+from openpyxl.styles import Font+from openpyxl.worksheet.worksheet import Worksheet+from pptx import Presentation+from pptx.text.text import TextFrame+from pptx.util import Inches, Pt++from src.quantlib.valuation import comps as _comps_module+from src.quantlib.valuation import contracts as _contracts_module+from src.quantlib.valuation import dcf as _dcf_module+from src.quantlib.valuation import threestatement as _threestatement_module+from src.quantlib.valuation.comps import (+ MULTIPLE_NAMES,+ CompsResult,+ PeerCompany,+ TargetCompany,+)+from src.quantlib.valuation.contracts import Assumption+from src.quantlib.valuation.dcf import DEFAULT_LONG_RUN_GDP_GROWTH_CEILING, DCFResult+from src.quantlib.valuation.threestatement import (+ BALANCE_TOLERANCE_REL,+ CIRCULARITY_TOLERANCE_REL,+ MAX_CIRCULARITY_ITERATIONS,+ ThreeStatementProjection,+)++__all__ = [+ "AssumptionRecord",+ "ModelArtifact",+ "FieldChange",+ "ArtifactDiff",+ "compute_input_hash",+ "build_dcf_artifact",+ "build_comps_artifact",+ "build_three_statement_artifact",+ "diff_artifacts",+ "export_dcf_workbook",+ "export_comps_workbook",+ "export_three_statement_workbook",+ "export_summary_deck",+]++#: Names this module knows how to build an artifact for. Any other+#: ``model_name`` on a :class:`ModelArtifact` is a construction bug, not a+#: valid but-unsupported case -- see :meth:`ModelArtifact.__post_init__`.+_MODEL_NAMES: tuple[str, ...] = ("dcf", "comps", "three_statement")++#: This module's own artifact-schema version. Bumped only if the normalization+#: scheme in :func:`_flatten` / :func:`_normalize_number` changes in a way+#: that would make an old and a new hash falsely comparable -- folded into+#: every input hash via :data:`_HASH_SCHEMA` so such a change is never silent.+_SCHEMA_VERSION = "artifact-v1"+_HASH_SCHEMA = "vt-valuation-input-hash-v1"+++# ---------------------------------------------------------------------------+# Core types+# ---------------------------------------------------------------------------+++@dataclass(frozen=True)+class AssumptionRecord:+ """One :class:`~.contracts.Assumption` found inside a result object, located.++ Attributes:+ path: Dotted/bracket path within the result object where this+ assumption was found, e.g. ``"$.terminal_value.terminal_growth"``.+ assumption: The :class:`~.contracts.Assumption` itself -- name, value,+ basis and optional source, unmodified.+ """++ path: str+ assumption: Assumption+++@dataclass(frozen=True)+class ModelArtifact:+ """A reproducible, diffable snapshot of one completed valuation run.++ Attributes:+ model_name: One of :data:`_MODEL_NAMES` -- ``"dcf"``, ``"comps"`` or+ ``"three_statement"``.+ model_version: Content-addressed tag for the code that produced+ ``result`` -- see :func:`_module_version`.+ schema_version: This artifact schema's own version, :data:`_SCHEMA_VERSION`.+ generated_at: Caller-supplied, timezone-aware timestamp of the run.+ Never computed inside this module -- see the module docstring.+ input_hash: ``sha256`` of the canonicalised inputs and call-level+ configuration that produced ``result``. Does NOT depend on+ ``generated_at`` or ``model_version``, by construction -- see+ :func:`diff_artifacts`.+ inputs: Flat ``{dotted.path: value}`` snapshot of every input leaf+ (readable Python scalars, not the canonical hash strings), for+ display and diffing.+ outputs: Flat ``{dotted.path: value}`` snapshot of every leaf in+ ``result``, same convention as ``inputs``.+ assumptions: Every :class:`AssumptionRecord` found inside ``result``.+ Empty for ``comps`` and ``three_statement`` -- neither model's+ required inputs go through :class:`~.contracts.Assumption`; see+ the module docstring.+ result: The original typed result object (:class:`DCFResult`,+ :class:`CompsResult` or :class:`ThreeStatementProjection`),+ unmodified, for exporters that need typed access.+ excluded: Human-readable notes on everything the model dropped,+ omitted, or flagged rather than silently absorbed -- excluded+ comps, omitted EV-bridge components, terminal growth above the+ GDP-growth reference ceiling, revolver draws/repayments. Always+ present (an empty tuple IS the report "nothing was excluded"),+ and always written into every export -- see the module docstring.+ warnings: Warning strings the underlying result itself carries+ (currently only :attr:`CompsResult.warnings`); ``()`` for models+ that carry none.+ """++ model_name: str+ model_version: str+ schema_version: str+ generated_at: datetime+ input_hash: str+ inputs: Mapping[str, Any]+ outputs: Mapping[str, Any]+ assumptions: tuple[AssumptionRecord, ...]+ result: Any+ excluded: tuple[str, ...]+ warnings: tuple[str, ...]++ def __post_init__(self) -> None:+ """Check the artifact's own invariants.++ Raises:+ ValueError: If ``model_name`` is not one of :data:`_MODEL_NAMES`,+ or ``input_hash`` is not a 64-character hex sha256 digest.+ """+ if self.model_name not in _MODEL_NAMES:+ raise ValueError(+ f"ModelArtifact.model_name must be one of {_MODEL_NAMES}, "+ f"got {self.model_name!r}"+ )+ if len(self.input_hash) != 64 or any(+ c not in "0123456789abcdef" for c in self.input_hash+ ):+ raise ValueError(+ f"ModelArtifact.input_hash must be a 64-character sha256 hex "+ f"digest, got {self.input_hash!r}"+ )+++@dataclass(frozen=True)+class FieldChange:+ """One field that differs between two artifacts' inputs or outputs.++ Attributes:+ path: The dotted/bracket path that changed.+ old: The baseline artifact's value at ``path``.+ new: The updated artifact's value at ``path``.+ delta: ``new - old`` when both are numbers (and neither is a+ ``bool``); ``None`` otherwise (e.g. a string or boolean field, or+ a field that changed type).+ """++ path: str+ old: Any+ new: Any+ delta: float | None+++@dataclass(frozen=True)+class ArtifactDiff:+ """The difference between two :class:`ModelArtifact` instances of the same model.++ Attributes:+ model_name: The shared ``model_name`` of both artifacts.+ baseline_generated_at: ``baseline.generated_at``.+ updated_generated_at: ``updated.generated_at``.+ baseline_input_hash: ``baseline.input_hash``.+ updated_input_hash: ``updated.input_hash``.+ input_hash_changed: ``baseline_input_hash != updated_input_hash``.+ baseline_model_version: ``baseline.model_version``.+ updated_model_version: ``updated.model_version``.+ model_version_changed: ``baseline_model_version != updated_model_version``.+ changed_inputs: One :class:`FieldChange` per input path present on+ both artifacts whose value differs.+ added_input_paths: Input paths present on ``updated`` only.+ removed_input_paths: Input paths present on ``baseline`` only.+ changed_outputs: One :class:`FieldChange` per output path present on+ both artifacts whose value differs.+ added_output_paths: Output paths present on ``updated`` only.+ removed_output_paths: Output paths present on ``baseline`` only.+ """++ model_name: str+ baseline_generated_at: datetime+ updated_generated_at: datetime+ baseline_input_hash: str+ updated_input_hash: str+ input_hash_changed: bool+ baseline_model_version: str+ updated_model_version: str+ model_version_changed: bool+ changed_inputs: tuple[FieldChange, ...]+ added_input_paths: tuple[str, ...]+ removed_input_paths: tuple[str, ...]+ changed_outputs: tuple[FieldChange, ...]+ added_output_paths: tuple[str, ...]+ removed_output_paths: tuple[str, ...]+++# ---------------------------------------------------------------------------+# Timestamp discipline -- no hidden clock anywhere in this module+# ---------------------------------------------------------------------------+++def _require_generated_at(value: datetime, model: str) -> datetime:+ """Check that a caller-supplied timestamp is usable, and only that.++ This function never reads a clock. Its only job is to reject a call that+ did not supply one properly -- see the module docstring.++ Args:+ value: The candidate ``generated_at``.+ model: Name of the calling builder, for the error message.++ Returns:+ ``value`` unchanged.++ Raises:+ TypeError: If ``value`` is not a ``datetime.datetime``.+ ValueError: If ``value`` is timezone-naive.+ """+ if not isinstance(value, datetime):+ raise TypeError(+ f"{model}: generated_at must be a datetime.datetime supplied by the "+ f"caller, got {type(value).__name__}. This module never calls "+ "datetime.now() -- pass datetime.now(timezone.utc) yourself."+ )+ if value.tzinfo is None or value.utcoffset() is None:+ raise ValueError(+ f"{model}: generated_at must be timezone-aware (e.g. "+ "datetime.now(timezone.utc)), got a naive datetime "+ f"{value!r} -- an artifact's timestamp must be unambiguous."+ )+ return value+++# ---------------------------------------------------------------------------+# Canonical normalization: numbers, then the recursive flatten/hash engine+# ---------------------------------------------------------------------------+++def _normalize_number(value: float) -> str:+ """Canonicalise one number for hashing.++ Fixed 12-significant-digit scientific notation, independent of magnitude,+ so ``int`` and ``float`` inputs representing the same economic value hash+ identically, and ``-0.0`` collapses to ``0.0``. 12 significant digits is+ far beyond the precision any input in this package carries, so a genuine+ input change always moves the hash while floating-point representation+ noise never does.++ Args:+ value: An ``int`` or ``float`` (already unwrapped from any numpy+ scalar by the caller).++ Returns:+ A canonical string form -- ``"NaN"`` / ``"Infinity"`` / ``"-Infinity"``+ for non-finite values, else fixed-precision scientific notation.+ """+ numeric = float(value)+ if math.isnan(numeric):+ return "NaN"+ if math.isinf(numeric):+ return "Infinity" if numeric > 0 else "-Infinity"+ if numeric == 0.0:+ numeric = 0.0 # collapse -0.0+ return f"{numeric:.12e}"+++def _flatten(+ value: Any,+ path: str,+ hash_leaves: dict[str, str],+ readable_leaves: dict[str, Any],+ assumptions: list[AssumptionRecord] | None,+) -> None:+ """Recursively walk a value into flat ``path -> leaf`` dictionaries.++ Handles the exact shapes that appear in this package's inputs and result+ objects: :class:`~.contracts.Assumption`, ``None``, ``bool``, ``int``/+ ``float`` (incl. numpy scalars), ``str``, any ``Mapping`` (incl.+ ``MappingProxyType``), ``numpy.ndarray``/``pandas.Series``, ``list``/+ ``tuple``, and any frozen dataclass (every result type in :mod:`dcf`,+ :mod:`comps` and :mod:`threestatement` is one). Anything else is refused+ rather than silently stringified, because a silent ``str(obj)`` fallback+ could make two different objects hash identically.++ Args:+ value: The (sub)value to flatten.+ path: The dotted/bracket path ``value`` was reached at. Callers+ should start with ``"$"``.+ hash_leaves: Mutated in place: ``path -> canonical string`` for+ hashing.+ readable_leaves: Mutated in place: ``path -> plain Python scalar``+ for display/diffing.+ assumptions: If not ``None``, mutated in place: every+ :class:`~.contracts.Assumption` encountered is appended as an+ :class:`AssumptionRecord`. Pass ``None`` when flattening raw+ inputs (assumptions are recorded from the RESULT only -- see the+ module docstring).++ Raises:+ TypeError: If ``value`` is of a type this function does not know how+ to normalize.+ """+ if isinstance(value, np.generic):+ value = value.item()++ if isinstance(value, Assumption):+ if assumptions is not None:+ assumptions.append(AssumptionRecord(path=path, assumption=value))+ _flatten(value.name, f"{path}.name", hash_leaves, readable_leaves, assumptions)+ _flatten(value.value, f"{path}.value", hash_leaves, readable_leaves, assumptions)+ _flatten(value.basis, f"{path}.basis", hash_leaves, readable_leaves, assumptions)+ _flatten(value.source, f"{path}.source", hash_leaves, readable_leaves, assumptions)+ return++ if value is None:+ hash_leaves[path] = "null"+ readable_leaves[path] = None+ return++ if isinstance(value, bool):+ hash_leaves[path] = "true" if value else "false"+ readable_leaves[path] = value+ return++ if isinstance(value, (int, float)):+ hash_leaves[path] = _normalize_number(value)+ readable_leaves[path] = float(value)+ return++ if isinstance(value, str):+ hash_leaves[path] = json.dumps(value, ensure_ascii=False)+ readable_leaves[path] = value+ return++ if isinstance(value, Mapping):+ for key in sorted(value.keys(), key=str):+ _flatten(value[key], f"{path}.{key}", hash_leaves, readable_leaves, assumptions)+ return++ if isinstance(value, np.ndarray):+ value = value.tolist()+ elif isinstance(value, pd.Series):+ value = value.tolist()++ if isinstance(value, (list, tuple)):+ for index, item in enumerate(value):+ _flatten(item, f"{path}[{index}]", hash_leaves, readable_leaves, assumptions)+ return++ if dataclasses.is_dataclass(value) and not isinstance(value, type):+ for field in dataclasses.fields(value):+ _flatten(+ getattr(value, field.name),+ f"{path}.{field.name}",+ hash_leaves,+ readable_leaves,+ assumptions,+ )+ return++ raise TypeError(+ f"artifact: cannot normalize a value of type {type(value).__name__!r} at "+ f"path {path!r}; extend _flatten or pass a plain mapping / sequence / "+ "dataclass / Assumption / scalar"+ )+++def _hash_leaves(hash_leaves: Mapping[str, str]) -> str:+ """Hash a completed ``path -> canonical string`` leaf set.++ Args:+ hash_leaves: Output of one or more :func:`_flatten` calls.++ Returns:+ A 64-character sha256 hex digest.+ """+ canonical = json.dumps(+ {"schema": _HASH_SCHEMA, "leaves": dict(hash_leaves)},+ sort_keys=True,+ ensure_ascii=False,+ separators=(",", ":"),+ )+ return hashlib.sha256(canonical.encode("utf-8")).hexdigest()+++def compute_input_hash(payload: Any) -> str:+ """Hash an arbitrary payload the same way ``build_*_artifact`` hashes inputs.++ Public mainly so the normalization scheme (:func:`_flatten` /+ :func:`_normalize_number`) can be tested directly, independent of any one+ model's builder.++ Args:+ payload: Any value :func:`_flatten` can walk -- typically a mapping+ combining call-level config with the model's raw inputs.++ Returns:+ A 64-character sha256 hex digest. Identical for two payloads that are+ the same after normalization (dict key order, ``int``/``float``,+ ``-0.0``/``0.0`` do not matter); different if any leaf's value+ genuinely differs.+ """+ hash_leaves: dict[str, str] = {}+ readable_leaves: dict[str, Any] = {}+ _flatten(payload, "$", hash_leaves, readable_leaves, None)+ return _hash_leaves(hash_leaves)+++def _module_version(module: ModuleType) -> str:+ """Build a content-addressed version tag for the module that produced a result.++ Hashes ``module``'s own source together with :mod:`.contracts`'s, since+ every model in this package depends on ``contracts.py``'s input+ discipline -- a change there changes what produced an artifact even if+ ``module``'s own text is untouched. Content-addressed rather than a+ hand-maintained string because no ``__version__`` exists anywhere in+ :mod:`src.quantlib` to defer to, and a hand-maintained tag goes stale+ exactly when it matters most (a formula changes but the tag does not).++ Args:+ module: The model module (:mod:`dcf`, :mod:`comps` or+ :mod:`threestatement`).++ Returns:+ ``"<module.__name__>@sha256:<16 hex chars>"``.+ """+ own_source = Path(module.__file__).read_bytes()+ shared_source = Path(_contracts_module.__file__).read_bytes()+ digest = hashlib.sha256(own_source + b"\x00" + shared_source).hexdigest()[:16]+ return f"{module.__name__}@sha256:{digest}"+++# ---------------------------------------------------------------------------+# Gap/exclusion extraction -- the "ugly parts" every export must carry+# ---------------------------------------------------------------------------+++def _dcf_gaps(result: DCFResult) -> tuple[str, ...]:+ """Collect DCF-specific notes: GDP-ceiling flag and the non-chosen terminal method.++ Args:+ result: A completed :class:`DCFResult`.++ Returns:+ Human-readable notes, possibly empty.+ """+ notes: list[str] = []+ tv = result.terminal_value+ if tv.growth_exceeds_gdp_ceiling:+ notes.append(+ f"terminal_growth={tv.terminal_growth.value!r} exceeds the "+ f"gdp_growth_ceiling={tv.gdp_growth_ceiling!r} (a flag, not a "+ "rejection) -- review whether a perpetuity growth rate this high "+ "is defensible for this business."+ )+ other_method = (+ "exit_multiple" if result.terminal_value_method == "perpetuity_growth" else "perpetuity_growth"+ )+ notes.append(+ f"terminal_value_method={result.terminal_value_method!r} was discounted "+ f"into enterprise_value; the other method ({other_method!r}) was still "+ f"computed (perpetuity_terminal_value={tv.perpetuity_terminal_value!r}, "+ f"exit_terminal_value={tv.exit_terminal_value!r}, "+ f"implied_ev_ebitda_multiple={tv.implied_ev_ebitda_multiple!r}, "+ f"implied_perpetuity_growth={tv.implied_perpetuity_growth!r}) and is not "+ "silently dropped."+ )+ return tuple(notes)+++def _comps_gaps(result: CompsResult, target: TargetCompany) -> tuple[str, ...]:+ """Collect comps-specific notes: excluded multiples and omitted EV-bridge components.++ Args:+ result: A completed :class:`CompsResult`.+ target: The target company the run was built for -- needed because+ the target's own EV-bridge omissions (used inside+ ``equity_value_from_enterprise_value`` while walking each+ EV-multiple's implied value back to equity) are not retained on+ ``CompsResult`` itself.++ Returns:+ Human-readable notes, possibly empty.+ """+ notes: list[str] = []+ for peer in result.peer_multiples:+ if peer.ev_bridge.omitted_components:+ notes.append(+ f"peer {peer.name!r}: EV bridge omitted "+ f"{', '.join(peer.ev_bridge.omitted_components)} (not supplied -- "+ "treated as unknown, not zero)."+ )+ for excl in peer.exclusions:+ notes.append(+ f"peer {peer.name!r}: {excl.multiple_name} excluded -- denominator "+ f"{excl.denominator_value!r} is not positive."+ )+ target_omitted = tuple(+ name+ for name, value in (+ ("minority_interest", target.minority_interest),+ ("preferred_stock", target.preferred_stock),+ ("investments_in_associates", target.investments_in_associates),+ )+ if value is None+ )+ if target_omitted:+ notes.append(+ f"target {target.name!r}: EV bridge omitted {', '.join(target_omitted)} "+ "when walking an implied enterprise value back to implied equity value."+ )+ return tuple(notes)+++def _three_statement_gaps(result: ThreeStatementProjection) -> tuple[str, ...]:+ """Collect three-statement notes: non-convergence and revolver plug activity.++ A successfully-returned :class:`ThreeStatementProjection` cannot actually+ contain a non-converged period -- :func:`~.threestatement.project_three_statement`+ raises :class:`~.threestatement.ConvergenceError` before one is+ constructed. The check below is kept anyway (mirroring+ :mod:`threestatement`'s own defensive re-checks) so that if this invariant+ is ever loosened upstream, an artifact built from the result still+ surfaces it rather than silently reporting ``converged=True``.++ Args:+ result: A completed :class:`ThreeStatementProjection`.++ Returns:+ Human-readable notes, possibly empty.+ """+ notes: list[str] = []+ for period in result.periods:+ if not period.converged:+ notes.append(+ f"period {period.period}: interest/revolver circularity DID NOT "+ f"CONVERGE after {period.iterations} iteration(s) -- treat this "+ "period's financing line items as unresolved."+ )+ cfs = period.cash_flow_statement+ if cfs.revolver_draw > 0.0:+ notes.append(+ f"period {period.period}: revolver drew {cfs.revolver_draw!r} to "+ "hold cash at minimum_cash -- financing is not organic."+ )+ if cfs.revolver_repayment > 0.0:+ notes.append(+ f"period {period.period}: revolver repaid {cfs.revolver_repayment!r} "+ "from surplus cash."+ )+ return tuple(notes)+++# ---------------------------------------------------------------------------+# Builders+# ---------------------------------------------------------------------------+++def build_dcf_artifact(+ *,+ inputs: Mapping[str, Any],+ result: DCFResult,+ generated_at: datetime,+ capital_structure_basis: str,+ discounting_convention: str,+ terminal_value_method: str,+ gdp_growth_ceiling: float = DEFAULT_LONG_RUN_GDP_GROWTH_CEILING,+) -> ModelArtifact:+ """Wrap a completed :func:`~.dcf.run_dcf` call into a versioned artifact.++ ``capital_structure_basis``, ``discounting_convention``,+ ``terminal_value_method`` and ``gdp_growth_ceiling`` are hashed alongside+ ``inputs`` because each one changes ``result`` just as much as a number in+ ``inputs`` would -- an artifact whose hash ignored them could report+ "inputs unchanged" for two runs that priced the same cash flows two+ different ways.++ Assumptions are collected from ``result`` (via ``result.terminal_value``),+ not from ``inputs`` directly -- :func:`~.dcf.run_dcf` passes the same+ :class:`~.contracts.Assumption` objects through unchanged, so walking the+ result finds them without walking the raw inputs a second time.++ Args:+ inputs: The exact mapping passed as ``run_dcf(inputs, ...)``.+ result: The :class:`DCFResult` that call produced.+ generated_at: Timezone-aware timestamp of the run, supplied by the+ caller. See :func:`_require_generated_at`.+ capital_structure_basis: The ``capital_structure_basis`` the call used.+ discounting_convention: The ``discounting_convention`` the call used.+ terminal_value_method: The ``terminal_value_method`` the call used.+ gdp_growth_ceiling: The ``gdp_growth_ceiling`` the call used.++ Returns:+ A ``model_name="dcf"`` :class:`ModelArtifact`.++ Raises:+ TypeError: If ``generated_at`` is not a ``datetime``, or ``result``+ is not a :class:`DCFResult`.+ ValueError: If ``generated_at`` is timezone-naive.+ """+ generated_at = _require_generated_at(generated_at, "build_dcf_artifact")+ if not isinstance(result, DCFResult):+ raise TypeError(+ f"build_dcf_artifact: result must be a DCFResult, got {type(result).__name__}"+ )++ canonical_inputs = {+ "config": {+ "capital_structure_basis": capital_structure_basis,+ "discounting_convention": discounting_convention,+ "terminal_value_method": terminal_value_method,+ "gdp_growth_ceiling": gdp_growth_ceiling,+ },+ "model_inputs": dict(inputs),+ }+ hash_leaves: dict[str, str] = {}+ readable_inputs: dict[str, Any] = {}+ _flatten(canonical_inputs, "$", hash_leaves, readable_inputs, None)+ input_hash = _hash_leaves(hash_leaves)++ readable_outputs: dict[str, Any] = {}+ assumptions: list[AssumptionRecord] = []+ _flatten(result, "$", {}, readable_outputs, assumptions)++ return ModelArtifact(+ model_name="dcf",+ model_version=_module_version(_dcf_module),+ schema_version=_SCHEMA_VERSION,+ generated_at=generated_at,+ input_hash=input_hash,+ inputs=MappingProxyType(readable_inputs),+ outputs=MappingProxyType(readable_outputs),+ assumptions=tuple(assumptions),+ result=result,+ excluded=_dcf_gaps(result),+ warnings=(),+ )+++def build_comps_artifact(+ *,+ target: TargetCompany,+ peers: Sequence[PeerCompany],+ calendarisation_policy: str,+ result: CompsResult,+ generated_at: datetime,+) -> ModelArtifact:+ """Wrap a completed :func:`~.comps.run_comps` call into a versioned artifact.++ :mod:`comps` takes no :class:`~.contracts.Assumption` objects anywhere in+ its required inputs -- every field on :class:`TargetCompany` and+ :class:`PeerCompany` is a bare number or a+ :class:`~.comps.FlowMetricPeriods`. The resulting artifact's+ ``assumptions`` is therefore always ``()``; that is a fact about the+ model, not a gap in this builder, and every export says so explicitly+ rather than leaving the section blank.++ Args:+ target: The :class:`TargetCompany` passed to ``run_comps``.+ peers: The peer sequence passed to ``run_comps``.+ calendarisation_policy: The ``calendarisation_policy`` the call used.+ result: The :class:`CompsResult` that call produced.+ generated_at: Timezone-aware timestamp of the run, supplied by the+ caller.++ Returns:+ A ``model_name="comps"`` :class:`ModelArtifact`.++ Raises:+ TypeError: If ``generated_at`` is not a ``datetime``, or ``result``+ is not a :class:`CompsResult`.+ ValueError: If ``generated_at`` is timezone-naive.+ """+ generated_at = _require_generated_at(generated_at, "build_comps_artifact")+ if not isinstance(result, CompsResult):+ raise TypeError(+ f"build_comps_artifact: result must be a CompsResult, got {type(result).__name__}"+ )++ canonical_inputs = {+ "config": {"calendarisation_policy": calendarisation_policy},+ "target": target,+ "peers": list(peers),+ }+ hash_leaves: dict[str, str] = {}+ readable_inputs: dict[str, Any] = {}+ _flatten(canonical_inputs, "$", hash_leaves, readable_inputs, None)+ input_hash = _hash_leaves(hash_leaves)++ readable_outputs: dict[str, Any] = {}+ assumptions: list[AssumptionRecord] = []+ _flatten(result, "$", {}, readable_outputs, assumptions)++ return ModelArtifact(+ model_name="comps",+ model_version=_module_version(_comps_module),+ schema_version=_SCHEMA_VERSION,+ generated_at=generated_at,+ input_hash=input_hash,+ inputs=MappingProxyType(readable_inputs),+ outputs=MappingProxyType(readable_outputs),+ assumptions=tuple(assumptions),+ result=result,+ excluded=_comps_gaps(result, target),+ warnings=result.warnings,+ )+++def build_three_statement_artifact(+ *,+ opening: Mapping[str, float],+ drivers: Mapping[str, Sequence[float]],+ result: ThreeStatementProjection,+ generated_at: datetime,+ circularity_tolerance: float = CIRCULARITY_TOLERANCE_REL,+ max_circularity_iterations: int = MAX_CIRCULARITY_ITERATIONS,+ balance_tolerance: float = BALANCE_TOLERANCE_REL,+) -> ModelArtifact:+ """Wrap a completed :func:`~.threestatement.project_three_statement` call into an artifact.++ The three tolerance/iteration-budget parameters default to the same+ constants :func:`~.threestatement.project_three_statement` itself+ defaults to -- these are numerical-solver knobs, not valuation opinions,+ so mirroring the model's own defaults keeps the hash consistent for a+ caller who did not override them, without this module inventing anything+ :mod:`.contracts` would refuse (a terminal growth rate or similar+ price-determining assumption is never defaulted anywhere in this file).++ Like :mod:`comps`, :mod:`threestatement` takes no+ :class:`~.contracts.Assumption` objects -- every driver is a bare number.+ ``assumptions`` on the returned artifact is therefore always ``()``.++ Args:+ opening: The exact mapping passed as ``project_three_statement(opening, ...)``.+ drivers: The exact mapping passed as the ``drivers`` argument.+ result: The :class:`ThreeStatementProjection` that call produced.+ generated_at: Timezone-aware timestamp of the run, supplied by the+ caller.+ circularity_tolerance: The ``circularity_tolerance`` the call used.+ max_circularity_iterations: The ``max_circularity_iterations`` the+ call used.+ balance_tolerance: The ``balance_tolerance`` the call used.++ Returns:+ A ``model_name="three_statement"`` :class:`ModelArtifact`.++ Raises:+ TypeError: If ``generated_at`` is not a ``datetime``, or ``result``+ is not a :class:`ThreeStatementProjection`.+ ValueError: If ``generated_at`` is timezone-naive.+ """+ generated_at = _require_generated_at(generated_at, "build_three_statement_artifact")+ if not isinstance(result, ThreeStatementProjection):+ raise TypeError(+ "build_three_statement_artifact: result must be a "+ f"ThreeStatementProjection, got {type(result).__name__}"+ )++ canonical_inputs = {+ "config": {+ "circularity_tolerance": circularity_tolerance,+ "max_circularity_iterations": max_circularity_iterations,+ "balance_tolerance": balance_tolerance,+ },+ "opening": dict(opening),+ "drivers": {key: list(value) for key, value in drivers.items()},+ }+ hash_leaves: dict[str, str] = {}+ readable_inputs: dict[str, Any] = {}+ _flatten(canonical_inputs, "$", hash_leaves, readable_inputs, None)+ input_hash = _hash_leaves(hash_leaves)++ readable_outputs: dict[str, Any] = {}+ assumptions: list[AssumptionRecord] = []+ _flatten(result, "$", {}, readable_outputs, assumptions)++ return ModelArtifact(+ model_name="three_statement",+ model_version=_module_version(_threestatement_module),+ schema_version=_SCHEMA_VERSION,+ generated_at=generated_at,+ input_hash=input_hash,+ inputs=MappingProxyType(readable_inputs),+ outputs=MappingProxyType(readable_outputs),+ assumptions=tuple(assumptions),+ result=result,+ excluded=_three_statement_gaps(result),+ warnings=(),+ )+++# ---------------------------------------------------------------------------+# Diff+# ---------------------------------------------------------------------------+++def _diff_leaves(+ baseline: Mapping[str, Any], updated: Mapping[str, Any]+) -> tuple[tuple[FieldChange, ...], tuple[str, ...], tuple[str, ...]]:+ """Diff two flat ``path -> value`` snapshots.++ Args:+ baseline: The "before" flat snapshot.+ updated: The "after" flat snapshot.++ Returns:+ ``(changed, added_paths, removed_paths)`` -- ``changed`` covers only+ paths present on both sides whose value differs; ``added_paths`` /+ ``removed_paths`` are sorted tuples of paths present on one side only.+ """+ baseline_keys = set(baseline.keys())+ updated_keys = set(updated.keys())+ changed: list[FieldChange] = []+ for path in sorted(baseline_keys & updated_keys):+ old, new = baseline[path], updated[path]+ if old == new:+ continue+ delta = None+ if (+ isinstance(old, (int, float))+ and not isinstance(old, bool)+ and isinstance(new, (int, float))+ and not isinstance(new, bool)+ ):+ delta = float(new) - float(old)+ changed.append(FieldChange(path=path, old=old, new=new, delta=delta))+ added = tuple(sorted(updated_keys - baseline_keys))+ removed = tuple(sorted(baseline_keys - updated_keys))+ return tuple(changed), added, removed+++def diff_artifacts(baseline: ModelArtifact, updated: ModelArtifact) -> ArtifactDiff:+ """Diff two artifacts of the same model: which fields changed, by how much.++ Args:+ baseline: The "before" artifact.+ updated: The "after" artifact. Must share ``baseline.model_name``.++ Returns:+ An :class:`ArtifactDiff` naming every changed/added/removed input and+ output path.++ Raises:+ ValueError: If ``baseline.model_name != updated.model_name`` -- the+ two artifacts would have no comparable field paths.+ """+ if baseline.model_name != updated.model_name:+ raise ValueError(+ f"diff_artifacts: cannot diff a {baseline.model_name!r} artifact "+ f"against a {updated.model_name!r} artifact -- they have no "+ "comparable field paths"+ )+ changed_inputs, added_inputs, removed_inputs = _diff_leaves(baseline.inputs, updated.inputs)+ changed_outputs, added_outputs, removed_outputs = _diff_leaves(baseline.outputs, updated.outputs)+ return ArtifactDiff(+ model_name=baseline.model_name,+ baseline_generated_at=baseline.generated_at,+ updated_generated_at=updated.generated_at,+ baseline_input_hash=baseline.input_hash,+ updated_input_hash=updated.input_hash,+ input_hash_changed=baseline.input_hash != updated.input_hash,+ baseline_model_version=baseline.model_version,+ updated_model_version=updated.model_version,+ model_version_changed=baseline.model_version != updated.model_version,+ changed_inputs=changed_inputs,+ added_input_paths=added_inputs,+ removed_input_paths=removed_inputs,+ changed_outputs=changed_outputs,+ added_output_paths=added_outputs,+ removed_output_paths=removed_outputs,+ )+++# ---------------------------------------------------------------------------+# xlsx export -- shared helpers+# ---------------------------------------------------------------------------+++def _bold_row(ws: Worksheet, row: int = 1) -> None:+ """Bold every cell in one worksheet row (typically a header row)."""+ for cell in ws[row]:+ cell.font = Font(bold=True)+++def _write_assumptions_and_gaps_sheet(wb: Workbook, artifact: ModelArtifact) -> None:+ """Write the "Assumptions & Data Quality" sheet shared by every xlsx export.++ Layout (rows, 1-indexed):+ 1: ``["Provenance"]``+ 2-6: ``model_name`` / ``model_version`` / ``schema_version`` /+ ``generated_at`` / ``input_hash``, each as ``[field, value]``+ 7: blank+ 8: ``["Assumptions", "name", "value", "basis", "source"]`` header+ 9..: one row per :class:`AssumptionRecord`, or a single+ ``"(none) -- ..."`` row if there are none+ blank, ``["Warnings"]``, one row per warning (or ``"(none)"``)+ blank, ``["Excluded / Omitted / Data-quality notes"]``, one row per+ note in ``artifact.excluded`` (or ``"(none)"``)++ Args:+ wb: The workbook to add the sheet to.+ artifact: The artifact whose provenance/assumptions/gaps to write.+ """+ ws = wb.create_sheet("Assumptions & Data Quality")+ ws.append(["Provenance"])+ ws.append(["model_name", artifact.model_name])+ ws.append(["model_version", artifact.model_version])+ ws.append(["schema_version", artifact.schema_version])+ ws.append(["generated_at", artifact.generated_at.isoformat()])+ ws.append(["input_hash", artifact.input_hash])+ ws.append([])+ ws.append(["Assumptions", "name", "value", "basis", "source"])+ if artifact.assumptions:+ for record in artifact.assumptions:+ a = record.assumption+ ws.append([record.path, a.name, a.value, a.basis, a.source or ""])+ else:+ ws.append(["(none) -- this model requires no caller-supplied Assumption objects"])+ ws.append([])+ ws.append(["Warnings"])+ for warning in artifact.warnings:+ ws.append([warning])+ if not artifact.warnings:+ ws.append(["(none)"])+ ws.append([])+ ws.append(["Excluded / Omitted / Data-quality notes"])+ for note in artifact.excluded:+ ws.append([note])+ if not artifact.excluded:+ ws.append(["(none)"])++ _bold_row(ws, 1)+ _bold_row(ws, 8)+++# ---------------------------------------------------------------------------+# xlsx export -- DCF+# ---------------------------------------------------------------------------++_FCFF_HEADERS: tuple[str, ...] = (+ "Year", "EBIT", "Tax Rate", "NOPAT", "D&A", "CapEx", "Delta NWC",+ "FCFF", "Discount Factor", "Present Value",+)++_WACC_FIELDS: tuple[str, ...] = (+ "risk_free_rate", "beta", "equity_risk_premium", "size_premium",+ "country_risk_premium", "cost_of_equity", "pretax_cost_of_debt", "tax_rate",+ "cost_of_debt_after_tax", "capital_structure_basis", "equity_weight",+ "debt_weight", "wacc",+)+++def _write_fcff_bridge_sheet(wb: Workbook, result: DCFResult) -> None:+ """Write the "FCFF Bridge" sheet: one row per year plus a PV total row."""+ ws = wb.create_sheet("FCFF Bridge")+ ws.append(list(_FCFF_HEADERS))+ for year, discounted in zip(result.fcff_bridge, result.discounted_fcff, strict=True):+ ws.append(+ [+ year.year, year.ebit, year.tax_rate, year.nopat,+ year.depreciation_amortization, year.capex, year.delta_nwc, year.fcff,+ discounted.discount_factor, discounted.present_value,+ ]+ )+ ws.append(+ ["Total", None, None, None, None, None, None, None,+ "PV of explicit FCFF", result.pv_of_explicit_fcff]+ )+ _bold_row(ws)+++def _write_wacc_sheet(wb: Workbook, result: DCFResult) -> None:+ """Write the "WACC Build" sheet as ``field -> value`` rows."""+ ws = wb.create_sheet("WACC Build")+ ws.append(["Field", "Value"])+ for field in _WACC_FIELDS:+ ws.append([field, getattr(result.wacc_build, field)])+ _bold_row(ws)+++def _write_terminal_value_sheet(wb: Workbook, result: DCFResult) -> None:+ """Write the "Terminal Value" sheet: both estimates, cross-checks, the full bridge."""+ ws = wb.create_sheet("Terminal Value")+ ws.append(["Field", "Value"])+ tv = result.terminal_value+ ndb = result.net_debt_bridge+ rows: tuple[tuple[str, Any], ...] = (+ ("wacc_rate", tv.wacc_rate),+ ("terminal_growth.value", tv.terminal_growth.value),+ ("terminal_growth.basis", tv.terminal_growth.basis),+ ("terminal_growth.source", tv.terminal_growth.source or ""),+ ("perpetuity_terminal_value", tv.perpetuity_terminal_value),+ ("terminal_year_ebitda", tv.terminal_year_ebitda),+ ("exit_multiple.value", tv.exit_multiple.value),+ ("exit_multiple.basis", tv.exit_multiple.basis),+ ("exit_multiple.source", tv.exit_multiple.source or ""),+ ("exit_terminal_value", tv.exit_terminal_value),+ ("implied_ev_ebitda_multiple", tv.implied_ev_ebitda_multiple),+ ("implied_perpetuity_growth", tv.implied_perpetuity_growth),+ ("gdp_growth_ceiling", tv.gdp_growth_ceiling),+ ("growth_exceeds_gdp_ceiling", tv.growth_exceeds_gdp_ceiling),+ ("terminal_value_method (chosen)", result.terminal_value_method),+ ("discounting_convention", result.discounting_convention),+ ("terminal_discount_factor", result.terminal_discount_factor),+ ("pv_of_explicit_fcff", result.pv_of_explicit_fcff),+ ("pv_of_terminal_value", result.pv_of_terminal_value),+ ("enterprise_value", result.enterprise_value),+ ("net_debt_bridge.total_debt", ndb.total_debt),+ ("net_debt_bridge.cash_and_equivalents", ndb.cash_and_equivalents),+ ("net_debt_bridge.minority_interest", ndb.minority_interest),+ ("net_debt_bridge.preferred_equity", ndb.preferred_equity),+ ("net_debt_bridge.associate_investments", ndb.associate_investments),+ ("equity_value", result.equity_value),+ ("net_debt_bridge.diluted_shares", ndb.diluted_shares),+ ("value_per_share", result.value_per_share),+ )+ for name, value in rows:+ ws.append([name, value])+ _bold_row(ws)+++def _write_sensitivity_sheet(wb: Workbook, grid: pd.DataFrame) -> None:+ """Write the "Sensitivity" sheet from a wacc x growth value-per-share grid."""+ ws = wb.create_sheet("Sensitivity")+ header_label = f"{grid.index.name} \\ {grid.columns.name}"+ ws.append([header_label] + [float(col) for col in grid.columns])+ for wacc_value, row in grid.iterrows():+ cells = [None if pd.isna(v) else float(v) for v in row]+ ws.append([float(wacc_value)] + cells)+ _bold_row(ws)+++def export_dcf_workbook(+ artifact: ModelArtifact,+ path: str | Path,+ *,+ sensitivity_grid: pd.DataFrame,+) -> Path:+ """Export a DCF artifact to a 5-sheet workbook.++ Sheets, in order: "FCFF Bridge", "WACC Build", "Terminal Value" (both+ terminal-value estimates cross-checked, and the full net-debt bridge to+ value per share), "Sensitivity" (the caller-supplied grid), "Assumptions+ & Data Quality" (see :func:`_write_assumptions_and_gaps_sheet`).++ Args:+ artifact: A ``model_name="dcf"`` artifact from :func:`build_dcf_artifact`.+ path: Output ``.xlsx`` path. Parent directories are created if absent.+ sensitivity_grid: A wacc x growth value-per-share grid, e.g. from+ :func:`src.quantlib.valuation.dcf.sensitivity_grid`. Required --+ this function does not choose a WACC/growth sweep range on the+ caller's behalf; see the module docstring.++ Returns:+ The written path.++ Raises:+ TypeError: If ``artifact.model_name != "dcf"``.+ """+ if artifact.model_name != "dcf":+ raise TypeError(+ f"export_dcf_workbook: expected a 'dcf' artifact, got {artifact.model_name!r}"+ )+ result: DCFResult = artifact.result++ wb = Workbook()+ wb.remove(wb.active)+ _write_fcff_bridge_sheet(wb, result)+ _write_wacc_sheet(wb, result)+ _write_terminal_value_sheet(wb, result)+ _write_sensitivity_sheet(wb, sensitivity_grid)+ _write_assumptions_and_gaps_sheet(wb, artifact)++ out_path = Path(path)+ out_path.parent.mkdir(parents=True, exist_ok=True)+ wb.save(str(out_path))+ return out_path+++# ---------------------------------------------------------------------------+# xlsx export -- comps+# ---------------------------------------------------------------------------++_PEER_HEADERS: tuple[str, ...] = (+ "name", "equity_value", "total_debt", "cash_and_equivalents", "enterprise_value",+ "omitted_ev_bridge_components", "ebitda", "ebit", "revenue", "diluted_eps",+ "ev_ebitda", "ev_ebit", "ev_sales", "pe", "pb",+)+++def _write_peer_detail_sheet(wb: Workbook, result: CompsResult) -> None:+ """Write the "Peer Detail" sheet: one row per peer's bridge, metrics and multiples."""+ ws = wb.create_sheet("Peer Detail")+ ws.append(list(_PEER_HEADERS))+ for peer in result.peer_multiples:+ ws.append(+ [+ peer.name,+ peer.ev_bridge.equity_value,+ peer.ev_bridge.total_debt,+ peer.ev_bridge.cash_and_equivalents,+ peer.ev_bridge.enterprise_value,+ ", ".join(peer.ev_bridge.omitted_components) or "(none)",+ peer.calendarised_ebitda.value,+ peer.calendarised_ebit.value,+ peer.calendarised_revenue.value,+ peer.calendarised_diluted_eps.value,+ peer.ev_ebitda if peer.ev_ebitda is not None else "excluded",+ peer.ev_ebit if peer.ev_ebit is not None else "excluded",+ peer.ev_sales if peer.ev_sales is not None else "excluded",+ peer.pe if peer.pe is not None else "excluded",+ peer.pb if peer.pb is not None else "excluded",+ ]+ )+ _bold_row(ws)+++def _write_multiple_matrix_sheet(wb: Workbook, result: CompsResult) -> None:+ """Write the "Multiple Matrix" sheet: cross-sectional stats plus excluded-peer detail."""+ ws = wb.create_sheet("Multiple Matrix")+ ws.append(["multiple", "min", "p25", "median", "p75", "max", "n_included", "n_excluded", "warning"])+ for name in MULTIPLE_NAMES:+ dist = result.distributions[name]+ ws.append(+ [+ name, dist.minimum, dist.p25, dist.median, dist.p75, dist.maximum,+ len(dist.included), len(dist.excluded), dist.warning or "",+ ]+ )+ ws.append([])+ ws.append(["Excluded detail: peer", "multiple", "denominator_value"])+ for peer in result.peer_multiples:+ for excl in peer.exclusions:+ ws.append([excl.peer_name, excl.multiple_name, excl.denominator_value])+ _bold_row(ws, 1)+++_QUANTILE_LABELS: tuple[str, ...] = ("minimum", "p25", "median", "p75", "maximum")+++def _write_implied_valuation_sheet(wb: Workbook, result: CompsResult) -> None:+ """Write the "Implied Valuation" sheet: target metric x peer quantiles, EV and equity."""+ ws = wb.create_sheet("Implied Valuation")+ ws.append(+ [+ "multiple", "is_ev_multiple", "target_metric_value",+ "implied_ev_min", "implied_ev_p25", "implied_ev_median", "implied_ev_p75", "implied_ev_max",+ "implied_equity_min", "implied_equity_p25", "implied_equity_median",+ "implied_equity_p75", "implied_equity_max", "warning",+ ]+ )+ for name in MULTIPLE_NAMES:+ iv = result.implied_valuations[name]+ ev_map = iv.implied_ev_by_quantile+ eq_map = iv.implied_equity_value_by_quantile+ ev_cells = [ev_map.get(label) if ev_map else None for label in _QUANTILE_LABELS]+ eq_cells = [eq_map.get(label) if eq_map else None for label in _QUANTILE_LABELS]+ ws.append([name, iv.is_ev_multiple, iv.target_metric_value, *ev_cells, *eq_cells, iv.warning or ""])+ _bold_row(ws)+++def export_comps_workbook(artifact: ModelArtifact, path: str | Path) -> Path:+ """Export a comps artifact to a 4-sheet workbook.++ Sheets, in order: "Peer Detail", "Multiple Matrix" (including the+ excluded-peer detail block), "Implied Valuation", "Assumptions & Data+ Quality" (see :func:`_write_assumptions_and_gaps_sheet` -- for comps this+ sheet's assumptions block always reads "(none)"; see+ :func:`build_comps_artifact`).++ Args:+ artifact: A ``model_name="comps"`` artifact from :func:`build_comps_artifact`.+ path: Output ``.xlsx`` path. Parent directories are created if absent.++ Returns:+ The written path.++ Raises:+ TypeError: If ``artifact.model_name != "comps"``.+ """+ if artifact.model_name != "comps":+ raise TypeError(+ f"export_comps_workbook: expected a 'comps' artifact, got {artifact.model_name!r}"+ )+ result: CompsResult = artifact.result++ wb = Workbook()+ wb.remove(wb.active)+ _write_peer_detail_sheet(wb, result)+ _write_multiple_matrix_sheet(wb, result)+ _write_implied_valuation_sheet(wb, result)+ _write_assumptions_and_gaps_sheet(wb, artifact)++ out_path = Path(path)+ out_path.parent.mkdir(parents=True, exist_ok=True)+ wb.save(str(out_path))+ return out_path+++# ---------------------------------------------------------------------------+# xlsx export -- three-statement+# ---------------------------------------------------------------------------++_INCOME_HEADERS: tuple[str, ...] = (+ "period", "revenue", "gross_profit", "opex", "ebitda",+ "depreciation_amortization", "ebit", "interest_expense", "pretax_income",+ "tax_expense", "net_income",+)++_CASHFLOW_HEADERS: tuple[str, ...] = (+ "period", "net_income", "depreciation_amortization",+ "change_in_net_working_capital", "capex", "dividends_paid", "revolver_draw",+ "revolver_repayment", "financing_activities", "net_change_in_cash",+ "cash_flow_from_operations", "free_cash_flow", "converged", "iterations",+)++_BALANCE_HEADERS: tuple[str, ...] = (+ "period", "cash", "net_working_capital", "ppe", "revolver_balance",+ "paid_in_capital", "retained_earnings", "total_assets", "total_liabilities",+ "total_equity", "residual",+)+++def _write_income_statement_sheet(wb: Workbook, projection: ThreeStatementProjection) -> None:+ """Write the "Income Statement" sheet: one row per projected period."""+ ws = wb.create_sheet("Income Statement")+ ws.append(list(_INCOME_HEADERS))+ for period in projection.periods:+ s = period.income_statement+ ws.append(+ [+ s.period, s.revenue, s.gross_profit, s.opex, s.ebitda,+ s.depreciation_amortization, s.ebit, s.interest_expense,+ s.pretax_income, s.tax_expense, s.net_income,+ ]+ )+ _bold_row(ws)+++def _write_cash_flow_sheet(wb: Workbook, projection: ThreeStatementProjection) -> None:+ """Write the "Cash Flow Statement" sheet, incl. the convergence diagnostics."""+ ws = wb.create_sheet("Cash Flow Statement")+ ws.append(list(_CASHFLOW_HEADERS))+ for period in projection.periods:+ c = period.cash_flow_statement+ ws.append(+ [+ c.period, c.net_income, c.depreciation_amortization,+ c.change_in_net_working_capital, c.capex, c.dividends_paid,+ c.revolver_draw, c.revolver_repayment, c.financing_activities,+ c.net_change_in_cash, c.cash_flow_from_operations, c.free_cash_flow,+ period.converged, period.iterations,+ ]+ )+ _bold_row(ws)+++def _write_balance_sheet_sheet(wb: Workbook, projection: ThreeStatementProjection) -> None:+ """Write the "Balance Sheet" sheet, opening plus every period, with the balance residual."""+ ws = wb.create_sheet("Balance Sheet")+ ws.append(list(_BALANCE_HEADERS))+ all_sheets = (projection.opening_balance_sheet, *(p.balance_sheet for p in projection.periods))+ for bs in all_sheets:+ residual = bs.total_assets - bs.total_liabilities - bs.total_equity+ ws.append(+ [+ bs.period, bs.cash, bs.net_working_capital, bs.ppe, bs.revolver_balance,+ bs.paid_in_capital, bs.retained_earnings, bs.total_assets,+ bs.total_liabilities, bs.total_equity, residual,+ ]+ )+ _bold_row(ws)+++def export_three_statement_workbook(artifact: ModelArtifact, path: str | Path) -> Path:+ """Export a three-statement artifact to a 4-sheet workbook.++ Sheets, in order: "Income Statement", "Cash Flow Statement" (including+ the per-period ``converged``/``iterations`` circularity diagnostics),+ "Balance Sheet" (including a ``residual`` column, opening balance sheet+ plus every period), "Assumptions & Data Quality" (see+ :func:`_write_assumptions_and_gaps_sheet` -- for three-statement this+ sheet's assumptions block always reads "(none)"; see+ :func:`build_three_statement_artifact`).++ Args:+ artifact: A ``model_name="three_statement"`` artifact from+ :func:`build_three_statement_artifact`.+ path: Output ``.xlsx`` path. Parent directories are created if absent.++ Returns:+ The written path.++ Raises:+ TypeError: If ``artifact.model_name != "three_statement"``.+ """+ if artifact.model_name != "three_statement":+ raise TypeError(+ "export_three_statement_workbook: expected a 'three_statement' "+ f"artifact, got {artifact.model_name!r}"+ )+ projection: ThreeStatementProjection = artifact.result++ wb = Workbook()+ wb.remove(wb.active)+ _write_income_statement_sheet(wb, projection)+ _write_cash_flow_sheet(wb, projection)+ _write_balance_sheet_sheet(wb, projection)+ _write_assumptions_and_gaps_sheet(wb, artifact)++ out_path = Path(path)+ out_path.parent.mkdir(parents=True, exist_ok=True)+ wb.save(str(out_path))+ return out_path+++# ---------------------------------------------------------------------------+# pptx export -- one-slide summary, any model+# ---------------------------------------------------------------------------+++def _dcf_headline(result: DCFResult) -> list[str]:+ """Return the DCF valuation-conclusion bullet lines."""+ return [+ f"Enterprise value: {result.enterprise_value:,.2f}",+ f"Equity value: {result.equity_value:,.2f}",+ f"Value per share: {result.value_per_share:,.4f}",+ f"WACC: {result.wacc_build.wacc:.4%}",+ f"Terminal value method used: {result.terminal_value_method}",+ ]+++def _dcf_sensitivity_lines(grid: pd.DataFrame | None) -> list[str]:+ """Return the DCF sensitivity bullet lines from a caller-supplied grid, if any."""+ if grid is None:+ return ["Sensitivity grid not supplied to this export."]+ values = grid.to_numpy(dtype=float)+ finite = values[np.isfinite(values)]+ if finite.size == 0:+ return [+ "Sensitivity grid supplied but every cell is undefined (growth >= "+ "WACC across the entire swept range)."+ ]+ return [+ f"Value-per-share range across the sensitivity grid: "+ f"{finite.min():,.4f} to {finite.max():,.4f} "+ f"({finite.size} of {values.size} cell(s) defined)"+ ]+++def _comps_headline(result: CompsResult) -> list[str]:+ """Return the comps valuation-conclusion bullet lines."""+ lines = [+ f"Target: {result.target_name}",+ f"Calendarisation policy: {result.calendarisation_policy}",+ f"EPS basis: {result.eps_basis}",+ ]+ for name in MULTIPLE_NAMES:+ iv = result.implied_valuations[name]+ if iv.implied_equity_value_by_quantile is None:+ lines.append(f"{name}: no implied valuation (distribution empty)")+ else:+ median = iv.implied_equity_value_by_quantile["median"]+ lines.append(f"{name}: implied equity value at the median peer multiple = {median:,.2f}")+ return lines+++def _comps_sensitivity_lines(result: CompsResult) -> list[str]:+ """Return the comps sensitivity bullet lines: each multiple's peer spread."""+ lines: list[str] = []+ for name in MULTIPLE_NAMES:+ dist = result.distributions[name]+ if dist.median is None:+ lines.append(f"{name}: no usable distribution ({dist.warning})")+ continue+ lines.append(+ f"{name}: peer multiple min {dist.minimum:.2f} / median {dist.median:.2f} / "+ f"max {dist.maximum:.2f}"+ )+ return lines+++def _three_statement_headline(result: ThreeStatementProjection) -> list[str]:+ """Return the three-statement conclusion bullet lines: the final projected period."""+ last = result.periods[-1]+ return [+ f"Projection horizon: {len(result.periods)} period(s)",+ f"Final period revenue: {last.income_statement.revenue:,.2f}",+ f"Final period net income: {last.income_statement.net_income:,.2f}",+ f"Final period ending cash: {last.balance_sheet.cash:,.2f}",+ f"Final period ending revolver balance: {last.balance_sheet.revolver_balance:,.2f}",+ ]+++def _assumption_lines(artifact: ModelArtifact) -> list[str]:+ """Return the "Key Assumptions" bullet lines, or an honest empty-state line."""+ if not artifact.assumptions:+ return ["No caller-supplied Assumption objects were required by this model."]+ return [+ f"{record.assumption.name} = {record.assumption.value!r} ({record.assumption.basis})"+ for record in artifact.assumptions+ ]+++def _gap_lines(artifact: ModelArtifact) -> list[str]:+ """Return the "Data Quality Notes" bullet lines, or an honest empty-state line."""+ lines = list(artifact.excluded) + list(artifact.warnings)+ return lines or ["No exclusions, omissions, or warnings were recorded for this run."]+++def _write_deck_section(text_frame: TextFrame, heading: str, lines: Sequence[str], *, first: bool = False) -> None:+ """Append one heading paragraph plus one bulleted paragraph per line to a text frame."""+ paragraph = text_frame.paragraphs[0] if first else text_frame.add_paragraph()+ paragraph.text = heading+ paragraph.font.bold = True+ paragraph.font.size = Pt(15)+ for line in lines:+ bullet = text_frame.add_paragraph()+ bullet.text = f"• {line}"+ bullet.font.size = Pt(11)+ bullet.level = 1+++def export_summary_deck(+ artifact: ModelArtifact,+ path: str | Path,+ *,+ sensitivity_grid: pd.DataFrame | None = None,+) -> Path:+ """Export a one-slide valuation summary: conclusion, assumptions, sensitivity, gaps.++ Works for any ``model_name``. The same provenance footer required on the+ xlsx exports (input hash, model version, generated-at) is written here+ too -- a slide making an unsourced claim is the same failure as an+ unsourced spreadsheet cell.++ Args:+ artifact: Any :class:`ModelArtifact` (``dcf``, ``comps`` or+ ``three_statement``).+ path: Output ``.pptx`` path. Parent directories are created if absent.+ sensitivity_grid: For a ``dcf`` artifact only, the wacc x growth+ value-per-share grid (e.g. from+ :func:`src.quantlib.valuation.dcf.sensitivity_grid`). If omitted+ on a ``dcf`` artifact, the slide says so explicitly rather than+ guessing a range. Ignored for ``comps``/``three_statement``.++ Returns:+ The written path.+ """+ prs = Presentation()+ slide = prs.slides.add_slide(prs.slide_layouts[6])++ title_box = slide.shapes.add_textbox(Inches(0.4), Inches(0.3), Inches(9.2), Inches(0.6))+ title_box.text_frame.text = f"{artifact.model_name.upper()} Valuation Summary"++ if artifact.model_name == "dcf":+ headline = _dcf_headline(artifact.result)+ sensitivity = _dcf_sensitivity_lines(sensitivity_grid)+ elif artifact.model_name == "comps":+ headline = _comps_headline(artifact.result)+ sensitivity = _comps_sensitivity_lines(artifact.result)+ else:+ headline = _three_statement_headline(artifact.result)+ sensitivity = ["Sensitivity analysis is not defined for a three-statement projection."]++ body = slide.shapes.add_textbox(Inches(0.4), Inches(1.0), Inches(9.2), Inches(5.7))+ text_frame = body.text_frame+ text_frame.word_wrap = True+ _write_deck_section(text_frame, "Valuation Conclusion", headline, first=True)+ _write_deck_section(text_frame, "Key Assumptions", _assumption_lines(artifact))+ _write_deck_section(text_frame, "Sensitivity", sensitivity)+ _write_deck_section(text_frame, "Data Quality Notes", _gap_lines(artifact))++ footer = slide.shapes.add_textbox(Inches(0.4), Inches(6.9), Inches(9.2), Inches(0.5))+ footer.text_frame.text = (+ f"input_hash={artifact.input_hash} | model_version={artifact.model_version} | "+ f"schema_version={artifact.schema_version} | generated_at={artifact.generated_at.isoformat()}"+ )++ out_path = Path(path)+ out_path.parent.mkdir(parents=True, exist_ok=True)+ prs.save(str(out_path))+ return out_pathdiff --git a/agent/src/quantlib/valuation/comps.py b/agent/src/quantlib/valuation/comps.pynew file mode 100644index 000000000..162542f29--- /dev/null+++ b/agent/src/quantlib/valuation/comps.py@@ -0,0 +1,1177 @@+"""Comparable-companies (comps) valuation: EV bridge, calendarisation, multiples.++A comps valuation answers "what is this company worth, given what the market+pays for similar companies" -- by building a multiple (EV/EBITDA, P/E, ...) for+each peer and applying the peer set's distribution to the target's own+financials. Two mistakes make that answer wrong before a single multiple is+even computed, and this module exists to make both of them structurally hard+to commit silently.++1. THE EV BRIDGE+ -----------------+ Enterprise value is not market cap. It is the price a buyer of the WHOLE+ operating business would pay, and every EV multiple's numerator must+ represent that same whole-business claim or it is not comparable to the+ denominator (EBITDA/EBIT/Sales), which is also a whole-business number:++ EV = market_cap + total_debt - cash_and_equivalents+ + minority_interest + preferred_stock - investments_in_associates++ Each sign is explained where it is applied (:func:`enterprise_value`), but+ the shape is: things that are a SENIOR or OUTSIDE claim on the operating+ business are ADDED (debt, minority interest, preferred); things that are+ NOT part of what the operating multiple prices are SUBTRACTED (cash sits+ outside operations, an equity-method stake's earnings sit below the+ operating metrics the multiple's denominator uses). Minority interest and+ preferred stock and associate investments are commonly undisclosed or+ genuinely zero -- this module refuses to guess which, and reports every+ omitted component by name (see ``omitted_components`` on+ :class:`EVBridgeResult`) rather than silently treating "not supplied" as+ "zero". An EV bridge missing minority interest is systematically biased+ LOW, exactly the failure mode the caller must be told about.++2. FISCAL-CALENDAR ALIGNMENT (CALENDARISATION)+ ---------------------------------------------+ A peer with a June fiscal year end and a peer with a December fiscal year+ end do not report over the same twelve months. Comparing their raw+ "latest fiscal year" multiples mixes, e.g., one company's Jul-2024..Jun-2025+ performance against another's Jan-2025..Dec-2025 -- six months of look-ahead+ or look-behind bias baked into a number that LOOKS like an apples-to-apples+ ratio. Two conventions fix this, and this module implements both, but a+ single :func:`run_comps` call uses exactly ONE for every peer and the+ target:++ - ``"ltm"`` (last twelve months): ``last_full_fiscal_year + current_ytd -+ prior_year_ytd``. This is always trailing twelve months ending at+ whatever "as of" date the YTD figures were cut at, REGARDLESS of fiscal+ year end -- it needs no month-weighting because the subtraction of+ ``prior_year_ytd`` already cancels out the seasonal stub.+ - ``"calendar_year"``: blends the fiscal year ending IN the target calendar+ year with the one ending in the NEXT calendar year, weighted by what+ fraction of the calendar year each covers, under the explicit+ simplifying assumption that a fiscal year's flow is spread evenly across+ its twelve months (a company disclosing quarterly seasonality could+ calendarise more precisely than this module does; this module's+ assumption is documented here so nobody mistakes the output for a+ seasonality-aware estimate).++ Mixing the two within one run is refused structurally: ``run_comps`` takes+ one ``calendarisation_policy`` for the whole call, and a peer whose data+ does not carry the fields that policy needs is NOT RUNNABLE (see+ :mod:`.contracts`) rather than silently computed from a partial fit.++3. THE MULTIPLE MATRIX+ ---------------------+ A multiple whose denominator is at or below zero is not a small number or+ a large negative number -- it is not a number at all in the sense a+ valuation multiple needs (a company with negative EBITDA is not "worth+ negative EBITDA times anything"). Every multiple in this module is dropped+ for a peer whenever its OWN denominator is non-positive, and the drop is+ reported by name (:class:`ExcludedMultiple`), not silently absorbed into a+ distribution that would otherwise look like ordinary peer dispersion. Note+ this rule is stated on the DENOMINATOR only, matching the task that+ motivated this module; a peer with a non-positive EV but a positive+ denominator (a net-cash-rich, low-multiple company) still produces a+ negative multiple and is NOT excluded by this rule -- see the note on+ :func:`_compute_multiple`.++ Every multiple's cross-sectional distribution is reported as min / p25 /+ median / p75 / max. The MEDIAN, not the mean, is this module's headline+ statistic and the one used to build the target's implied valuation: a+ comps set is small by construction (rarely more than a handful of true+ peers), and a single outlier peer can drag a mean far off-center while+ barely moving a median. Below :data:`MIN_ROBUST_COMPS` peers, even the+ median is flagged with an explicit warning -- a "median" of one or two+ points is just those points, not a statistic.++Import this module directly (``from src.quantlib.valuation.comps import+run_comps``); see :mod:`src.quantlib.valuation` for why submodules are kept+independently importable.+"""++from __future__ import annotations++from collections.abc import Mapping, Sequence+from dataclasses import dataclass+from types import MappingProxyType++import numpy as np++from src.quantlib.valuation.contracts import (+ MissingInputError,+ ValuationError,+ require_inputs,+ require_positive,+)++__all__ = [+ "CALENDARISATION_POLICIES",+ "EPS_BASES",+ "MULTIPLE_NAMES",+ "MIN_ROBUST_COMPS",+ "FlowMetricPeriods",+ "CalendarisedMetric",+ "EVBridgeResult",+ "PeerCompany",+ "TargetCompany",+ "ExcludedMultiple",+ "PeerMultiples",+ "MultipleDistribution",+ "ImpliedValuation",+ "CompsResult",+ "enterprise_value",+ "equity_value_from_enterprise_value",+ "calendarise_metric",+ "peer_multiple_set",+ "multiple_distribution",+ "implied_valuation",+ "run_comps",+]++#: The two fiscal-calendar alignment conventions this module implements. A+#: single `run_comps` call uses exactly one for every peer and the target --+#: see the module docstring's section 2 for why mixing them is refused.+CALENDARISATION_POLICIES: tuple[str, ...] = ("ltm", "calendar_year")++#: EPS conventions a caller may declare. Not a preference this module has an+#: opinion on -- it exists purely so the basis is an explicit, recorded fact+#: rather than an assumption baked silently into whatever EPS number arrived.+EPS_BASES: tuple[str, ...] = ("gaap", "adjusted")++#: The five multiples this module computes, in the fixed order used for+#: reporting. The first three price Enterprise Value; the last two price+#: equity value directly and never pass through the EV bridge.+MULTIPLE_NAMES: tuple[str, ...] = ("ev_ebitda", "ev_ebit", "ev_sales", "pe", "pb")++#: Which of `MULTIPLE_NAMES` have EV (not equity) as their numerator.+_EV_MULTIPLES: frozenset[str] = frozenset({"ev_ebitda", "ev_ebit", "ev_sales"})++#: Fewest peers a cross-sectional median needs before it is a statistic+#: rather than an arbitrary pick from 1-2 data points. Below this the+#: distribution is still computed (it is not "wrong"), but every result+#: carries an explicit warning saying so.+MIN_ROBUST_COMPS: int = 3++#: Names of the EV bridge's optional line items, in the order they appear in+#: the formula. A caller who does not supply one of these is NOT asserting it+#: is zero -- see `EVBridgeResult.omitted_components`.+_EV_BRIDGE_OPTIONAL_FIELDS: tuple[str, ...] = (+ "minority_interest",+ "preferred_stock",+ "investments_in_associates",+)+++@dataclass(frozen=True)+class FlowMetricPeriods:+ """Raw fiscal-period figures for one flow metric (EBITDA, EBIT, Sales, ...).++ Which fields beyond `last_full_fiscal_year` are required depends on which+ calendarisation policy a run uses -- both need not be populated at once;+ see :func:`calendarise_metric`.++ Attributes:+ fiscal_year_end_month: Month (1-12) the company's fiscal year ends in.+ last_full_fiscal_year: Value for the most recently COMPLETED fiscal+ year. Used by both policies: it is the anchor of the LTM formula,+ and the "fiscal year ending in the earlier calendar year" leg of+ the calendar-year blend.+ current_year_to_date: Value for the stub period since the CURRENT+ fiscal year began, through the analysis "as of" date. Required+ for the `"ltm"` policy.+ prior_year_to_date: Value for the SAME stub period one year earlier+ -- same start month, same length. Required for the `"ltm"`+ policy.+ next_full_fiscal_year: Value for the fiscal year immediately AFTER+ `last_full_fiscal_year` (ending one calendar year later).+ Required for the `"calendar_year"` policy whenever+ `fiscal_year_end_month != 12` -- a December fiscal year end needs+ no second year, because month-weighting already resolves to 100%+ of `last_full_fiscal_year`.++ Raises:+ ValuationError: If `fiscal_year_end_month` is not in 1..12.+ """++ fiscal_year_end_month: int+ last_full_fiscal_year: float+ current_year_to_date: float | None = None+ prior_year_to_date: float | None = None+ next_full_fiscal_year: float | None = None++ def __post_init__(self) -> None:+ if not 1 <= int(self.fiscal_year_end_month) <= 12:+ raise ValuationError(+ "comps.FlowMetricPeriods: fiscal_year_end_month must be 1-12, "+ f"got {self.fiscal_year_end_month!r}"+ )+++@dataclass(frozen=True)+class CalendarisedMetric:+ """One flow metric after fiscal-calendar alignment.++ Attributes:+ policy: Which convention produced `value` -- `"ltm"` or+ `"calendar_year"`.+ value: The aligned metric value.+ fiscal_year_end_month: Carried through from the input, for audit.+ weights: For `"calendar_year"`, the `(early_fy_weight,+ late_fy_weight)` used to blend the two fiscal years. `None` for+ `"ltm"`, which has no month-weighting step.+ """++ policy: str+ value: float+ fiscal_year_end_month: int+ weights: tuple[float, float] | None+++def calendarise_metric(+ periods: FlowMetricPeriods,+ policy: str,+ *,+ metric_name: str,+ company_name: str,+) -> CalendarisedMetric:+ """Align one company's flow metric onto a comparable twelve-month footing.++ See the module docstring, section 2, for why this step exists and why+ the two policies are not interchangeable within one comps run.++ Args:+ periods: The company's raw fiscal-period figures for this metric.+ policy: `"ltm"` or `"calendar_year"`.+ metric_name: Name of the metric being aligned (e.g. `"ebitda"`), used+ only for error messages.+ company_name: Name of the company being aligned, used only for error+ messages.++ Returns:+ The aligned :class:`CalendarisedMetric`.++ Raises:+ ValuationError: If `policy` is not one of `CALENDARISATION_POLICIES`.+ MissingInputError: If `periods` lacks a field this policy needs.+ """+ if policy not in CALENDARISATION_POLICIES:+ raise ValuationError(+ f"comps.calendarise_metric: unknown policy {policy!r}, must be "+ f"one of {CALENDARISATION_POLICIES}"+ )+ model = f"comps.calendarise_metric[{company_name}.{metric_name}:{policy}]"++ if policy == "ltm":+ require_inputs(+ {+ "last_full_fiscal_year": periods.last_full_fiscal_year,+ "current_year_to_date": periods.current_year_to_date,+ "prior_year_to_date": periods.prior_year_to_date,+ },+ ("last_full_fiscal_year", "current_year_to_date", "prior_year_to_date"),+ model,+ )+ value = (+ periods.last_full_fiscal_year+ + periods.current_year_to_date+ - periods.prior_year_to_date+ )+ return CalendarisedMetric(+ policy="ltm",+ value=value,+ fiscal_year_end_month=periods.fiscal_year_end_month,+ weights=None,+ )++ # policy == "calendar_year"+ month = periods.fiscal_year_end_month+ if month == 12:+ require_inputs(+ {"last_full_fiscal_year": periods.last_full_fiscal_year},+ ("last_full_fiscal_year",),+ model,+ )+ return CalendarisedMetric(+ policy="calendar_year",+ value=periods.last_full_fiscal_year,+ fiscal_year_end_month=month,+ weights=(1.0, 0.0),+ )++ require_inputs(+ {+ "last_full_fiscal_year": periods.last_full_fiscal_year,+ "next_full_fiscal_year": periods.next_full_fiscal_year,+ },+ ("last_full_fiscal_year", "next_full_fiscal_year"),+ model,+ )+ weight_early = month / 12.0+ weight_late = 1.0 - weight_early+ value = weight_early * periods.last_full_fiscal_year + weight_late * periods.next_full_fiscal_year+ return CalendarisedMetric(+ policy="calendar_year",+ value=value,+ fiscal_year_end_month=month,+ weights=(weight_early, weight_late),+ )+++@dataclass(frozen=True)+class EVBridgeResult:+ """Enterprise-value bridge for one company, walked in one direction.++ Attributes:+ direction: `"equity_to_ev"` (a known market cap produces EV) or+ `"ev_to_equity"` (a known EV, e.g. one implied by a peer+ multiple, produces an implied equity value). Lets a report tell+ at a glance which side of the bridge was the input.+ equity_value: The equity-side value -- `market_cap` on the forward+ direction, the implied equity value on the reverse direction.+ enterprise_value: The enterprise-side value -- computed on the+ forward direction, supplied as an input on the reverse direction.+ total_debt: Debt component used.+ cash_and_equivalents: Cash component used.+ minority_interest: Component used, or `None` if not supplied.+ preferred_stock: Component used, or `None` if not supplied.+ investments_in_associates: Component used, or `None` if not supplied.+ omitted_components: Names, among `minority_interest`,+ `preferred_stock`, `investments_in_associates`, that were NOT+ supplied. Non-empty means the bridge value excludes their+ (unknown) contribution and is biased in the direction of the+ missing sign -- e.g. an omitted `minority_interest` means+ `enterprise_value` is understated relative to the true bridge.+ """++ direction: str+ equity_value: float+ enterprise_value: float+ total_debt: float+ cash_and_equivalents: float+ minority_interest: float | None+ preferred_stock: float | None+ investments_in_associates: float | None+ omitted_components: tuple[str, ...]+++def _bridge_delta(+ total_debt: float,+ cash_and_equivalents: float,+ minority_interest: float | None,+ preferred_stock: float | None,+ investments_in_associates: float | None,+) -> tuple[float, tuple[str, ...]]:+ """Compute the EV-minus-equity-value delta and which optional items were omitted.++ The delta is added to equity value to reach EV, and subtracted from EV to+ reach equity value -- the two public bridge functions differ only in+ which side is the known input.++ Returns:+ `(delta, omitted_components)`.+ """+ omitted: list[str] = []+ total = total_debt - cash_and_equivalents+ for name, value in (+ ("minority_interest", minority_interest),+ ("preferred_stock", preferred_stock),+ ("investments_in_associates", investments_in_associates),+ ):+ if value is None:+ omitted.append(name)+ continue+ sign = -1.0 if name == "investments_in_associates" else 1.0+ total += sign * value+ return total, tuple(omitted)+++def enterprise_value(+ *,+ market_cap: float,+ total_debt: float,+ cash_and_equivalents: float,+ minority_interest: float | None = None,+ preferred_stock: float | None = None,+ investments_in_associates: float | None = None,+) -> EVBridgeResult:+ """Bridge a known equity market value to enterprise value.++ EV = market_cap + total_debt - cash_and_equivalents+ + minority_interest + preferred_stock - investments_in_associates++ Sign of each term, in the direction FROM equity value TO enterprise value:++ - `total_debt` (+): an acquirer of the whole enterprise assumes its debt+ on top of paying for the equity -- debtholders are repaid ahead of+ equity, so their claim is an ADDITIONAL cost layered on market cap.+ - `cash_and_equivalents` (-): cash on the balance sheet is not part of+ the OPERATING business the multiple's denominator (EBITDA/EBIT/Sales)+ measures -- it funds part of the purchase price (an acquirer nets it+ against assumed debt, or simply pockets it), so it is subtracted back+ out of what the operating multiple is pricing.+ - `minority_interest` (+): a majority-owned, consolidated subsidiary+ contributes 100% of its EBITDA/EBIT/revenue to the parent's+ consolidated figures (consolidation accounting backs the minority+ holders' share out only at the net-income line, not the operating+ lines). EV must therefore also represent 100% of that subsidiary's+ value -- including the minority claim -- or EV and the operating+ metric price different slices of the same business.+ - `preferred_stock` (+): preferred shares rank senior to common equity+ but junior to debt. `market_cap` prices only the common shares, so the+ preferred claim is an additional cost an acquirer of the whole+ enterprise must also cover, exactly like debt.+ - `investments_in_associates` (-): an equity-method stake (typically+ 20-50% owned, not consolidated) contributes only a single "equity in+ earnings" line BELOW the operating metrics -- its own revenue/EBITDA/+ EBIT are NOT included in the consolidated numbers the multiple's+ denominator uses. Its value is therefore not part of what the+ operating multiple prices, and is backed out of EV the same way cash+ is.++ `minority_interest`, `preferred_stock` and `investments_in_associates`+ are genuinely optional -- many companies have none of one or more of+ them. Passing `None` (the default) means "not supplied", NOT "zero": the+ bridge still computes (using no contribution from that term), but the+ omission is named in `EVBridgeResult.omitted_components` so nobody reads+ the result as a complete bridge when it is not. Pass `0.0` explicitly to+ assert a confirmed-zero line item.++ Args:+ market_cap: Equity market value (share price x shares outstanding).+ total_debt: Interest-bearing debt, all maturities.+ cash_and_equivalents: Cash and short-term investments.+ minority_interest: Book or fair value of minority (non-controlling)+ interests in consolidated subsidiaries, or `None` if not+ supplied.+ preferred_stock: Value of preferred equity outstanding, or `None` if+ not supplied.+ investments_in_associates: Value of equity-method (non-consolidated)+ investments, or `None` if not supplied.++ Returns:+ The :class:`EVBridgeResult`, `direction="equity_to_ev"`.++ Raises:+ MissingInputError: If `market_cap`, `total_debt` or+ `cash_and_equivalents` is absent.+ """+ require_inputs(+ {+ "market_cap": market_cap,+ "total_debt": total_debt,+ "cash_and_equivalents": cash_and_equivalents,+ },+ ("market_cap", "total_debt", "cash_and_equivalents"),+ "comps.enterprise_value",+ )+ delta, omitted = _bridge_delta(+ total_debt, cash_and_equivalents, minority_interest, preferred_stock, investments_in_associates+ )+ ev = float(market_cap) + delta+ return EVBridgeResult(+ direction="equity_to_ev",+ equity_value=float(market_cap),+ enterprise_value=ev,+ total_debt=float(total_debt),+ cash_and_equivalents=float(cash_and_equivalents),+ minority_interest=minority_interest,+ preferred_stock=preferred_stock,+ investments_in_associates=investments_in_associates,+ omitted_components=omitted,+ )+++def equity_value_from_enterprise_value(+ *,+ enterprise_value: float,+ total_debt: float,+ cash_and_equivalents: float,+ minority_interest: float | None = None,+ preferred_stock: float | None = None,+ investments_in_associates: float | None = None,+) -> EVBridgeResult:+ """Walk the EV bridge backward: a known EV to an implied equity value.++ This is the exact inverse of :func:`enterprise_value` -- same signs, same+ omission handling -- used to turn a target's IMPLIED enterprise value+ (peer multiple x target metric) into an implied equity value, using the+ TARGET's own capital structure:++ equity_value = enterprise_value - total_debt + cash_and_equivalents+ - minority_interest - preferred_stock+ + investments_in_associates++ Args:+ enterprise_value: A known or implied enterprise value.+ total_debt: Target's interest-bearing debt.+ cash_and_equivalents: Target's cash and short-term investments.+ minority_interest: Target's minority interest, or `None` if not+ supplied.+ preferred_stock: Target's preferred equity, or `None` if not+ supplied.+ investments_in_associates: Target's equity-method investments, or+ `None` if not supplied.++ Returns:+ The :class:`EVBridgeResult`, `direction="ev_to_equity"`.++ Raises:+ MissingInputError: If `enterprise_value`, `total_debt` or+ `cash_and_equivalents` is absent.+ """+ require_inputs(+ {+ "enterprise_value": enterprise_value,+ "total_debt": total_debt,+ "cash_and_equivalents": cash_and_equivalents,+ },+ ("enterprise_value", "total_debt", "cash_and_equivalents"),+ "comps.equity_value_from_enterprise_value",+ )+ delta, omitted = _bridge_delta(+ total_debt, cash_and_equivalents, minority_interest, preferred_stock, investments_in_associates+ )+ equity = float(enterprise_value) - delta+ return EVBridgeResult(+ direction="ev_to_equity",+ equity_value=equity,+ enterprise_value=float(enterprise_value),+ total_debt=float(total_debt),+ cash_and_equivalents=float(cash_and_equivalents),+ minority_interest=minority_interest,+ preferred_stock=preferred_stock,+ investments_in_associates=investments_in_associates,+ omitted_components=omitted,+ )+++def _require_name(name: str, model: str) -> str:+ """Reject a blank company name -- every report keys off it."""+ if not isinstance(name, str) or not name.strip():+ raise ValuationError(f"{model}: name is required and cannot be blank, got {name!r}")+ return name+++def _require_eps_basis(eps_basis: str, model: str) -> str:+ """Reject an EPS basis that is not one of the two this module recognises."""+ if eps_basis not in EPS_BASES:+ raise ValuationError(+ f"{model}: eps_basis must be one of {EPS_BASES}, got {eps_basis!r}"+ )+ return eps_basis+++@dataclass(frozen=True)+class PeerCompany:+ """One comparable company's raw inputs for the EV bridge and multiple matrix.++ Attributes:+ name: Identifier (ticker or short name), used in every report and+ exclusion message for this peer.+ market_cap: Equity market value.+ total_debt: Interest-bearing debt.+ cash_and_equivalents: Cash and short-term investments.+ ebitda: Fiscal-period figures for EBITDA.+ ebit: Fiscal-period figures for EBIT.+ revenue: Fiscal-period figures for revenue/sales.+ diluted_eps: Fiscal-period figures for diluted EPS.+ price_per_share: Current share price, paired with `diluted_eps` to+ form this peer's own P/E.+ book_value_of_equity: Latest reported book value of common equity (a+ balance-sheet snapshot, not a flow -- it is used as-is, never+ calendarised).+ eps_basis: `"gaap"` or `"adjusted"` -- must match every other peer's+ and the target's basis within one `run_comps` call (see+ `run_comps`).+ minority_interest: Optional EV-bridge component; `None` means not+ supplied (see `enterprise_value`).+ preferred_stock: Optional EV-bridge component; `None` means not+ supplied.+ investments_in_associates: Optional EV-bridge component; `None`+ means not supplied.+ """++ name: str+ market_cap: float+ total_debt: float+ cash_and_equivalents: float+ ebitda: FlowMetricPeriods+ ebit: FlowMetricPeriods+ revenue: FlowMetricPeriods+ diluted_eps: FlowMetricPeriods+ price_per_share: float+ book_value_of_equity: float+ eps_basis: str+ minority_interest: float | None = None+ preferred_stock: float | None = None+ investments_in_associates: float | None = None++ def __post_init__(self) -> None:+ _require_name(self.name, "comps.PeerCompany")+ _require_eps_basis(self.eps_basis, "comps.PeerCompany")+++@dataclass(frozen=True)+class TargetCompany:+ """The company being valued: its own fundamentals and capital structure.++ A target does NOT carry `market_cap` or `price_per_share` -- those are+ what a comps run estimates, not an input to it. It DOES carry its own+ capital structure (`total_debt`, `cash_and_equivalents`, and the three+ optional EV-bridge items), because those are needed to walk an EV+ multiple's implied enterprise value back down to an implied equity value+ via `equity_value_from_enterprise_value`.++ Attributes:+ name: Identifier, used in every report for this run.+ total_debt: Target's interest-bearing debt.+ cash_and_equivalents: Target's cash and short-term investments.+ ebitda: Target's fiscal-period figures for EBITDA.+ ebit: Target's fiscal-period figures for EBIT.+ revenue: Target's fiscal-period figures for revenue/sales.+ diluted_eps: Target's fiscal-period figures for diluted EPS.+ diluted_shares_outstanding: Target's diluted share count, used with+ the calendarised `diluted_eps` to recover an aggregate+ "net income to diluted common" figure so a peer P/E (a per-share+ ratio) can be applied to produce an aggregate implied equity+ value rather than a per-share price.+ book_value_of_equity: Target's latest reported book value of common+ equity.+ eps_basis: `"gaap"` or `"adjusted"` -- must match every peer's basis.+ minority_interest: Optional EV-bridge component; `None` means not+ supplied.+ preferred_stock: Optional EV-bridge component; `None` means not+ supplied.+ investments_in_associates: Optional EV-bridge component; `None`+ means not supplied.++ Raises:+ ValuationError: If `diluted_shares_outstanding` is not a finite+ positive number, or `eps_basis` is not recognised, or `name` is+ blank.+ """++ name: str+ total_debt: float+ cash_and_equivalents: float+ ebitda: FlowMetricPeriods+ ebit: FlowMetricPeriods+ revenue: FlowMetricPeriods+ diluted_eps: FlowMetricPeriods+ diluted_shares_outstanding: float+ book_value_of_equity: float+ eps_basis: str+ minority_interest: float | None = None+ preferred_stock: float | None = None+ investments_in_associates: float | None = None++ def __post_init__(self) -> None:+ _require_name(self.name, "comps.TargetCompany")+ _require_eps_basis(self.eps_basis, "comps.TargetCompany")+ require_positive(self.diluted_shares_outstanding, "diluted_shares_outstanding", "comps.TargetCompany")+++@dataclass(frozen=True)+class ExcludedMultiple:+ """One peer dropped from one multiple's statistics.++ Attributes:+ peer_name: Which comp was dropped.+ multiple_name: Which multiple (one of `MULTIPLE_NAMES`).+ denominator_value: The denominator at the time of exclusion.+ numerator_value: The numerator at the time of exclusion.+ reason: ``"non_positive_denominator"`` or ``"non_positive_numerator"``.+ """++ peer_name: str+ multiple_name: str+ denominator_value: float+ numerator_value: float = 0.0+ reason: str = "non_positive_denominator"+++def _compute_multiple(+ numerator: float, denominator: float, *, peer_name: str, multiple_name: str+) -> tuple[float | None, ExcludedMultiple | None]:+ """Compute one peer's multiple, or explain why it is excluded.++ **Both sides are checked, and that is deliberate.**++ A non-positive DENOMINATOR (a loss-making peer's EBITDA) makes the ratio+ not a valuation multiple at all. So does a non-positive NUMERATOR: a+ net-cash-rich company can have a negative enterprise value while its EBITDA+ is perfectly healthy, and ``EV/EBITDA = -3.2x`` is not a cheap company, it+ is a company the multiple cannot describe. Letting either through drags the+ median toward a number no peer actually trades at.++ An earlier version guarded the denominator only and documented the gap as+ "a one-sided guarantee inherited from the spec". A guarantee a reader has to+ read the source to discover is not one; both sides are now excluded and+ ``ExcludedMultiple.reason`` says which side triggered it.++ Args:+ numerator: Multiple numerator (EV, price, market cap).+ denominator: Multiple denominator (EBITDA, EBIT, revenue, EPS, book).+ peer_name: For the exclusion record.+ multiple_name: For the exclusion record.++ Returns:+ ``(value, None)`` when both sides are positive, else+ ``(None, ExcludedMultiple(...))`` naming the side that failed.+ """+ if denominator <= 0.0:+ return None, ExcludedMultiple(+ peer_name=peer_name,+ multiple_name=multiple_name,+ denominator_value=denominator,+ numerator_value=numerator,+ reason="non_positive_denominator",+ )+ if numerator <= 0.0:+ return None, ExcludedMultiple(+ peer_name=peer_name,+ multiple_name=multiple_name,+ denominator_value=denominator,+ numerator_value=numerator,+ reason="non_positive_numerator",+ )+ return numerator / denominator, None+++@dataclass(frozen=True)+class PeerMultiples:+ """One peer's EV bridge, calendarised metrics, and full multiple set.++ Attributes:+ name: The peer's name.+ ev_bridge: This peer's `EVBridgeResult`.+ calendarised_ebitda: EBITDA after fiscal-calendar alignment.+ calendarised_ebit: EBIT after fiscal-calendar alignment.+ calendarised_revenue: Revenue after fiscal-calendar alignment.+ calendarised_diluted_eps: Diluted EPS after fiscal-calendar alignment.+ ev_ebitda: This peer's EV/EBITDA, or `None` if excluded.+ ev_ebit: This peer's EV/EBIT, or `None` if excluded.+ ev_sales: This peer's EV/Sales, or `None` if excluded.+ pe: This peer's P/E, or `None` if excluded.+ pb: This peer's P/B, or `None` if excluded.+ exclusions: Every multiple excluded for this peer, and why.+ """++ name: str+ ev_bridge: EVBridgeResult+ calendarised_ebitda: CalendarisedMetric+ calendarised_ebit: CalendarisedMetric+ calendarised_revenue: CalendarisedMetric+ calendarised_diluted_eps: CalendarisedMetric+ ev_ebitda: float | None+ ev_ebit: float | None+ ev_sales: float | None+ pe: float | None+ pb: float | None+ exclusions: tuple[ExcludedMultiple, ...]+++def peer_multiple_set(peer: PeerCompany, policy: str) -> PeerMultiples:+ """Build one peer's EV bridge, calendarised metrics and full multiple set.++ Args:+ peer: The peer's raw inputs.+ policy: `"ltm"` or `"calendar_year"` -- see `calendarise_metric`.++ Returns:+ The peer's :class:`PeerMultiples`.++ Raises:+ MissingInputError: If `peer`'s data lacks a field the chosen policy+ needs.+ """+ ev_bridge = enterprise_value(+ market_cap=peer.market_cap,+ total_debt=peer.total_debt,+ cash_and_equivalents=peer.cash_and_equivalents,+ minority_interest=peer.minority_interest,+ preferred_stock=peer.preferred_stock,+ investments_in_associates=peer.investments_in_associates,+ )+ ebitda = calendarise_metric(peer.ebitda, policy, metric_name="ebitda", company_name=peer.name)+ ebit = calendarise_metric(peer.ebit, policy, metric_name="ebit", company_name=peer.name)+ revenue = calendarise_metric(peer.revenue, policy, metric_name="revenue", company_name=peer.name)+ eps = calendarise_metric(peer.diluted_eps, policy, metric_name="diluted_eps", company_name=peer.name)++ exclusions: list[ExcludedMultiple] = []+ values: dict[str, float | None] = {}+ for multiple_name, numerator, denominator in (+ ("ev_ebitda", ev_bridge.enterprise_value, ebitda.value),+ ("ev_ebit", ev_bridge.enterprise_value, ebit.value),+ ("ev_sales", ev_bridge.enterprise_value, revenue.value),+ ("pe", peer.price_per_share, eps.value),+ ("pb", peer.market_cap, peer.book_value_of_equity),+ ):+ value, excluded = _compute_multiple(+ numerator, denominator, peer_name=peer.name, multiple_name=multiple_name+ )+ values[multiple_name] = value+ if excluded is not None:+ exclusions.append(excluded)++ return PeerMultiples(+ name=peer.name,+ ev_bridge=ev_bridge,+ calendarised_ebitda=ebitda,+ calendarised_ebit=ebit,+ calendarised_revenue=revenue,+ calendarised_diluted_eps=eps,+ ev_ebitda=values["ev_ebitda"],+ ev_ebit=values["ev_ebit"],+ ev_sales=values["ev_sales"],+ pe=values["pe"],+ pb=values["pb"],+ exclusions=tuple(exclusions),+ )+++@dataclass(frozen=True)+class MultipleDistribution:+ """Cross-sectional distribution of one multiple across the included peers.++ Attributes:+ name: Which multiple (one of `MULTIPLE_NAMES`).+ included: `{peer_name: value}` for peers whose denominator was+ positive.+ excluded: Peers dropped from this multiple, and why. An empty tuple+ IS the report "nobody was excluded" -- it is always present, not+ omitted when empty.+ minimum: Smallest included value, or `None` if `included` is empty.+ p25: 25th percentile (linear interpolation), or `None`.+ median: 50th percentile, or `None`. The headline statistic this+ module uses for implied valuation -- see module docstring,+ section 3, for why median rather than mean.+ p75: 75th percentile, or `None`.+ maximum: Largest included value, or `None`.+ warning: Set when `included` has fewer than `MIN_ROBUST_COMPS`+ peers (including zero), explaining why the statistics above are+ not, or cannot be, robust. `None` when the sample is adequate.+ """++ name: str+ included: Mapping[str, float]+ excluded: tuple[ExcludedMultiple, ...]+ minimum: float | None+ p25: float | None+ median: float | None+ p75: float | None+ maximum: float | None+ warning: str | None+++def multiple_distribution(name: str, peer_multiples: Sequence[PeerMultiples]) -> MultipleDistribution:+ """Build one multiple's cross-sectional distribution across a peer set.++ Args:+ name: Which multiple, one of `MULTIPLE_NAMES`.+ peer_multiples: Every peer's already-computed `PeerMultiples`.++ Returns:+ The :class:`MultipleDistribution` for `name`.+ """+ included: dict[str, float] = {}+ excluded: list[ExcludedMultiple] = []+ for peer in peer_multiples:+ value = getattr(peer, name)+ if value is None:+ excluded.extend(exc for exc in peer.exclusions if exc.multiple_name == name)+ else:+ included[peer.name] = value++ n = len(included)+ if n == 0:+ warning = (+ f"{name}: all {len(peer_multiples)} peer(s) were excluded (non-positive "+ "denominator) -- no min/p25/median/p75/max can be computed"+ )+ return MultipleDistribution(+ name=name,+ included=MappingProxyType(included),+ excluded=tuple(excluded),+ minimum=None,+ p25=None,+ median=None,+ p75=None,+ maximum=None,+ warning=warning,+ )++ values = np.asarray(sorted(included.values()), dtype=float)+ warning = None+ if n < MIN_ROBUST_COMPS:+ warning = (+ f"{name}: only {n} peer(s) contribute to this distribution (fewer than "+ f"{MIN_ROBUST_COMPS}) -- a median of {n} point(s) is just the input(s) "+ "themselves, not a robust cross-sectional statistic"+ )++ return MultipleDistribution(+ name=name,+ included=MappingProxyType(included),+ excluded=tuple(excluded),+ minimum=float(values[0]),+ p25=float(np.percentile(values, 25)),+ median=float(np.percentile(values, 50)),+ p75=float(np.percentile(values, 75)),+ maximum=float(values[-1]),+ warning=warning,+ )+++@dataclass(frozen=True)+class ImpliedValuation:+ """The target's implied value range from one multiple's peer distribution.++ Attributes:+ multiple_name: Which multiple (one of `MULTIPLE_NAMES`).+ is_ev_multiple: Whether this multiple's numerator is enterprise+ value (`ev_ebitda`/`ev_ebit`/`ev_sales`) rather than equity value+ (`pe`/`pb`).+ target_metric_value: The target's own metric multiplied against the+ peer distribution -- calendarised EBITDA/EBIT/Revenue for the EV+ multiples, book value of equity for `pb`, and calendarised+ diluted EPS x diluted shares outstanding (an aggregate+ "net income to diluted common" figure) for `pe`.+ implied_ev_by_quantile: `{"minimum"/"p25"/"median"/"p75"/"maximum":+ implied enterprise value}`, one entry per quantile of the peer+ distribution x `target_metric_value`. `None` for `pe`/`pb`,+ which imply equity value directly and never pass through an EV+ bridge. Also `None` when the source distribution had zero+ included peers.+ implied_equity_value_by_quantile: Same quantile keys, implied equity+ value. For the EV multiples this is `implied_ev_by_quantile`+ walked back down through the TARGET's own EV bridge (see+ `equity_value_from_enterprise_value`); for `pe`/`pb` it is+ `target_metric_value * multiple` directly. `None` when the+ source distribution had zero included peers.+ warning: Propagated from the underlying `MultipleDistribution`.+ """++ multiple_name: str+ is_ev_multiple: bool+ target_metric_value: float+ implied_ev_by_quantile: Mapping[str, float] | None+ implied_equity_value_by_quantile: Mapping[str, float] | None+ warning: str | None+++_QUANTILE_FIELDS: tuple[str, ...] = ("minimum", "p25", "median", "p75", "maximum")+++def implied_valuation(+ multiple_name: str,+ distribution: MultipleDistribution,+ target: TargetCompany,+ calendarised_target: Mapping[str, CalendarisedMetric],+) -> ImpliedValuation:+ """Project one multiple's peer distribution onto the target's own metric.++ Args:+ multiple_name: Which multiple, one of `MULTIPLE_NAMES`.+ distribution: That multiple's peer `MultipleDistribution`.+ target: The target company (for capital structure and share count).+ calendarised_target: `{"ebitda"/"ebit"/"revenue"/"diluted_eps":+ CalendarisedMetric}` -- the target's own metrics, aligned with+ the same policy as the peer set.++ Returns:+ The target's :class:`ImpliedValuation` for `multiple_name`.+ """+ is_ev = multiple_name in _EV_MULTIPLES++ if multiple_name == "pb":+ target_metric_value = target.book_value_of_equity+ elif multiple_name == "pe":+ target_metric_value = (+ calendarised_target["diluted_eps"].value * target.diluted_shares_outstanding+ )+ else:+ source_key = {"ev_ebitda": "ebitda", "ev_ebit": "ebit", "ev_sales": "revenue"}[multiple_name]+ target_metric_value = calendarised_target[source_key].value++ if distribution.median is None:+ return ImpliedValuation(+ multiple_name=multiple_name,+ is_ev_multiple=is_ev,+ target_metric_value=target_metric_value,+ implied_ev_by_quantile=None,+ implied_equity_value_by_quantile=None,+ warning=distribution.warning,+ )++ quantiles = {field: getattr(distribution, field) for field in _QUANTILE_FIELDS}++ if is_ev:+ implied_ev = {label: multiple * target_metric_value for label, multiple in quantiles.items()}+ implied_equity = {+ label: equity_value_from_enterprise_value(+ enterprise_value=ev,+ total_debt=target.total_debt,+ cash_and_equivalents=target.cash_and_equivalents,+ minority_interest=target.minority_interest,+ preferred_stock=target.preferred_stock,+ investments_in_associates=target.investments_in_associates,+ ).equity_value+ for label, ev in implied_ev.items()+ }+ return ImpliedValuation(+ multiple_name=multiple_name,+ is_ev_multiple=True,+ target_metric_value=target_metric_value,+ implied_ev_by_quantile=MappingProxyType(implied_ev),+ implied_equity_value_by_quantile=MappingProxyType(implied_equity),+ warning=distribution.warning,+ )++ implied_equity = {label: multiple * target_metric_value for label, multiple in quantiles.items()}+ return ImpliedValuation(+ multiple_name=multiple_name,+ is_ev_multiple=False,+ target_metric_value=target_metric_value,+ implied_ev_by_quantile=None,+ implied_equity_value_by_quantile=MappingProxyType(implied_equity),+ warning=distribution.warning,+ )+++@dataclass(frozen=True)+class CompsResult:+ """Full output of one comparable-companies run: one target against N peers.++ Attributes:+ target_name: The target company's name.+ calendarisation_policy: `"ltm"` or `"calendar_year"` -- the ONE+ convention used for every peer and the target in this run (see+ module docstring, section 2).+ eps_basis: `"gaap"` or `"adjusted"` -- the ONE EPS convention shared+ by every peer's P/E and the target's implied P/E valuation.+ peer_multiples: Every peer's `PeerMultiples`, in the order supplied.+ distributions: `{multiple_name: MultipleDistribution}` for all five+ multiples in `MULTIPLE_NAMES`.+ implied_valuations: `{multiple_name: ImpliedValuation}` for all five+ multiples.+ warnings: Every small-sample / zero-peer warning raised anywhere in+ this run, so a caller reading only `warnings` still sees them+ without walking every distribution.+ """++ target_name: str+ calendarisation_policy: str+ eps_basis: str+ peer_multiples: tuple[PeerMultiples, ...]+ distributions: Mapping[str, MultipleDistribution]+ implied_valuations: Mapping[str, ImpliedValuation]+ warnings: tuple[str, ...]+++def run_comps(+ target: TargetCompany,+ peers: Sequence[PeerCompany],+ *,+ calendarisation_policy: str,+) -> CompsResult:+ """Run a full comparable-companies valuation: EV bridge, multiples, implied range.++ Args:+ target: The company being valued.+ peers: The comparable set. Must be non-empty -- see `Raises`. Fewer+ than `MIN_ROBUST_COMPS` peers still runs, but every distribution+ (and the top-level `warnings`) carries an explicit small-sample+ warning.+ calendarisation_policy: `"ltm"` or `"calendar_year"`, applied to+ every peer and the target -- see module docstring, section 2.++ Returns:+ The full :class:`CompsResult`.++ Raises:+ MissingInputError: If `peers` is empty -- with no comparable+ companies at all there is nothing to build a multiple from, so+ the run is not runnable, the same as any other missing required+ input (see :mod:`.contracts`). This is distinct from the+ boundary case where peers were supplied but every one of them+ was later excluded from a given multiple by its own non-positive+ denominator -- that case returns a normal `CompsResult` whose+ `distributions[name]` is empty and carries a warning, because+ the peers themselves were not missing, only their multiples were+ not computable.+ ValuationError: If `calendarisation_policy` is not recognised, if+ two peers share a name, or if peers/target do not all declare+ the same `eps_basis` (mixing GAAP and adjusted EPS across the+ comp set would skew the P/E distribution by whatever one-time+ items the adjustment removes, the same kind of silent distortion+ the calendarisation-policy rule exists to prevent).+ MissingInputError: (propagated from `calendarise_metric`) if any+ peer's or the target's fiscal-period data lacks a field+ `calendarisation_policy` needs.+ """+ if calendarisation_policy not in CALENDARISATION_POLICIES:+ raise ValuationError(+ f"comps.run_comps: unknown calendarisation_policy {calendarisation_policy!r}, "+ f"must be one of {CALENDARISATION_POLICIES}"+ )+ if len(peers) == 0:+ raise MissingInputError(("peers",), "comps.run_comps")++ names = [peer.name for peer in peers]+ if len(set(names)) != len(names):+ raise ValuationError(f"comps.run_comps: duplicate peer names in {names}")++ all_bases = {peer.eps_basis for peer in peers} | {target.eps_basis}+ if len(all_bases) > 1:+ raise ValuationError(+ "comps.run_comps: mixed eps_basis across the comp set "+ f"{sorted(all_bases)} -- every peer and the target must declare the "+ "same EPS basis, or the P/E distribution mixes GAAP and adjusted "+ "earnings"+ )++ peer_multiples = tuple(peer_multiple_set(peer, calendarisation_policy) for peer in peers)+ distributions = {+ name: multiple_distribution(name, peer_multiples) for name in MULTIPLE_NAMES+ }++ calendarised_target = {+ "ebitda": calendarise_metric(+ target.ebitda, calendarisation_policy, metric_name="ebitda", company_name=target.name+ ),+ "ebit": calendarise_metric(+ target.ebit, calendarisation_policy, metric_name="ebit", company_name=target.name+ ),+ "revenue": calendarise_metric(+ target.revenue, calendarisation_policy, metric_name="revenue", company_name=target.name+ ),+ "diluted_eps": calendarise_metric(+ target.diluted_eps, calendarisation_policy, metric_name="diluted_eps", company_name=target.name+ ),+ }++ implied = {+ name: implied_valuation(name, distributions[name], target, calendarised_target)+ for name in MULTIPLE_NAMES+ }++ warnings = tuple(+ distributions[name].warning for name in MULTIPLE_NAMES if distributions[name].warning is not None+ )+ if len(peers) < MIN_ROBUST_COMPS:+ warnings = (+ f"comps.run_comps: only {len(peers)} peer(s) supplied (fewer than "+ f"{MIN_ROBUST_COMPS}) -- every multiple in this run is built from a "+ "sample too small for its median to be a robust statistic",+ ) + warnings++ return CompsResult(+ target_name=target.name,+ calendarisation_policy=calendarisation_policy,+ eps_basis=target.eps_basis,+ peer_multiples=peer_multiples,+ distributions=MappingProxyType(distributions),+ implied_valuations=MappingProxyType(implied),+ warnings=warnings,+ )diff --git a/agent/src/quantlib/valuation/contracts.py b/agent/src/quantlib/valuation/contracts.pynew file mode 100644index 000000000..c6f5726ba--- /dev/null+++ b/agent/src/quantlib/valuation/contracts.py@@ -0,0 +1,160 @@+"""Shared input discipline for every valuation model in this package.++The modules here -- DCF, comps, three-statement -- deliberately own their own+result types and share almost nothing. What they DO share is the one rule that+decides whether a valuation is a measurement or a story:++ **A missing input makes the model NOT RUNNABLE. It never becomes an+ assumption chosen by the code.**++A discounted cash flow whose tax rate was quietly defaulted to 21%, or whose+terminal growth was quietly defaulted to 2.5%, produces a per-share number that+looks exactly like one built from filed statements. Nothing downstream can tell+them apart, and the reader has no way to know which assumptions were theirs.+:func:`require_inputs` and :class:`MissingInputError` exist so that outcome is+unreachable: the model stops and names every field it lacked.++An assumption that the CALLER makes is a different thing and is welcome -- but+it arrives as an :class:`Assumption` carrying its own justification, and it+shows up in the result so it can be argued with.++WHY NOT DEFAULTS+----------------+Every default in a valuation model is an opinion wearing a constant's clothes.+A 2.5% terminal growth rate is a view on long-run GDP; a 21% tax rate is a view+on jurisdiction and on permanence of current law. Those views may well be right,+but they belong to whoever signs the valuation, not to this package.+"""++from __future__ import annotations++from collections.abc import Iterable, Mapping+from dataclasses import dataclass+from typing import Any++from src.entities.models import normalize_currency++__all__ = [+ "Assumption",+ "MissingInputError",+ "ValuationError",+ "normalize_currency",+ "require_inputs",+ "require_positive",+]+++class ValuationError(ValueError):+ """Base class for every refusal a valuation model makes."""+++class MissingInputError(ValuationError):+ """Raised when a model cannot run because inputs are absent.++ Carries the full list rather than the first one found, so a caller+ assembling data from filings learns everything still needed in one round+ trip instead of one field per attempt.++ Attributes:+ missing: Names of the absent fields, in the order they were required.+ model: Name of the model that refused.+ """++ def __init__(self, missing: Iterable[str], model: str) -> None:+ self.missing = tuple(missing)+ self.model = model+ joined = ", ".join(self.missing)+ super().__init__(+ f"{model} is not runnable: missing {len(self.missing)} required "+ f"input(s): {joined}. Supply them or report the model as not "+ f"runnable -- do not substitute an assumed value."+ )+++@dataclass(frozen=True)+class Assumption:+ """A caller-supplied judgement, carried through to the result.++ Attributes:+ name: What is being assumed, e.g. ``"terminal_growth"``.+ value: The assumed value.+ basis: Why this value. Free text, but required and non-empty: an+ assumption whose justification nobody wrote down cannot be reviewed,+ and an unreviewable assumption in a valuation is indistinguishable+ from a guess.+ source: Optional pointer to where the basis came from -- a filing, a+ data tool call, a named analyst view.++ Raises:+ ValueError: If ``name`` or ``basis`` is empty or blank.+ """++ name: str+ value: Any+ basis: str+ source: str | None = None++ def __post_init__(self) -> None:+ if not str(self.name).strip():+ raise ValueError("an assumption must be named")+ if not str(self.basis).strip():+ raise ValueError(+ f"assumption {self.name!r} has no basis; state why this value was "+ "chosen, or do not make the assumption"+ )+++def require_inputs(+ supplied: Mapping[str, Any],+ required: Iterable[str],+ model: str,+) -> None:+ """Refuse to run unless every required input is present and usable.++ A key that is absent, ``None``, or an empty string counts as missing. Zero+ and ``False`` do NOT: they are legitimate values for a line item, and+ treating them as missing is the mirror-image bug of defaulting.++ Args:+ supplied: The inputs the caller provided.+ required: Field names the model cannot run without.+ model: Name used in the error message.++ Raises:+ MissingInputError: If any required field is absent or unusable, naming+ all of them.+ """+ missing = [+ field+ for field in required+ if field not in supplied+ or supplied[field] is None+ or (isinstance(supplied[field], str) and not supplied[field].strip())+ ]+ if missing:+ raise MissingInputError(missing, model)+++def require_positive(value: float, name: str, model: str) -> float:+ """Check a value that is meaningless at or below zero.++ Args:+ value: The value to check, e.g. a share count or a discount rate.+ name: Field name for the error message.+ model: Model name for the error message.++ Returns:+ ``value`` as a float.++ Raises:+ ValuationError: If the value is not a finite number greater than zero.+ """+ try:+ numeric = float(value)+ except (TypeError, ValueError) as exc:+ raise ValuationError(f"{model}: {name} must be a number, got {value!r}") from exc+ if not numeric > 0.0 or numeric != numeric or numeric in (float("inf"), float("-inf")):+ raise ValuationError(+ f"{model}: {name} must be a finite positive number, got {numeric}"+ )+ return numericdiff --git a/agent/src/quantlib/valuation/dcf.py b/agent/src/quantlib/valuation/dcf.pynew file mode 100644index 000000000..5aaa9b6fe--- /dev/null+++ b/agent/src/quantlib/valuation/dcf.py@@ -0,0 +1,1345 @@+"""Discounted cash flow valuation: WACC, the FCFF bridge, dual terminal value,+discounting, and the bridge from enterprise value to value per share.++This module is the executable form of the DCF walkthrough that used to live as+markdown in valuation write-ups -- a WACC formula, an FCFF formula, a Gordon+growth terminal value, all typed out fresh (and inconsistently) on every run.+Several design choices are deliberate and are exactly the places a hand-rolled+DCF usually goes wrong silently.++**No valuation parameter defaults to anything.** This follows+:mod:`src.quantlib.valuation.contracts` to the letter: the risk-free rate,+beta, the equity risk premium, the cost of debt, the tax rate, the terminal+growth rate, the exit multiple and the diluted share count are all required+arguments with no fallback value anywhere in this file. :func:`run_dcf` takes+them as a flat mapping and refuses to run with :class:`~..contracts.MissingInputError`+if any is absent, so a caller assembling a model from filings learns exactly+what is still missing rather than getting a number built on a guess.++**Terminal growth and the exit multiple are Assumptions, not bare floats.**+``contracts.py``'s own docstring names "terminal growth quietly defaulted to+2.5%" as the canonical example of a valuation opinion wearing a constant's+clothes. Both terminal-value drivers here must therefore arrive as+:class:`~..contracts.Assumption` objects carrying a ``basis`` -- the model+refuses a bare number for either one, and the justification travels through to+:class:`TerminalValueResult` so it can be checked, not just the output.++**Terminal value is always computed two ways, and the two are cross-checked.**+:func:`terminal_value` never runs the perpetuity-growth method alone: it also+runs the exit-multiple method and reports each one's implied version of the+other's driver -- the perpetuity value's implied EV/EBITDA multiple, and the+exit value's implied perpetuity growth rate. This is the only mechanism that+catches a terminal assumption that is arithmetically fine but economically+detached from reality (a growth rate that implies a 35x EBITDA multiple is+wrong even though the Gordon growth formula was applied correctly). ``growth+>= WACC`` is refused outright -- the terminal value is undefined there, not+merely large -- while growth above a long-run nominal GDP reference is only+flagged, because that is a judgment call the model has no standing to veto.++**``delta_nwc`` sign convention.** An *increase* in net working capital is a+*use* of cash: ``delta_nwc > 0`` means working capital grew period over+period and is subtracted from FCFF; a working-capital release+(``delta_nwc < 0``) adds cash back. This is the ordinary balance-sheet+convention, stated explicitly because the alternative reading (delta_nwc as+"cash contribution") is exactly as common in the wild and the two disagree on+every sign.++**Discounting convention is exact, not approximate, at the enterprise-value+level.** Mid-year discounting multiplies every present value by exactly+``(1 + WACC) ** 0.5`` relative to year-end discounting, for one reason: this+module discounts the terminal value using the *same* time index as the final+explicit forecast year (``t = n - 0.5`` under mid-year, ``t = n`` under+year-end), so every dollar in the model -- explicit FCFF or terminal value --+is scaled by the identical constant when the convention flips. That makes the+mid-year/year-end enterprise-value ratio equal to ``sqrt(1 + WACC)`` exactly,+not approximately, which is a strong assertion the test suite checks bit for+bit. The equality does *not* extend to equity value or value per share, since+the net-debt bridge below enterprise value is a fixed balance-sheet fact that+does not scale with the discounting convention.++**Equity bridge sign convention.** Every line between enterprise value and+equity value is supplied as a **non-negative magnitude**; the formula itself+applies the sign::++ equity_value = EV - total_debt + cash_and_equivalents - minority_interest+ - preferred_equity + associate_investments++Passing a negative magnitude is refused rather than silently flipping the+formula's intent, because that is the single most common sign error in a+hand-built bridge.++**Capital-structure basis is a required, explicit argument.** WACC weights can+come from *current* market values (``E / (D + E)``, ``D / (D + E)`` off+today's market value of equity and debt) or from a *target* structure the+analyst believes the firm is moving toward. The two are not interchangeable:+current weights are only the theoretically correct WACC weights if the firm+intends to hold that mix going forward, and a firm expected to lever up or+delever needs target weights instead (Copeland/Koller enterprise-DCF+convention). Nothing here picks one silently -- see+``capital_structure_basis`` on :func:`wacc` and :func:`run_dcf`.+"""++from __future__ import annotations++import math+from collections.abc import Mapping, Sequence+from dataclasses import dataclass+from typing import Any++import numpy as np+import pandas as pd++from src.quantlib.valuation.contracts import (+ Assumption,+ MissingInputError,+ ValuationError,+ require_inputs,+ require_positive,+)++__all__ = [+ "CAPITAL_STRUCTURE_BASES",+ "DISCOUNTING_CONVENTIONS",+ "TERMINAL_VALUE_METHODS",+ "DEFAULT_LONG_RUN_GDP_GROWTH_CEILING",+ "DCF_BASE_REQUIRED_FIELDS",+ "DCF_CURRENT_STRUCTURE_FIELDS",+ "DCF_TARGET_STRUCTURE_FIELDS",+ "WACCResult",+ "FCFFYear",+ "TerminalValueResult",+ "DiscountedCashFlow",+ "NetDebtBridgeResult",+ "DCFResult",+ "wacc",+ "fcff_bridge",+ "terminal_value",+ "discount_fcff",+ "equity_bridge",+ "run_dcf",+ "sensitivity_grid",+]++#: How WACC's capital-structure weights are sourced. ``"current"`` derives+#: ``E / (D + E)`` and ``D / (D + E)`` from today's market values; ``"target"``+#: takes the weights directly as the analyst's view of the structure the firm+#: is moving toward. See the module docstring for why the two are not+#: interchangeable.+CAPITAL_STRUCTURE_BASES: tuple[str, ...] = ("current", "target")++#: Timing convention for discounting a cash flow that arrives sometime during+#: year ``t``. ``"mid_year"`` assumes it lands on average at ``t - 0.5``;+#: ``"year_end"`` assumes it lands at ``t``.+DISCOUNTING_CONVENTIONS: tuple[str, ...] = ("mid_year", "year_end")++#: Which terminal-value estimate feeds the enterprise-value bridge. Both+#: methods are always computed and cross-checked (see :func:`terminal_value`);+#: this only selects which one is discounted into ``DCFResult.enterprise_value``.+TERMINAL_VALUE_METHODS: tuple[str, ...] = ("perpetuity_growth", "exit_multiple")++#: Reference ceiling used only to FLAG a perpetuity growth assumption, never to+#: block or alter one -- a terminal growth rate above long-run nominal GDP+#: growth is not mathematically wrong, only worth a second look. This is a+#: diagnostic threshold, not a valuation input: it never appears in any formula+#: that produces a price. 4% approximates long-run US real GDP growth+#: (~2%) plus a long-run inflation target (~2%); callers valuing a business+#: against a different economy should pass their own ``gdp_growth_ceiling``.+DEFAULT_LONG_RUN_GDP_GROWTH_CEILING: float = 0.04++#: Flat input-mapping keys :func:`run_dcf` requires regardless of+#: ``capital_structure_basis``.+DCF_BASE_REQUIRED_FIELDS: tuple[str, ...] = (+ "risk_free_rate",+ "beta",+ "equity_risk_premium",+ "pretax_cost_of_debt",+ "tax_rate",+ "ebit",+ "depreciation_amortization",+ "capex",+ "delta_nwc",+ "terminal_growth",+ "exit_multiple",+ "total_debt",+ "cash_and_equivalents",+ "minority_interest",+ "preferred_equity",+ "associate_investments",+ "diluted_shares",+)++#: Additional keys :func:`run_dcf` requires when ``capital_structure_basis="current"``.+DCF_CURRENT_STRUCTURE_FIELDS: tuple[str, ...] = (+ "market_value_of_equity",+ "market_value_of_debt",+)++#: Additional keys :func:`run_dcf` requires when ``capital_structure_basis="target"``.+DCF_TARGET_STRUCTURE_FIELDS: tuple[str, ...] = (+ "target_equity_weight",+ "target_debt_weight",+)++#: Slack allowed when checking that capital-structure weights sum to 1, and+#: when re-checking a dataclass's own internal arithmetic in ``__post_init__``.+_RECONCILIATION_TOLERANCE: float = 1e-6+++# ---------------------------------------------------------------------------+# small private helpers+# ---------------------------------------------------------------------------+++def _require_assumption(value: Any, expected_name: str, model: str) -> Assumption:+ """Check that a terminal-value driver arrived as a justified Assumption.++ Args:+ value: Candidate supplied by the caller.+ expected_name: The :attr:`Assumption.name` this slot expects.+ model: Name used in the error message.++ Returns:+ ``value``, unchanged.++ Raises:+ ValuationError: If ``value`` is not an :class:`Assumption`, or if its+ ``name`` does not match ``expected_name`` (which usually means two+ assumptions were passed under swapped keys).+ """+ if not isinstance(value, Assumption):+ raise ValuationError(+ f"{model}: {expected_name!r} must be supplied as an Assumption("+ f"name=..., value=..., basis=...) carrying its justification, not "+ f"a bare {type(value).__name__}. A terminal growth rate or exit "+ "multiple chosen without a stated reason is exactly the kind of "+ "silent default this package refuses to make on your behalf."+ )+ if value.name != expected_name:+ raise ValuationError(+ f"{model}: expected an Assumption named {expected_name!r}, got "+ f"{value.name!r}; check that assumptions were not passed under "+ "swapped keys."+ )+ return value+++def _require_nonnegative(value: float, name: str, model: str) -> float:+ """Check a value that is a signed formula's magnitude, so must be >= 0.++ Args:+ value: The candidate magnitude.+ name: Field name for the error message.+ model: Model name for the error message.++ Returns:+ ``value`` as a float.++ Raises:+ ValuationError: If the value is negative or not a finite number. A+ negative magnitude here would silently flip the sign the bridge+ formula already applies.+ """+ try:+ numeric = float(value)+ except (TypeError, ValueError) as exc:+ raise ValuationError(f"{model}: {name} must be a number, got {value!r}") from exc+ if not math.isfinite(numeric) or numeric < 0.0:+ raise ValuationError(+ f"{model}: {name} must be supplied as a non-negative magnitude "+ f"(its sign is applied by the bridge formula), got {numeric!r}"+ )+ return numeric+++def _validate_weights(equity_weight: float, debt_weight: float, *, model: str) -> None:+ """Check that a pair of capital-structure weights is usable.++ Args:+ equity_weight: Proposed ``E / (D + E)``.+ debt_weight: Proposed ``D / (D + E)``.+ model: Model name for the error message.++ Raises:+ ValuationError: If either weight is negative, or if they do not sum to+ 1 within :data:`_RECONCILIATION_TOLERANCE`.+ """+ if equity_weight < 0.0 or debt_weight < 0.0:+ raise ValuationError(+ f"{model}: capital-structure weights must be non-negative, got "+ f"equity_weight={equity_weight!r} debt_weight={debt_weight!r}"+ )+ total = equity_weight + debt_weight+ if abs(total - 1.0) > _RECONCILIATION_TOLERANCE:+ raise ValuationError(+ f"{model}: capital-structure weights must sum to 1 (within "+ f"{_RECONCILIATION_TOLERANCE:g}), got equity_weight={equity_weight!r} "+ f"+ debt_weight={debt_weight!r} = {total!r}"+ )+++# ---------------------------------------------------------------------------+# WACC+# ---------------------------------------------------------------------------+++@dataclass(frozen=True)+class WACCResult:+ """The WACC build, with every component that fed it kept visible.++ Attributes:+ risk_free_rate: ``rf`` used in CAPM.+ beta: Levered beta used in CAPM.+ equity_risk_premium: ``ERP`` used in CAPM.+ size_premium: Additive small-cap premium, ``0.0`` if not supplied.+ country_risk_premium: Additive sovereign/country premium, ``0.0`` if+ not supplied.+ cost_of_equity: ``Re = rf + beta * ERP + size_premium + country_risk_premium``.+ pretax_cost_of_debt: ``Rd`` before the tax shield.+ tax_rate: Marginal tax rate applied to the debt tax shield (and, in+ :func:`fcff_bridge`, to EBIT -- the same statutory rate drives both).+ cost_of_debt_after_tax: ``Rd * (1 - tax_rate)``.+ capital_structure_basis: ``"current"`` or ``"target"``; see the module+ docstring for the difference.+ equity_weight: ``E / (D + E)``.+ debt_weight: ``D / (D + E)``.+ wacc: The blended discount rate,+ ``equity_weight * cost_of_equity + debt_weight * cost_of_debt_after_tax``.+ """++ risk_free_rate: float+ beta: float+ equity_risk_premium: float+ size_premium: float+ country_risk_premium: float+ cost_of_equity: float+ pretax_cost_of_debt: float+ tax_rate: float+ cost_of_debt_after_tax: float+ capital_structure_basis: str+ equity_weight: float+ debt_weight: float+ wacc: float++ def __post_init__(self) -> None:+ """Re-check the blend arithmetic and the weight identity.++ Raises:+ ValueError: If the weights do not sum to 1, or ``wacc`` is not the+ stated weighted blend of the two costs of capital.+ """+ _validate_weights(self.equity_weight, self.debt_weight, model="WACCResult")+ expected = (+ self.equity_weight * self.cost_of_equity+ + self.debt_weight * self.cost_of_debt_after_tax+ )+ if not math.isclose(+ self.wacc, expected, rel_tol=_RECONCILIATION_TOLERANCE, abs_tol=1e-12+ ):+ raise ValueError(+ f"WACCResult.wacc={self.wacc!r} does not match the weighted "+ f"blend {expected!r} of cost_of_equity and cost_of_debt_after_tax"+ )+++def wacc(+ *,+ risk_free_rate: float,+ beta: float,+ equity_risk_premium: float,+ pretax_cost_of_debt: float,+ tax_rate: float,+ capital_structure_basis: str,+ market_value_of_equity: float | None = None,+ market_value_of_debt: float | None = None,+ target_equity_weight: float | None = None,+ target_debt_weight: float | None = None,+ size_premium: float = 0.0,+ country_risk_premium: float = 0.0,+) -> WACCResult:+ """Build the weighted average cost of capital.++ ``Re`` is CAPM plus two optional additive premiums; ``Rd`` is the pretax+ cost of debt shielded by the tax rate; the two are blended by+ capital-structure weights sourced per ``capital_structure_basis``.++ Args:+ risk_free_rate: ``rf``, as a decimal.+ beta: Levered equity beta.+ equity_risk_premium: ``ERP``, as a decimal.+ pretax_cost_of_debt: ``Rd`` before the tax shield, as a decimal.+ tax_rate: Marginal tax rate in ``[0, 1]``.+ capital_structure_basis: One of :data:`CAPITAL_STRUCTURE_BASES`.+ ``"current"`` derives weights from today's market values;+ ``"target"`` takes the weights directly. Required, no default --+ see the module docstring for why the two are not interchangeable.+ market_value_of_equity: Market value of equity. Required (and only+ used) when ``capital_structure_basis="current"``.+ market_value_of_debt: Market value of debt. Required (and only used)+ when ``capital_structure_basis="current"``.+ target_equity_weight: Target ``E / (D + E)``. Required (and only used)+ when ``capital_structure_basis="target"``.+ target_debt_weight: Target ``D / (D + E)``. Required (and only used)+ when ``capital_structure_basis="target"``.+ size_premium: Additive small-cap premium on cost of equity. Optional --+ absence means "not applying one", which is a structural choice, not+ a guessed magnitude standing in for an unknown rate.+ country_risk_premium: Additive sovereign/country premium on cost of+ equity. Same optionality rationale as ``size_premium``.++ Returns:+ A :class:`WACCResult` with every intermediate figure visible.++ Raises:+ MissingInputError: If the market-value or target-weight pair matching+ ``capital_structure_basis`` is not fully supplied.+ ValuationError: If ``capital_structure_basis`` is unrecognised, if+ ``tax_rate`` is outside ``[0, 1]``, if a market value is negative,+ if the market value of equity plus debt is zero (weights+ undefined), or if the resulting weights are negative or do not sum+ to 1.+ """+ if capital_structure_basis not in CAPITAL_STRUCTURE_BASES:+ raise ValuationError(+ f"wacc: capital_structure_basis must be one of "+ f"{CAPITAL_STRUCTURE_BASES}, got {capital_structure_basis!r}"+ )+ if not 0.0 <= tax_rate <= 1.0:+ raise ValuationError(f"wacc: tax_rate must be within [0, 1], got {tax_rate!r}")++ if capital_structure_basis == "current":+ missing = [+ name+ for name, value in (+ ("market_value_of_equity", market_value_of_equity),+ ("market_value_of_debt", market_value_of_debt),+ )+ if value is None+ ]+ if missing:+ raise MissingInputError(missing, "wacc")+ equity_mv = float(market_value_of_equity) # type: ignore[arg-type]+ debt_mv = float(market_value_of_debt) # type: ignore[arg-type]+ if equity_mv < 0.0 or debt_mv < 0.0:+ raise ValuationError(+ f"wacc: market values must be non-negative, got "+ f"market_value_of_equity={equity_mv!r} market_value_of_debt={debt_mv!r}"+ )+ total_mv = equity_mv + debt_mv+ if total_mv <= 0.0:+ raise ValuationError(+ "wacc: market value of equity plus debt is zero (D + E = 0); "+ "capital-structure weights are undefined"+ )+ equity_weight = equity_mv / total_mv+ debt_weight = debt_mv / total_mv+ else:+ missing = [+ name+ for name, value in (+ ("target_equity_weight", target_equity_weight),+ ("target_debt_weight", target_debt_weight),+ )+ if value is None+ ]+ if missing:+ raise MissingInputError(missing, "wacc")+ equity_weight = float(target_equity_weight) # type: ignore[arg-type]+ debt_weight = float(target_debt_weight) # type: ignore[arg-type]++ _validate_weights(equity_weight, debt_weight, model="wacc")++ cost_of_equity = (+ risk_free_rate + beta * equity_risk_premium + size_premium + country_risk_premium+ )+ cost_of_debt_after_tax = pretax_cost_of_debt * (1.0 - tax_rate)+ blended = equity_weight * cost_of_equity + debt_weight * cost_of_debt_after_tax++ return WACCResult(+ risk_free_rate=float(risk_free_rate),+ beta=float(beta),+ equity_risk_premium=float(equity_risk_premium),+ size_premium=float(size_premium),+ country_risk_premium=float(country_risk_premium),+ cost_of_equity=cost_of_equity,+ pretax_cost_of_debt=float(pretax_cost_of_debt),+ tax_rate=float(tax_rate),+ cost_of_debt_after_tax=cost_of_debt_after_tax,+ capital_structure_basis=capital_structure_basis,+ equity_weight=equity_weight,+ debt_weight=debt_weight,+ wacc=blended,+ )+++# ---------------------------------------------------------------------------+# FCFF bridge+# ---------------------------------------------------------------------------+++@dataclass(frozen=True)+class FCFFYear:+ """One projection year's bridge from EBIT to free cash flow to the firm.++ ``FCFF = NOPAT + depreciation_amortization - capex - delta_nwc``. Every+ step is a field so a reader can see which one consumed the cash, not just+ the final number.++ Attributes:+ year: 1-indexed projection year (1 is the first forecast year).+ ebit: Earnings before interest and tax.+ tax_rate: Marginal tax rate applied to EBIT.+ nopat: ``ebit * (1 - tax_rate)``.+ depreciation_amortization: Non-cash D&A added back.+ capex: Capital expenditure, a positive magnitude representing a cash+ outflow.+ delta_nwc: Change in net working capital. **Positive means working+ capital increased and cash was used**; negative means working+ capital was released and cash was returned. See the module+ docstring.+ fcff: ``nopat + depreciation_amortization - capex - delta_nwc``.+ """++ year: int+ ebit: float+ tax_rate: float+ nopat: float+ depreciation_amortization: float+ capex: float+ delta_nwc: float+ fcff: float++ def __post_init__(self) -> None:+ """Re-check the NOPAT and FCFF arithmetic.++ Raises:+ ValueError: If ``nopat`` or ``fcff`` do not match their formulas,+ or ``year`` is not a positive integer.+ """+ if self.year < 1:+ raise ValueError(f"FCFFYear.year must be >= 1, got {self.year!r}")+ expected_nopat = self.ebit * (1.0 - self.tax_rate)+ if not math.isclose(+ self.nopat, expected_nopat, rel_tol=_RECONCILIATION_TOLERANCE, abs_tol=1e-9+ ):+ raise ValueError(+ f"FCFFYear(year={self.year}).nopat={self.nopat!r} does not match "+ f"ebit * (1 - tax_rate) = {expected_nopat!r}"+ )+ expected_fcff = (+ self.nopat + self.depreciation_amortization - self.capex - self.delta_nwc+ )+ if not math.isclose(+ self.fcff, expected_fcff, rel_tol=_RECONCILIATION_TOLERANCE, abs_tol=1e-9+ ):+ raise ValueError(+ f"FCFFYear(year={self.year}).fcff={self.fcff!r} does not match the "+ f"bridge total {expected_fcff!r}"+ )+++def fcff_bridge(+ *,+ ebit: Sequence[float],+ tax_rate: float,+ depreciation_amortization: Sequence[float],+ capex: Sequence[float],+ delta_nwc: Sequence[float],+) -> tuple[FCFFYear, ...]:+ """Build the EBIT -> FCFF bridge for every projection year.++ Args:+ ebit: EBIT forecast, one entry per projection year, oldest first.+ tax_rate: Marginal tax rate in ``[0, 1]``, applied to every year.+ depreciation_amortization: D&A forecast, same length as ``ebit``.+ capex: Capital expenditure forecast (positive = cash outflow), same+ length as ``ebit``.+ delta_nwc: Net-working-capital change forecast (positive = cash+ outflow; see the module docstring), same length as ``ebit``.++ Returns:+ One :class:`FCFFYear` per projection year, in order.++ Raises:+ ValuationError: If ``tax_rate`` is outside ``[0, 1]``, if ``ebit`` is+ empty, or if the other three forecasts are not the same length as+ ``ebit``.+ """+ if not 0.0 <= tax_rate <= 1.0:+ raise ValuationError(f"fcff_bridge: tax_rate must be within [0, 1], got {tax_rate!r}")++ ebit_list = list(ebit)+ horizon = len(ebit_list)+ if horizon == 0:+ raise ValuationError(+ "fcff_bridge: ebit forecast is empty; at least one projection year "+ "is required"+ )+ forecasts = {+ "depreciation_amortization": list(depreciation_amortization),+ "capex": list(capex),+ "delta_nwc": list(delta_nwc),+ }+ for name, values in forecasts.items():+ if len(values) != horizon:+ raise ValuationError(+ f"fcff_bridge: {name} has {len(values)} year(s), expected "+ f"{horizon} to match ebit"+ )++ years = []+ for index in range(horizon):+ ebit_value = float(ebit_list[index])+ da_value = float(forecasts["depreciation_amortization"][index])+ capex_value = float(forecasts["capex"][index])+ delta_nwc_value = float(forecasts["delta_nwc"][index])+ nopat = ebit_value * (1.0 - tax_rate)+ fcff_value = nopat + da_value - capex_value - delta_nwc_value+ years.append(+ FCFFYear(+ year=index + 1,+ ebit=ebit_value,+ tax_rate=tax_rate,+ nopat=nopat,+ depreciation_amortization=da_value,+ capex=capex_value,+ delta_nwc=delta_nwc_value,+ fcff=fcff_value,+ )+ )+ return tuple(years)+++# ---------------------------------------------------------------------------+# Dual terminal value+# ---------------------------------------------------------------------------+++@dataclass(frozen=True)+class TerminalValueResult:+ """Both terminal-value estimates, each cross-checked against the other.++ Attributes:+ wacc_rate: Discount rate used by the perpetuity-growth method.+ terminal_growth: The :class:`Assumption` behind the perpetuity-growth+ method, carrying its ``basis``.+ perpetuity_terminal_value: ``FCFF_{n+1} / (wacc_rate - g)`` where+ ``FCFF_{n+1} = FCFF_n * (1 + g)``.+ terminal_year_ebitda: ``EBITDA`` of the final explicit forecast year,+ used by the exit-multiple method.+ exit_multiple: The :class:`Assumption` behind the exit-multiple+ method, carrying its ``basis``.+ exit_terminal_value: ``terminal_year_ebitda * exit_multiple.value``.+ implied_ev_ebitda_multiple: What EV/EBITDA multiple+ ``perpetuity_terminal_value`` implies -- the perpetuity method's+ result, restated in the exit method's units, so a reader can judge+ whether the growth assumption is realistic on its face.+ implied_perpetuity_growth: What perpetuity growth rate+ ``exit_terminal_value`` implies -- the exit method's result,+ restated in the perpetuity method's units.+ gdp_growth_ceiling: Reference ceiling used for ``growth_exceeds_gdp_ceiling``.+ growth_exceeds_gdp_ceiling: ``True`` if ``terminal_growth.value`` is+ above ``gdp_growth_ceiling``. A flag, never an error -- see the+ module docstring.+ """++ wacc_rate: float+ terminal_growth: Assumption+ perpetuity_terminal_value: float+ terminal_year_ebitda: float+ exit_multiple: Assumption+ exit_terminal_value: float+ implied_ev_ebitda_multiple: float+ implied_perpetuity_growth: float+ gdp_growth_ceiling: float+ growth_exceeds_gdp_ceiling: bool++ def __post_init__(self) -> None:+ """Re-check that the stored growth rate is still below WACC.++ Raises:+ ValueError: If ``terminal_growth.value >= wacc_rate``. This should+ already have been refused by :func:`terminal_value` before+ construction; this is a second, independent check.+ """+ if float(self.terminal_growth.value) >= self.wacc_rate:+ raise ValueError(+ f"TerminalValueResult.terminal_growth.value="+ f"{self.terminal_growth.value!r} is not below wacc_rate="+ f"{self.wacc_rate!r}"+ )+++def terminal_value(+ *,+ final_year_fcff: float,+ terminal_year_ebitda: float,+ wacc_rate: float,+ terminal_growth: Assumption,+ exit_multiple: Assumption,+ gdp_growth_ceiling: float = DEFAULT_LONG_RUN_GDP_GROWTH_CEILING,+) -> TerminalValueResult:+ """Compute both terminal-value estimates and cross-validate them.++ Args:+ final_year_fcff: ``FCFF_n``, the last explicit forecast year's free+ cash flow to the firm.+ terminal_year_ebitda: ``EBITDA`` of the final explicit forecast year.+ wacc_rate: The discount rate, as a decimal.+ terminal_growth: An :class:`Assumption` naming the perpetuity growth+ rate ``g`` and its basis.+ exit_multiple: An :class:`Assumption` naming the EV/EBITDA exit+ multiple and its basis.+ gdp_growth_ceiling: Reference ceiling used only to flag+ ``terminal_growth`` -- see :data:`DEFAULT_LONG_RUN_GDP_GROWTH_CEILING`.++ Returns:+ A :class:`TerminalValueResult` carrying both terminal values and both+ cross-checks.++ Raises:+ ValuationError: If either argument is not the matching+ :class:`Assumption`; if ``wacc_rate <= -1``; if+ ``terminal_growth.value >= wacc_rate`` (the perpetuity terminal+ value is negative or infinite there, not merely large); if+ ``terminal_year_ebitda <= 0`` (an EV/EBITDA multiple is undefined);+ if ``exit_multiple.value <= 0``; or if the exit terminal value+ happens to equal ``-final_year_fcff`` exactly, which makes the+ implied-growth reverse-solve's denominator zero.+ """+ _require_assumption(terminal_growth, "terminal_growth", "terminal_value")+ _require_assumption(exit_multiple, "exit_multiple", "terminal_value")++ if wacc_rate <= -1.0:+ raise ValuationError(+ f"terminal_value: wacc_rate must exceed -1, got {wacc_rate!r}"+ )+ growth = float(terminal_growth.value)+ if growth >= wacc_rate:+ raise ValuationError(+ f"terminal_value: terminal_growth ({growth!r}) must be strictly "+ f"less than WACC ({wacc_rate!r}); at or above WACC the Gordon-growth "+ "terminal value is negative or infinite, not merely a large number. "+ "Lower the growth assumption or check the WACC build."+ )+ if terminal_year_ebitda <= 0.0:+ raise ValuationError(+ f"terminal_value: terminal_year_ebitda must be positive to derive "+ f"an implied EV/EBITDA multiple, got {terminal_year_ebitda!r}"+ )+ multiple = float(exit_multiple.value)+ if multiple <= 0.0:+ raise ValuationError(+ f"terminal_value: exit_multiple.value must be positive, got {multiple!r}"+ )++ next_year_fcff = final_year_fcff * (1.0 + growth)+ perpetuity_tv = next_year_fcff / (wacc_rate - growth)+ exit_tv = terminal_year_ebitda * multiple++ implied_ev_ebitda_multiple = perpetuity_tv / terminal_year_ebitda++ denominator = exit_tv + final_year_fcff+ if denominator == 0.0:+ raise ValuationError(+ "terminal_value: cannot solve the exit multiple's implied perpetuity "+ "growth because exit_terminal_value and final_year_fcff are equal "+ "and opposite, making the reverse-solve denominator zero"+ )+ implied_perpetuity_growth = (exit_tv * wacc_rate - final_year_fcff) / denominator++ return TerminalValueResult(+ wacc_rate=float(wacc_rate),+ terminal_growth=terminal_growth,+ perpetuity_terminal_value=perpetuity_tv,+ terminal_year_ebitda=float(terminal_year_ebitda),+ exit_multiple=exit_multiple,+ exit_terminal_value=exit_tv,+ implied_ev_ebitda_multiple=implied_ev_ebitda_multiple,+ implied_perpetuity_growth=implied_perpetuity_growth,+ gdp_growth_ceiling=float(gdp_growth_ceiling),+ growth_exceeds_gdp_ceiling=growth > gdp_growth_ceiling,+ )+++# ---------------------------------------------------------------------------+# Discounting+# ---------------------------------------------------------------------------+++@dataclass(frozen=True)+class DiscountedCashFlow:+ """One projection year's FCFF, discounted to present value.++ Attributes:+ year: 1-indexed projection year, matching :attr:`FCFFYear.year`.+ fcff: The undiscounted free cash flow to the firm for this year.+ wacc_rate: Discount rate used.+ time_period: The exponent ``t`` actually used --+ ``year - 0.5`` under ``"mid_year"``, ``year`` under ``"year_end"``.+ discount_factor: ``(1 + wacc_rate) ** -time_period``.+ present_value: ``fcff * discount_factor``.+ """++ year: int+ fcff: float+ wacc_rate: float+ time_period: float+ discount_factor: float+ present_value: float++ def __post_init__(self) -> None:+ """Re-check the discount factor and present-value arithmetic.++ Raises:+ ValueError: If ``discount_factor`` or ``present_value`` do not+ match their formulas.+ """+ expected_factor = (1.0 + self.wacc_rate) ** (-self.time_period)+ if not math.isclose(+ self.discount_factor, expected_factor, rel_tol=1e-9, abs_tol=1e-12+ ):+ raise ValueError(+ f"DiscountedCashFlow(year={self.year}).discount_factor="+ f"{self.discount_factor!r} does not match "+ f"(1 + wacc_rate) ** -time_period = {expected_factor!r}"+ )+ expected_pv = self.fcff * self.discount_factor+ if not math.isclose(self.present_value, expected_pv, rel_tol=1e-9, abs_tol=1e-9):+ raise ValueError(+ f"DiscountedCashFlow(year={self.year}).present_value="+ f"{self.present_value!r} does not match fcff * discount_factor "+ f"= {expected_pv!r}"+ )+++def discount_fcff(+ fcff_years: Sequence[FCFFYear],+ *,+ wacc_rate: float,+ discounting_convention: str,+) -> tuple[DiscountedCashFlow, ...]:+ """Discount every projection year's FCFF to present value.++ Args:+ fcff_years: The FCFF bridge, e.g. from :func:`fcff_bridge`.+ wacc_rate: Discount rate, as a decimal, strictly greater than -1.+ discounting_convention: One of :data:`DISCOUNTING_CONVENTIONS`.+ Required, no default -- see the module docstring for why mid-year+ and year-end are not interchangeable.++ Returns:+ One :class:`DiscountedCashFlow` per input year, in the same order.++ Raises:+ ValuationError: If ``discounting_convention`` is unrecognised, if+ ``fcff_years`` is empty, or if ``wacc_rate <= -1``.+ """+ if discounting_convention not in DISCOUNTING_CONVENTIONS:+ raise ValuationError(+ f"discount_fcff: discounting_convention must be one of "+ f"{DISCOUNTING_CONVENTIONS}, got {discounting_convention!r}"+ )+ if not fcff_years:+ raise ValuationError("discount_fcff: fcff_years is empty")+ if wacc_rate <= -1.0:+ raise ValuationError(f"discount_fcff: wacc_rate must exceed -1, got {wacc_rate!r}")++ results = []+ for entry in fcff_years:+ time_period = (+ entry.year - 0.5 if discounting_convention == "mid_year" else float(entry.year)+ )+ discount_factor_value = (1.0 + wacc_rate) ** (-time_period)+ results.append(+ DiscountedCashFlow(+ year=entry.year,+ fcff=entry.fcff,+ wacc_rate=float(wacc_rate),+ time_period=time_period,+ discount_factor=discount_factor_value,+ present_value=entry.fcff * discount_factor_value,+ )+ )+ return tuple(results)+++# ---------------------------------------------------------------------------+# Net-debt bridge to value per share+# ---------------------------------------------------------------------------+++@dataclass(frozen=True)+class NetDebtBridgeResult:+ """The bridge from enterprise value to value per share.++ Every balance-sheet item is a non-negative magnitude; the sign each one+ carries in the formula is fixed and documented here, not inferred from the+ number's own sign.++ Attributes:+ enterprise_value: EV entering the bridge.+ total_debt: Subtracted -- debt is a claim ahead of equity.+ cash_and_equivalents: Added -- cash is equity value EV does not price.+ minority_interest: Subtracted -- non-controlling interests' claim on+ consolidated value.+ preferred_equity: Subtracted -- senior to common equity.+ associate_investments: Added -- equity-method investments EV does not+ capture (their earnings are typically excluded from EBIT/EBITDA).+ equity_value: ``enterprise_value - total_debt + cash_and_equivalents -+ minority_interest - preferred_equity + associate_investments``.+ diluted_shares: Fully diluted share count.+ value_per_share: ``equity_value / diluted_shares``.+ """++ enterprise_value: float+ total_debt: float+ cash_and_equivalents: float+ minority_interest: float+ preferred_equity: float+ associate_investments: float+ equity_value: float+ diluted_shares: float+ value_per_share: float++ def __post_init__(self) -> None:+ """Re-check the bridge and per-share arithmetic.++ Raises:+ ValueError: If ``equity_value`` or ``value_per_share`` do not+ match their formulas.+ """+ expected_equity = (+ self.enterprise_value+ - self.total_debt+ + self.cash_and_equivalents+ - self.minority_interest+ - self.preferred_equity+ + self.associate_investments+ )+ if not math.isclose(+ self.equity_value, expected_equity, rel_tol=_RECONCILIATION_TOLERANCE, abs_tol=1e-6+ ):+ raise ValueError(+ f"NetDebtBridgeResult.equity_value={self.equity_value!r} does not "+ f"match the bridge total {expected_equity!r}"+ )+ expected_per_share = self.equity_value / self.diluted_shares+ if not math.isclose(+ self.value_per_share,+ expected_per_share,+ rel_tol=_RECONCILIATION_TOLERANCE,+ abs_tol=1e-9,+ ):+ raise ValueError(+ f"NetDebtBridgeResult.value_per_share={self.value_per_share!r} "+ f"does not match equity_value / diluted_shares = {expected_per_share!r}"+ )+++def equity_bridge(+ *,+ enterprise_value: float,+ total_debt: float,+ cash_and_equivalents: float,+ minority_interest: float,+ preferred_equity: float,+ associate_investments: float,+ diluted_shares: float,+) -> NetDebtBridgeResult:+ """Bridge enterprise value to equity value and value per share.++ Args:+ enterprise_value: EV entering the bridge.+ total_debt: Non-negative magnitude of total debt; subtracted.+ cash_and_equivalents: Non-negative magnitude of cash and equivalents;+ added.+ minority_interest: Non-negative magnitude of non-controlling+ interests; subtracted.+ preferred_equity: Non-negative magnitude of preferred equity;+ subtracted.+ associate_investments: Non-negative magnitude of equity-method+ investments in associates/joint ventures; added.+ diluted_shares: Fully diluted share count; must be strictly positive.++ Returns:+ A :class:`NetDebtBridgeResult`.++ Raises:+ ValuationError: If any of the five balance-sheet items is negative or+ not finite, or if ``diluted_shares`` is not a finite positive number.+ """+ debt = _require_nonnegative(total_debt, "total_debt", "equity_bridge")+ cash = _require_nonnegative(cash_and_equivalents, "cash_and_equivalents", "equity_bridge")+ minority = _require_nonnegative(minority_interest, "minority_interest", "equity_bridge")+ preferred = _require_nonnegative(preferred_equity, "preferred_equity", "equity_bridge")+ associates = _require_nonnegative(+ associate_investments, "associate_investments", "equity_bridge"+ )+ shares = require_positive(diluted_shares, "diluted_shares", "equity_bridge")++ equity_value = enterprise_value - debt + cash - minority - preferred + associates+ value_per_share = equity_value / shares++ return NetDebtBridgeResult(+ enterprise_value=float(enterprise_value),+ total_debt=debt,+ cash_and_equivalents=cash,+ minority_interest=minority,+ preferred_equity=preferred,+ associate_investments=associates,+ equity_value=equity_value,+ diluted_shares=shares,+ value_per_share=value_per_share,+ )+++# ---------------------------------------------------------------------------+# Sensitivity grid+# ---------------------------------------------------------------------------+++def sensitivity_grid(+ fcff_years: Sequence[FCFFYear],+ *,+ wacc_values: Sequence[float],+ growth_values: Sequence[float],+ discounting_convention: str,+ total_debt: float,+ cash_and_equivalents: float,+ minority_interest: float,+ preferred_equity: float,+ associate_investments: float,+ diluted_shares: float,+) -> pd.DataFrame:+ """Value-per-share sensitivity to WACC and perpetuity terminal growth.++ Every cell re-runs the full model (discount the explicit FCFFs at that+ WACC, build the perpetuity-growth terminal value at that WACC and growth,+ discount it at the same timing as the final explicit year, then bridge+ through the same fixed balance-sheet items) rather than perturbing the+ published enterprise value, so the grid is internally consistent at every+ point. Only the perpetuity-growth method is swept -- the exit-multiple+ method has no growth axis.++ Args:+ fcff_years: The FCFF bridge, e.g. from :func:`fcff_bridge`. WACC- and+ growth-independent, so it is reused unchanged at every cell.+ wacc_values: WACC values forming the grid's rows, each strictly+ greater than -1.+ growth_values: Perpetuity growth values forming the grid's columns.+ discounting_convention: One of :data:`DISCOUNTING_CONVENTIONS`.+ total_debt: Non-negative magnitude; subtracted at every cell.+ cash_and_equivalents: Non-negative magnitude; added at every cell.+ minority_interest: Non-negative magnitude; subtracted at every cell.+ preferred_equity: Non-negative magnitude; subtracted at every cell.+ associate_investments: Non-negative magnitude; added at every cell.+ diluted_shares: Fully diluted share count; must be strictly positive.++ Returns:+ A ``pandas.DataFrame`` indexed by ``wacc_values`` (index name+ ``"wacc"``) with columns ``growth_values`` (columns name+ ``"terminal_growth"``). Cells where ``growth >= wacc`` are ``NaN``+ rather than a large number, because the perpetuity terminal value is+ undefined there, not merely large -- see the module docstring.++ Raises:+ ValuationError: If ``fcff_years``, ``wacc_values`` or+ ``growth_values`` is empty, if ``discounting_convention`` is+ unrecognised, if any ``wacc_values`` entry is at or below -1, or if+ any balance-sheet item is negative or ``diluted_shares`` is not+ positive.+ """+ if discounting_convention not in DISCOUNTING_CONVENTIONS:+ raise ValuationError(+ f"sensitivity_grid: discounting_convention must be one of "+ f"{DISCOUNTING_CONVENTIONS}, got {discounting_convention!r}"+ )+ if not fcff_years:+ raise ValuationError("sensitivity_grid: fcff_years is empty")+ wacc_list = list(wacc_values)+ growth_list = list(growth_values)+ if not wacc_list:+ raise ValuationError("sensitivity_grid: wacc_values is empty")+ if not growth_list:+ raise ValuationError("sensitivity_grid: growth_values is empty")++ debt = _require_nonnegative(total_debt, "total_debt", "sensitivity_grid")+ cash = _require_nonnegative(cash_and_equivalents, "cash_and_equivalents", "sensitivity_grid")+ minority = _require_nonnegative(minority_interest, "minority_interest", "sensitivity_grid")+ preferred = _require_nonnegative(preferred_equity, "preferred_equity", "sensitivity_grid")+ associates = _require_nonnegative(+ associate_investments, "associate_investments", "sensitivity_grid"+ )+ shares = require_positive(diluted_shares, "diluted_shares", "sensitivity_grid")++ final_fcff = fcff_years[-1].fcff+ grid = np.full((len(wacc_list), len(growth_list)), np.nan, dtype=float)++ for row, wacc_value in enumerate(wacc_list):+ if wacc_value <= -1.0:+ raise ValuationError(+ f"sensitivity_grid: wacc_values must exceed -1, got {wacc_value!r}"+ )+ discounted = discount_fcff(+ fcff_years, wacc_rate=wacc_value, discounting_convention=discounting_convention+ )+ pv_explicit = sum(entry.present_value for entry in discounted)+ terminal_factor = discounted[-1].discount_factor+ for col, growth_value in enumerate(growth_list):+ if growth_value >= wacc_value:+ continue # left as NaN: the perpetuity terminal value is undefined here+ tv = final_fcff * (1.0 + growth_value) / (wacc_value - growth_value)+ enterprise_value = pv_explicit + tv * terminal_factor+ equity_value = (+ enterprise_value - debt + cash - minority - preferred + associates+ )+ grid[row, col] = equity_value / shares++ return pd.DataFrame(+ grid,+ index=pd.Index(wacc_list, name="wacc"),+ columns=pd.Index(growth_list, name="terminal_growth"),+ )+++# ---------------------------------------------------------------------------+# Top-level orchestration+# ---------------------------------------------------------------------------+++@dataclass(frozen=True)+class DCFResult:+ """The full DCF: every bridge, both terminal values, and the final price.++ Attributes:+ wacc_build: The WACC build, with every component visible.+ fcff_bridge: One :class:`FCFFYear` per projection year.+ discounted_fcff: One :class:`DiscountedCashFlow` per projection year.+ pv_of_explicit_fcff: Sum of ``discounted_fcff[*].present_value``.+ terminal_value: Both terminal-value estimates and their cross-checks.+ terminal_value_method: Which of :data:`TERMINAL_VALUE_METHODS` was+ discounted into ``enterprise_value``. The other method's estimate+ is still fully computed and visible on ``terminal_value``.+ discounting_convention: Which of :data:`DISCOUNTING_CONVENTIONS` was used.+ terminal_discount_factor: Discount factor applied to the chosen+ terminal value -- the same factor used for the final explicit+ year, per the module docstring.+ pv_of_terminal_value: The chosen terminal value, discounted.+ enterprise_value: ``pv_of_explicit_fcff + pv_of_terminal_value``.+ net_debt_bridge: The full enterprise-value-to-equity-value bridge.+ equity_value: ``net_debt_bridge.equity_value``.+ value_per_share: ``net_debt_bridge.value_per_share``.+ """++ wacc_build: WACCResult+ fcff_bridge: tuple[FCFFYear, ...]+ discounted_fcff: tuple[DiscountedCashFlow, ...]+ pv_of_explicit_fcff: float+ terminal_value: TerminalValueResult+ terminal_value_method: str+ discounting_convention: str+ terminal_discount_factor: float+ pv_of_terminal_value: float+ enterprise_value: float+ net_debt_bridge: NetDebtBridgeResult+ equity_value: float+ value_per_share: float++ def __post_init__(self) -> None:+ """Re-check that the top-level rollups match their components.++ Raises:+ ValueError: If ``enterprise_value``, ``equity_value`` or+ ``value_per_share`` do not match the components they are+ built from.+ """+ expected_pv_explicit = sum(entry.present_value for entry in self.discounted_fcff)+ if not math.isclose(+ self.pv_of_explicit_fcff, expected_pv_explicit, rel_tol=1e-9, abs_tol=1e-6+ ):+ raise ValueError(+ f"DCFResult.pv_of_explicit_fcff={self.pv_of_explicit_fcff!r} does "+ f"not match sum(discounted_fcff.present_value)={expected_pv_explicit!r}"+ )+ expected_ev = self.pv_of_explicit_fcff + self.pv_of_terminal_value+ if not math.isclose(self.enterprise_value, expected_ev, rel_tol=1e-9, abs_tol=1e-6):+ raise ValueError(+ f"DCFResult.enterprise_value={self.enterprise_value!r} does not "+ f"match pv_of_explicit_fcff + pv_of_terminal_value = {expected_ev!r}"+ )+ if not math.isclose(+ self.enterprise_value, self.net_debt_bridge.enterprise_value, rel_tol=1e-9, abs_tol=1e-6+ ):+ raise ValueError(+ f"DCFResult.enterprise_value={self.enterprise_value!r} does not "+ f"match net_debt_bridge.enterprise_value="+ f"{self.net_debt_bridge.enterprise_value!r}"+ )+ if self.equity_value != self.net_debt_bridge.equity_value:+ raise ValueError(+ f"DCFResult.equity_value={self.equity_value!r} does not match "+ f"net_debt_bridge.equity_value={self.net_debt_bridge.equity_value!r}"+ )+ if self.value_per_share != self.net_debt_bridge.value_per_share:+ raise ValueError(+ f"DCFResult.value_per_share={self.value_per_share!r} does not "+ f"match net_debt_bridge.value_per_share="+ f"{self.net_debt_bridge.value_per_share!r}"+ )+++def run_dcf(+ inputs: Mapping[str, Any],+ *,+ capital_structure_basis: str,+ discounting_convention: str,+ terminal_value_method: str,+ gdp_growth_ceiling: float = DEFAULT_LONG_RUN_GDP_GROWTH_CEILING,+) -> DCFResult:+ """Run a complete DCF from a flat mapping of named inputs.++ This is the entry point :mod:`contracts` was written for: every required+ field is named, checked for presence up front, and the model refuses to+ run rather than substitute anything for one that is missing.++ Args:+ inputs: Flat mapping of raw inputs. Required keys are+ :data:`DCF_BASE_REQUIRED_FIELDS` plus+ :data:`DCF_CURRENT_STRUCTURE_FIELDS` (if+ ``capital_structure_basis="current"``) or+ :data:`DCF_TARGET_STRUCTURE_FIELDS` (if ``"target"``).+ ``inputs["terminal_growth"]`` and ``inputs["exit_multiple"]`` must+ each be an :class:`Assumption` (named ``"terminal_growth"`` /+ ``"exit_multiple"`` respectively), not a bare number. Optional+ keys ``"size_premium"`` and ``"country_risk_premium"`` default to+ ``0.0`` when absent (an explicit "not applying one", not a guessed+ magnitude). ``"ebit"``, ``"depreciation_amortization"``,+ ``"capex"`` and ``"delta_nwc"`` are equal-length sequences, one+ entry per projection year.+ capital_structure_basis: One of :data:`CAPITAL_STRUCTURE_BASES`.+ Required, no default.+ discounting_convention: One of :data:`DISCOUNTING_CONVENTIONS`.+ Required, no default.+ terminal_value_method: One of :data:`TERMINAL_VALUE_METHODS`, selecting+ which terminal-value estimate is discounted into+ ``enterprise_value``. Required, no default. Both estimates are+ always computed and cross-checked regardless of which is chosen --+ see ``DCFResult.terminal_value``.+ gdp_growth_ceiling: Reference ceiling used only to flag (never block)+ ``terminal_growth`` -- see :data:`DEFAULT_LONG_RUN_GDP_GROWTH_CEILING`.++ Returns:+ A :class:`DCFResult` with every intermediate figure visible.++ Raises:+ MissingInputError: If any required key is absent from ``inputs``.+ ValuationError: If ``capital_structure_basis``,+ ``discounting_convention`` or ``terminal_value_method`` is+ unrecognised; if ``terminal_growth`` or ``exit_multiple`` is not+ the matching :class:`Assumption`; if ``terminal_growth.value >=``+ the built WACC; if any capital-structure, FCFF-bridge or+ balance-sheet input fails its own guard (see :func:`wacc`,+ :func:`fcff_bridge`, :func:`terminal_value`, :func:`equity_bridge`).+ """+ if capital_structure_basis not in CAPITAL_STRUCTURE_BASES:+ raise ValuationError(+ f"run_dcf: capital_structure_basis must be one of "+ f"{CAPITAL_STRUCTURE_BASES}, got {capital_structure_basis!r}"+ )+ if discounting_convention not in DISCOUNTING_CONVENTIONS:+ raise ValuationError(+ f"run_dcf: discounting_convention must be one of "+ f"{DISCOUNTING_CONVENTIONS}, got {discounting_convention!r}"+ )+ if terminal_value_method not in TERMINAL_VALUE_METHODS:+ raise ValuationError(+ f"run_dcf: terminal_value_method must be one of "+ f"{TERMINAL_VALUE_METHODS}, got {terminal_value_method!r}"+ )++ structure_fields = (+ DCF_CURRENT_STRUCTURE_FIELDS+ if capital_structure_basis == "current"+ else DCF_TARGET_STRUCTURE_FIELDS+ )+ require_inputs(inputs, (*DCF_BASE_REQUIRED_FIELDS, *structure_fields), model="run_dcf")++ terminal_growth = _require_assumption(inputs["terminal_growth"], "terminal_growth", "run_dcf")+ exit_multiple = _require_assumption(inputs["exit_multiple"], "exit_multiple", "run_dcf")++ wacc_build = wacc(+ risk_free_rate=inputs["risk_free_rate"],+ beta=inputs["beta"],+ equity_risk_premium=inputs["equity_risk_premium"],+ pretax_cost_of_debt=inputs["pretax_cost_of_debt"],+ tax_rate=inputs["tax_rate"],+ capital_structure_basis=capital_structure_basis,+ market_value_of_equity=inputs.get("market_value_of_equity"),+ market_value_of_debt=inputs.get("market_value_of_debt"),+ target_equity_weight=inputs.get("target_equity_weight"),+ target_debt_weight=inputs.get("target_debt_weight"),+ size_premium=inputs.get("size_premium", 0.0),+ country_risk_premium=inputs.get("country_risk_premium", 0.0),+ )++ bridge = fcff_bridge(+ ebit=inputs["ebit"],+ tax_rate=inputs["tax_rate"],+ depreciation_amortization=inputs["depreciation_amortization"],+ capex=inputs["capex"],+ delta_nwc=inputs["delta_nwc"],+ )+ final_year = bridge[-1]+ terminal_year_ebitda = final_year.ebit + final_year.depreciation_amortization++ tv = terminal_value(+ final_year_fcff=final_year.fcff,+ terminal_year_ebitda=terminal_year_ebitda,+ wacc_rate=wacc_build.wacc,+ terminal_growth=terminal_growth,+ exit_multiple=exit_multiple,+ gdp_growth_ceiling=gdp_growth_ceiling,+ )++ discounted = discount_fcff(+ bridge, wacc_rate=wacc_build.wacc, discounting_convention=discounting_convention+ )+ pv_explicit = sum(entry.present_value for entry in discounted)++ chosen_tv = (+ tv.perpetuity_terminal_value+ if terminal_value_method == "perpetuity_growth"+ else tv.exit_terminal_value+ )+ # Discounted at the same timing as the final explicit year -- see the+ # module docstring for why this makes the mid-year/year-end enterprise+ # value ratio exactly sqrt(1 + WACC).+ terminal_discount_factor = discounted[-1].discount_factor+ pv_of_terminal_value = chosen_tv * terminal_discount_factor+ enterprise_value = pv_explicit + pv_of_terminal_value++ net_debt = equity_bridge(+ enterprise_value=enterprise_value,+ total_debt=inputs["total_debt"],+ cash_and_equivalents=inputs["cash_and_equivalents"],+ minority_interest=inputs["minority_interest"],+ preferred_equity=inputs["preferred_equity"],+ associate_investments=inputs["associate_investments"],+ diluted_shares=inputs["diluted_shares"],+ )++ return DCFResult(+ wacc_build=wacc_build,+ fcff_bridge=bridge,+ discounted_fcff=discounted,+ pv_of_explicit_fcff=pv_explicit,+ terminal_value=tv,+ terminal_value_method=terminal_value_method,+ discounting_convention=discounting_convention,+ terminal_discount_factor=terminal_discount_factor,+ pv_of_terminal_value=pv_of_terminal_value,+ enterprise_value=enterprise_value,+ net_debt_bridge=net_debt,+ equity_value=net_debt.equity_value,+ value_per_share=net_debt.value_per_share,+ )diff --git a/agent/src/quantlib/valuation/threestatement.py b/agent/src/quantlib/valuation/threestatement.pynew file mode 100644index 000000000..b7626d795--- /dev/null+++ b/agent/src/quantlib/valuation/threestatement.py@@ -0,0 +1,727 @@+"""Linked three-statement projection: P&L, cash flow and balance sheet, one model.++A three-statement model is only as good as its linkage. It is trivial to build+three spreadsheets that each look plausible in isolation and disagree the moment+you check whether assets equal liabilities plus equity -- that disagreement is+usually smoothed over with a hidden "plug" cell nobody labelled. This module+makes that failure mode structurally unreachable:++* Every line on the balance sheet is *derived* from the income statement and+ cash flow statement of the same period, never entered independently. Cash+ rolls forward by the cash flow statement's net change; retained earnings+ rolls forward by net income less dividends; PP&E rolls forward by capex less+ depreciation. There is nothing left to plug.+* :func:`check_balance_sheet` asserts ``assets == liabilities + equity`` after+ the opening balance sheet and after every projected period, and raises+ :class:`BalanceSheetError` naming the exact residual if it does not. Nothing+ catches or downgrades that exception -- an unbalanced period is not a+ projection, it is a bug.+* The one place this model deliberately keeps a balancing account is the+ **revolving credit facility**: if cash flow before financing would push cash+ below ``minimum_cash``, the revolver draws exactly the shortfall; if there is+ excess cash and an outstanding balance, the revolver sweeps exactly the+ excess (capped at what is owed). This is a plug in the sense that it exists+ to make the cash line come out right -- but it is *declared*, reported as its+ own field (:attr:`BalanceSheet.revolver_balance`, plus+ :attr:`CashFlowStatement.revolver_draw` / ``revolver_repayment``) and governed+ by an explicit, inspectable policy (``minimum_cash``). A silent plug hides+ what moved and why; this one names it on every period.++CIRCULARITY+-----------+Interest expense is charged on the *average* of the beginning and ending+revolver balance, which is standard practice (it does not reward or penalise a+company for exactly when in the period it drew or repaid). But the ending+balance depends on net income (through the cash available to repay or the+shortfall to cover), and net income depends on interest expense -- so a+period's own ending debt balance is defined in terms of itself. This module+resolves that with fixed-point iteration (see :func:`_project_period`): guess+an ending balance, price interest off it, run the statements through to a new+ending balance, and repeat until the guess stops moving. Every+:class:`PeriodResult` reports ``converged`` and ``iterations`` so a caller can+see the solve actually happened rather than trusting it silently. A period that+fails to converge within :data:`MAX_CIRCULARITY_ITERATIONS` raises+:class:`ConvergenceError` instead of returning the last guess dressed up as an+answer.++SCOPE, STATED PLAINLY+----------------------+* Dividends are paid only out of positive net income (``max(net_income, 0) *+ dividend_payout_ratio``); a loss-making period pays no dividend and receives+ no offsetting "negative dividend". The payout ratio itself is still a+ required, caller-supplied input -- this is a rule about how it applies, not a+ default value for it.+* Net working capital is carried as one net line (its ratio to revenue is a+ required driver); this model does not decompose it into receivables,+ inventory and payables. A negative NWC balance is valid and simply reduces+ total assets, which is mathematically identical to carrying the same net+ liability on the other side of the ledger.+* Paid-in capital never moves: this model has no share-issuance or buyback+ driver, so the only equity account that changes is retained earnings.+* Depreciation and interest rate are required per-period inputs, not derived+ from a ratio driver -- see :data:`DRIVER_REQUIRED_FIELDS`. A model that+ invented a depreciation-to-revenue ratio nobody asked for would be exactly+ the kind of silently-chosen assumption :mod:`.contracts` exists to prevent.++Every required input across the opening balance sheet and every driver is+checked with :func:`~src.quantlib.valuation.contracts.require_inputs` before+any arithmetic runs -- a missing field stops the model, never gets a default.+"""++from __future__ import annotations++import math+from collections.abc import Mapping, Sequence+from dataclasses import dataclass++from src.quantlib.valuation.contracts import (+ MissingInputError, # noqa: F401 -- re-exported for callers that catch it here+ ValuationError,+ require_inputs,+ require_positive,+)++__all__ = [+ "MODEL_NAME",+ "BALANCE_TOLERANCE_REL",+ "CIRCULARITY_TOLERANCE_REL",+ "MAX_CIRCULARITY_ITERATIONS",+ "OPENING_REQUIRED_FIELDS",+ "DRIVER_REQUIRED_FIELDS",+ "BalanceSheetError",+ "ConvergenceError",+ "IncomeStatement",+ "CashFlowStatement",+ "BalanceSheet",+ "PeriodResult",+ "ThreeStatementProjection",+ "check_balance_sheet",+ "project_three_statement",+]++#: Name used in every error message raised by this module.+MODEL_NAME = "three_statement_projection"++#: How far ``assets - (liabilities + equity)`` may drift, as a fraction of total+#: assets, before a balance sheet is refused. Scaled by assets (not an absolute+#: dollar amount) so the same tolerance is equally strict for a $10k projection+#: and a $10bn one. 1e-9 is far looser than the ~1e-12..1e-10 floating-point+#: noise a correctly-linked model accumulates over a handful of chained+#: arithmetic operations, and far tighter than any real accounting break, so it+#: catches genuine plugs without ever flagging rounding.+BALANCE_TOLERANCE_REL: float = 1e-9++#: Fixed-point convergence tolerance for the interest/revolver circularity,+#: expressed relative to the ending debt balance being solved for. Set an order+#: of magnitude tighter than BALANCE_TOLERANCE_REL because the balance-sheet+#: check is downstream of this solve: a loosely-converged debt balance would+#: still make the accounting identity hold exactly (it holds for any+#: self-consistent snapshot, converged or not -- see the module docstring), but+#: it would report a period whose interest was not actually priced off its own+#: ending balance. The tightness here is about answering the right economic+#: question, not about balancing.+CIRCULARITY_TOLERANCE_REL: float = 1e-10++#: Iteration budget for the revolver/interest fixed point. Realistic financing+#: rates put the loop's contraction factor -- roughly+#: ``(1 - payout) * (1 - tax) * interest_rate / 2`` from averaging the two debt+#: balances -- well under 0.5 per period, which reaches CIRCULARITY_TOLERANCE_REL+#: in well under 10 passes. 100 leaves an order of magnitude of headroom for+#: unusually high-yield financing before a genuinely non-convergent (contraction+#: factor >= 1) input is refused instead of silently truncated.+MAX_CIRCULARITY_ITERATIONS: int = 100++#: Required keys of the ``opening`` mapping passed to :func:`project_three_statement`.+OPENING_REQUIRED_FIELDS: tuple[str, ...] = (+ "revenue",+ "cash",+ "net_working_capital",+ "ppe",+ "revolver_balance",+ "paid_in_capital",+ "retained_earnings",+)++#: Required keys of the ``drivers`` mapping passed to :func:`project_three_statement`.+#: Every value must be a sequence of the same length -- one entry per projected+#: period. ``depreciation_amortization``, ``interest_rate`` and ``minimum_cash``+#: are required alongside the seven ratio/rate drivers because the linkage the+#: model exists to enforce (D&A into the PP&E rollforward, interest into the+#: revolver circularity, minimum_cash into the revolver policy) has no+#: economically defensible ratio to default them from; see the module docstring.+DRIVER_REQUIRED_FIELDS: tuple[str, ...] = (+ "revenue_growth",+ "gross_margin",+ "opex_pct_revenue",+ "capex_pct_revenue",+ "nwc_pct_revenue",+ "tax_rate",+ "dividend_payout_ratio",+ "depreciation_amortization",+ "interest_rate",+ "minimum_cash",+)+++class BalanceSheetError(ValuationError):+ """Raised when a balance sheet fails ``assets == liabilities + equity``.++ Attributes:+ period: The period index that failed (0 is the opening balance sheet).+ assets: Total assets computed for that period.+ liabilities: Total liabilities computed for that period.+ equity: Total equity computed for that period.+ residual: ``assets - liabilities - equity``. Non-zero is the failure.+ tolerance: The relative tolerance that was exceeded.+ """++ def __init__(self, period: int, assets: float, liabilities: float, equity: float, tolerance: float) -> None:+ self.period = period+ self.assets = assets+ self.liabilities = liabilities+ self.equity = equity+ self.residual = assets - liabilities - equity+ self.tolerance = tolerance+ super().__init__(+ f"{MODEL_NAME}: period {period} balance sheet does not balance -- "+ f"assets {assets!r} != liabilities {liabilities!r} + equity {equity!r} "+ f"(residual {self.residual!r}, tolerance {tolerance!r} of assets). "+ "This model derives every balance-sheet line from the income "+ "statement and cash flow statement; a non-zero residual means an "+ "input or a rollforward was overridden by hand, not that the model "+ "chose to plug it."+ )+++class ConvergenceError(ValuationError):+ """Raised when the interest/revolver circularity fails to converge.++ Attributes:+ period: The period whose fixed-point solve failed.+ iterations: How many iterations were attempted (equals the budget).+ last_delta: The absolute change in the ending debt balance on the final+ iteration -- still larger than ``tolerance`` allowed.+ tolerance: The relative convergence tolerance that was not met.+ """++ def __init__(self, period: int, iterations: int, last_delta: float, tolerance: float) -> None:+ self.period = period+ self.iterations = iterations+ self.last_delta = last_delta+ self.tolerance = tolerance+ super().__init__(+ f"{MODEL_NAME}: period {period} interest/revolver circularity did not "+ f"converge in {iterations} iteration(s) (last change in ending debt "+ f"{last_delta!r}, tolerance {tolerance!r}). Refusing to return the "+ "last iteration's numbers as if they were a solved period -- widen "+ "max_circularity_iterations only after confirming the loop is "+ "actually contracting, not just slow."+ )+++@dataclass(frozen=True)+class IncomeStatement:+ """One period's income statement, linked end to end.++ The chain is ``revenue -> gross_profit -> ebitda -> (less D&A) -> ebit ->+ (less interest) -> pretax_income -> (less tax) -> net_income``.++ Attributes:+ period: 1-indexed projection period.+ revenue: Period revenue.+ gross_profit: ``revenue * gross_margin``.+ opex: Operating expense, ``revenue * opex_pct_revenue``.+ ebitda: ``gross_profit - opex``.+ depreciation_amortization: D&A for the period (a required input, not a+ derived ratio -- see the module docstring).+ ebit: ``ebitda - depreciation_amortization``.+ interest_expense: Interest on the average revolver balance for the+ period; the output of the circularity solve.+ pretax_income: ``ebit - interest_expense``.+ tax_expense: ``pretax_income * tax_rate``. Negative when pretax income+ is negative -- this model does not model a tax-loss carryforward,+ so a loss period shows a tax benefit at the same rate.+ net_income: ``pretax_income - tax_expense``.+ """++ period: int+ revenue: float+ gross_profit: float+ opex: float+ ebitda: float+ depreciation_amortization: float+ ebit: float+ interest_expense: float+ pretax_income: float+ tax_expense: float+ net_income: float++ @property+ def cogs(self) -> float:+ """Return cost of goods sold, implied by revenue and gross profit.++ Returns:+ ``revenue - gross_profit``.+ """+ return self.revenue - self.gross_profit+++@dataclass(frozen=True)+class CashFlowStatement:+ """One period's cash flow statement, bridging net income to the cash change.++ Implements ``net_income + D&A - change_in_net_working_capital - capex ++ financing_activities = net_change_in_cash`` exactly.++ Attributes:+ period: 1-indexed projection period.+ net_income: Copied from the period's :class:`IncomeStatement`.+ depreciation_amortization: Added back as a non-cash expense.+ change_in_net_working_capital: ``nwc_end - nwc_begin``. A positive+ value (NWC grew) is a use of cash and is subtracted.+ capex: Capital expenditure, a use of cash.+ dividends_paid: Cash dividends for the period (zero in a loss period;+ see the module docstring).+ revolver_draw: Cash drawn on the revolver this period (>= 0). This is+ the explicit, reported plug that keeps cash from falling below+ ``minimum_cash``.+ revolver_repayment: Cash used to pay down the revolver this period+ (>= 0), capped at the balance outstanding.+ financing_activities: ``revolver_draw - revolver_repayment -+ dividends_paid``.+ net_change_in_cash: The full bridge total; matches+ ``BalanceSheet.cash - previous BalanceSheet.cash`` exactly.+ """++ period: int+ net_income: float+ depreciation_amortization: float+ change_in_net_working_capital: float+ capex: float+ dividends_paid: float+ revolver_draw: float+ revolver_repayment: float+ financing_activities: float+ net_change_in_cash: float++ @property+ def cash_flow_from_operations(self) -> float:+ """Return operating cash flow, before investing and financing.++ Returns:+ ``net_income + depreciation_amortization - change_in_net_working_capital``.+ """+ return self.net_income + self.depreciation_amortization - self.change_in_net_working_capital++ @property+ def free_cash_flow(self) -> float:+ """Return free cash flow, before financing activities.++ Returns:+ :attr:`cash_flow_from_operations` minus :attr:`capex`.+ """+ return self.cash_flow_from_operations - self.capex+++@dataclass(frozen=True)+class BalanceSheet:+ """One period's balance sheet. Every field is a rollforward, never an input.++ ``period=0`` is the opening balance sheet supplied by the caller; every+ other period is derived: cash rolls forward by the cash flow statement's+ net change, PP&E by capex less D&A, the revolver by its draws and+ repayments, and retained earnings by net income less dividends. Paid-in+ capital never moves (see the module docstring).++ Attributes:+ period: 0 for the opening balance sheet, 1-indexed thereafter.+ cash: Ending cash balance.+ net_working_capital: Ending net working capital (a single net line;+ see the module docstring).+ ppe: Ending net property, plant and equipment.+ revolver_balance: Ending balance on the revolving credit facility --+ the model's one explicit, reported plug.+ paid_in_capital: Contributed capital. Constant across every period.+ retained_earnings: Ending retained earnings; may be negative.+ """++ period: int+ cash: float+ net_working_capital: float+ ppe: float+ revolver_balance: float+ paid_in_capital: float+ retained_earnings: float++ @property+ def total_assets(self) -> float:+ """Return total assets.++ Returns:+ ``cash + net_working_capital + ppe``.+ """+ return self.cash + self.net_working_capital + self.ppe++ @property+ def total_liabilities(self) -> float:+ """Return total liabilities.++ Returns:+ ``revolver_balance`` -- the only liability this model carries.+ """+ return self.revolver_balance++ @property+ def total_equity(self) -> float:+ """Return total equity.++ Returns:+ ``paid_in_capital + retained_earnings``.+ """+ return self.paid_in_capital + self.retained_earnings+++@dataclass(frozen=True)+class PeriodResult:+ """One projected period's linked statements plus circularity diagnostics.++ Attributes:+ period: 1-indexed projection period.+ income_statement: The period's :class:`IncomeStatement`.+ cash_flow_statement: The period's :class:`CashFlowStatement`.+ balance_sheet: The period's :class:`BalanceSheet`, already checked by+ :func:`check_balance_sheet` before this object is returned.+ converged: Whether the interest/revolver fixed point converged. Always+ ``True`` on a returned :class:`PeriodResult` -- a non-convergent+ period raises :class:`ConvergenceError` instead of being returned;+ the field is kept on the result so a caller inspecting a completed+ projection does not have to take convergence on faith.+ iterations: Number of fixed-point iterations the circularity solve+ took. ``1`` means the initial guess (no revolver movement) was+ already the fixed point -- for example, a period with zero+ beginning debt and no shortfall.+ """++ period: int+ income_statement: IncomeStatement+ cash_flow_statement: CashFlowStatement+ balance_sheet: BalanceSheet+ converged: bool+ iterations: int+++@dataclass(frozen=True)+class ThreeStatementProjection:+ """A full multi-period projection: the opening balance sheet plus every period.++ Attributes:+ opening_balance_sheet: The caller-supplied opening balance sheet+ (``period=0``), already checked by :func:`check_balance_sheet`.+ periods: Projected periods in chronological order, 1-indexed.+ """++ opening_balance_sheet: BalanceSheet+ periods: tuple[PeriodResult, ...]+++def check_balance_sheet(balance_sheet: BalanceSheet, tolerance: float = BALANCE_TOLERANCE_REL) -> None:+ """Assert that a balance sheet balances, or raise naming the residual.++ Args:+ balance_sheet: The balance sheet to check.+ tolerance: Largest tolerated ``|residual| / max(total_assets, 1.0)``.+ Defaults to :data:`BALANCE_TOLERANCE_REL`.++ Raises:+ BalanceSheetError: If ``assets != liabilities + equity`` beyond+ ``tolerance``. The exception carries the exact residual.+ """+ assets = balance_sheet.total_assets+ liabilities = balance_sheet.total_liabilities+ equity = balance_sheet.total_equity+ residual = assets - liabilities - equity+ scale = max(abs(assets), 1.0)+ if abs(residual) > tolerance * scale:+ raise BalanceSheetError(balance_sheet.period, assets, liabilities, equity, tolerance)+++def _resolve_period_count(drivers: Mapping[str, Sequence[float]]) -> int:+ """Validate every driver sequence shares one non-zero length and return it.++ Args:+ drivers: The driver mapping already checked by+ :func:`~src.quantlib.valuation.contracts.require_inputs`.++ Returns:+ The number of periods to project.++ Raises:+ ValuationError: If the driver sequences disagree in length, or all are+ empty.+ """+ lengths = {field: len(drivers[field]) for field in DRIVER_REQUIRED_FIELDS}+ distinct = set(lengths.values())+ if len(distinct) > 1:+ detail = ", ".join(f"{field}={n}" for field, n in lengths.items())+ raise ValuationError(+ f"{MODEL_NAME}: every driver sequence must share one length (one entry "+ f"per projected period); got {detail}"+ )+ periods = distinct.pop()+ if periods < 1:+ raise ValuationError(+ f"{MODEL_NAME}: driver sequences are empty; at least one projection "+ "period is required"+ )+ return periods+++def _project_period(+ period: int,+ prior_bs: BalanceSheet,+ prior_revenue: float,+ revenue_growth: float,+ gross_margin: float,+ opex_pct_revenue: float,+ capex_pct_revenue: float,+ nwc_pct_revenue: float,+ tax_rate: float,+ dividend_payout_ratio: float,+ depreciation_amortization: float,+ interest_rate: float,+ minimum_cash: float,+ circularity_tolerance: float,+ max_circularity_iterations: int,+) -> PeriodResult:+ """Project one period, solving the interest/revolver circularity by iteration.++ See the module docstring for the fixed-point scheme: the ending revolver+ balance is guessed, interest is priced on the average of the beginning and+ guessed ending balance, the statements are run through to a freshly+ computed ending balance, and the guess is replaced by that value until it+ stops moving.++ Args:+ period: 1-indexed period being projected.+ prior_bs: The previous period's (or the opening) balance sheet.+ prior_revenue: The previous period's (or the opening) revenue.+ revenue_growth: This period's revenue growth rate.+ gross_margin: This period's gross margin.+ opex_pct_revenue: This period's operating expense as a fraction of revenue.+ capex_pct_revenue: This period's capex as a fraction of revenue.+ nwc_pct_revenue: This period's net working capital as a fraction of revenue.+ tax_rate: This period's tax rate.+ dividend_payout_ratio: This period's dividend payout ratio (applied to+ positive net income only).+ depreciation_amortization: This period's D&A, in currency units.+ interest_rate: This period's interest rate on the average revolver balance.+ minimum_cash: This period's minimum cash the revolver policy targets.+ circularity_tolerance: Relative convergence tolerance on the ending+ revolver balance.+ max_circularity_iterations: Iteration budget before refusing to answer.++ Returns:+ The period's :class:`PeriodResult`, with a balance sheet that has+ already passed :func:`check_balance_sheet`.++ Raises:+ ConvergenceError: If the fixed point does not converge within+ ``max_circularity_iterations``.+ BalanceSheetError: If the resulting balance sheet does not balance+ (this should be unreachable given the rollforwards below, and its+ presence here is a deliberate defensive check, not the primary+ guard -- see the module docstring).+ """+ revenue = prior_revenue * (1.0 + revenue_growth)+ gross_profit = revenue * gross_margin+ opex = revenue * opex_pct_revenue+ ebitda = gross_profit - opex+ ebit = ebitda - depreciation_amortization+ capex = revenue * capex_pct_revenue+ nwc_end = revenue * nwc_pct_revenue+ change_in_nwc = nwc_end - prior_bs.net_working_capital++ debt_begin = prior_bs.revolver_balance+ debt_end_guess = debt_begin++ interest_expense = pretax_income = tax_expense = net_income = 0.0+ dividends_paid = revolver_draw = revolver_repayment = 0.0+ debt_end_actual = debt_end_guess+ cash_end = prior_bs.cash+ delta = float("inf")+ converged = False+ iterations = 0++ for iterations in range(1, max_circularity_iterations + 1):+ avg_debt = (debt_begin + debt_end_guess) / 2.0+ interest_expense = interest_rate * avg_debt+ pretax_income = ebit - interest_expense+ tax_expense = pretax_income * tax_rate+ net_income = pretax_income - tax_expense+ dividends_paid = max(net_income, 0.0) * dividend_payout_ratio++ cash_flow_before_financing = net_income + depreciation_amortization - change_in_nwc - capex - dividends_paid+ cash_before_revolver = prior_bs.cash + cash_flow_before_financing++ if cash_before_revolver >= minimum_cash:+ surplus = cash_before_revolver - minimum_cash+ revolver_repayment = min(surplus, debt_begin)+ revolver_draw = 0.0+ else:+ revolver_draw = minimum_cash - cash_before_revolver+ revolver_repayment = 0.0++ debt_end_actual = debt_begin + revolver_draw - revolver_repayment+ cash_end = cash_before_revolver + revolver_draw - revolver_repayment++ scale = max(abs(debt_end_actual), 1.0)+ delta = abs(debt_end_actual - debt_end_guess)+ if delta <= circularity_tolerance * scale:+ converged = True+ break+ debt_end_guess = debt_end_actual++ if not converged:+ raise ConvergenceError(period, iterations, delta, circularity_tolerance)++ financing_activities = revolver_draw - revolver_repayment - dividends_paid+ net_change_in_cash = net_income + depreciation_amortization - change_in_nwc - capex + financing_activities++ income_statement = IncomeStatement(+ period=period,+ revenue=revenue,+ gross_profit=gross_profit,+ opex=opex,+ ebitda=ebitda,+ depreciation_amortization=depreciation_amortization,+ ebit=ebit,+ interest_expense=interest_expense,+ pretax_income=pretax_income,+ tax_expense=tax_expense,+ net_income=net_income,+ )+ cash_flow_statement = CashFlowStatement(+ period=period,+ net_income=net_income,+ depreciation_amortization=depreciation_amortization,+ change_in_net_working_capital=change_in_nwc,+ capex=capex,+ dividends_paid=dividends_paid,+ revolver_draw=revolver_draw,+ revolver_repayment=revolver_repayment,+ financing_activities=financing_activities,+ net_change_in_cash=net_change_in_cash,+ )+ balance_sheet = BalanceSheet(+ period=period,+ cash=cash_end,+ net_working_capital=nwc_end,+ ppe=prior_bs.ppe + capex - depreciation_amortization,+ revolver_balance=debt_end_actual,+ paid_in_capital=prior_bs.paid_in_capital,+ retained_earnings=prior_bs.retained_earnings + net_income - dividends_paid,+ )+ check_balance_sheet(balance_sheet)++ return PeriodResult(+ period=period,+ income_statement=income_statement,+ cash_flow_statement=cash_flow_statement,+ balance_sheet=balance_sheet,+ converged=converged,+ iterations=iterations,+ )+++def project_three_statement(+ opening: Mapping[str, float],+ drivers: Mapping[str, Sequence[float]],+ circularity_tolerance: float = CIRCULARITY_TOLERANCE_REL,+ max_circularity_iterations: int = MAX_CIRCULARITY_ITERATIONS,+ balance_tolerance: float = BALANCE_TOLERANCE_REL,+) -> ThreeStatementProjection:+ """Project linked income, cash flow and balance-sheet statements forward.++ Args:+ opening: The opening balance sheet plus trailing revenue. Must contain+ every field in :data:`OPENING_REQUIRED_FIELDS`.+ drivers: Per-period driver sequences. Must contain every field in+ :data:`DRIVER_REQUIRED_FIELDS`, each a sequence of the same length+ (one entry per projected period, chronological order).+ circularity_tolerance: Relative convergence tolerance for the+ interest/revolver fixed point. Defaults to+ :data:`CIRCULARITY_TOLERANCE_REL`.+ max_circularity_iterations: Iteration budget for that fixed point.+ Defaults to :data:`MAX_CIRCULARITY_ITERATIONS`.+ balance_tolerance: Relative tolerance for the hard balance-sheet check.+ Defaults to :data:`BALANCE_TOLERANCE_REL`.++ Returns:+ A :class:`ThreeStatementProjection` whose opening and every projected+ balance sheet has passed :func:`check_balance_sheet`, and whose every+ :class:`PeriodResult` converged.++ Raises:+ MissingInputError: If ``opening`` or ``drivers`` is missing a required+ field.+ ValuationError: If the driver sequences disagree in length, are empty,+ or if ``circularity_tolerance`` / ``balance_tolerance`` /+ ``max_circularity_iterations`` are not usable.+ BalanceSheetError: If the opening balance sheet, or any projected+ period's balance sheet, does not balance.+ ConvergenceError: If any period's interest/revolver circularity fails+ to converge within ``max_circularity_iterations``.+ """+ require_inputs(opening, OPENING_REQUIRED_FIELDS, MODEL_NAME)+ require_inputs(drivers, DRIVER_REQUIRED_FIELDS, MODEL_NAME)+ circularity_tolerance = require_positive(circularity_tolerance, "circularity_tolerance", MODEL_NAME)+ balance_tolerance = require_positive(balance_tolerance, "balance_tolerance", MODEL_NAME)+ if max_circularity_iterations < 1:+ raise ValuationError(+ f"{MODEL_NAME}: max_circularity_iterations must be >= 1, got "+ f"{max_circularity_iterations!r}"+ )++ periods = _resolve_period_count(drivers)++ opening_balance_sheet = BalanceSheet(+ period=0,+ cash=float(opening["cash"]),+ net_working_capital=float(opening["net_working_capital"]),+ ppe=float(opening["ppe"]),+ revolver_balance=float(opening["revolver_balance"]),+ paid_in_capital=float(opening["paid_in_capital"]),+ retained_earnings=float(opening["retained_earnings"]),+ )+ check_balance_sheet(opening_balance_sheet, balance_tolerance)++ prior_bs = opening_balance_sheet+ prior_revenue = float(opening["revenue"])+ results: list[PeriodResult] = []+ for index in range(periods):+ result = _project_period(+ period=index + 1,+ prior_bs=prior_bs,+ prior_revenue=prior_revenue,+ revenue_growth=float(drivers["revenue_growth"][index]),+ gross_margin=float(drivers["gross_margin"][index]),+ opex_pct_revenue=float(drivers["opex_pct_revenue"][index]),+ capex_pct_revenue=float(drivers["capex_pct_revenue"][index]),+ nwc_pct_revenue=float(drivers["nwc_pct_revenue"][index]),+ tax_rate=float(drivers["tax_rate"][index]),+ dividend_payout_ratio=float(drivers["dividend_payout_ratio"][index]),+ depreciation_amortization=float(drivers["depreciation_amortization"][index]),+ interest_rate=float(drivers["interest_rate"][index]),+ minimum_cash=float(drivers["minimum_cash"][index]),+ circularity_tolerance=circularity_tolerance,+ max_circularity_iterations=max_circularity_iterations,+ )+ # Defensive re-check with the caller's tolerance: _project_period already+ # checked with the module default, but a caller-widened balance_tolerance+ # must not be allowed to let a period through unchecked at its own bar.+ check_balance_sheet(result.balance_sheet, balance_tolerance)+ results.append(result)+ prior_bs = result.balance_sheet+ prior_revenue = result.income_statement.revenue++ return ThreeStatementProjection(opening_balance_sheet=opening_balance_sheet, periods=tuple(results))diff --git a/agent/src/quantlib/var_backtest.py b/agent/src/quantlib/var_backtest.pynew file mode 100644index 000000000..30007e1ea--- /dev/null+++ b/agent/src/quantlib/var_backtest.py@@ -0,0 +1,654 @@+"""VaR model backtesting: does the model's stated confidence level hold up?++``src.quantlib.risk`` *produces* VaR numbers. This module *validates* them, which+is a separate job with a separate consumer: a risk function has to demonstrate+that a 99% VaR was breached on roughly 1% of days, and that the breaches did not+arrive in clusters. A VaR that is right on average and wrong in bursts is the one+that ends a firm, because the losses land consecutively while the model still+reports a passing exception count.++Three tests, deliberately kept separate rather than collapsed into one verdict:++``kupiec_pof``+ Unconditional coverage. Are there the right *number* of breaches? Blind to+ when they happened -- a model breached ten days running and then never again+ passes this test.++``christoffersen_independence``+ Independence. Does a breach today predict a breach tomorrow? Blind to the+ level -- a model breached on 30% of days but evenly scattered passes this+ test.++``christoffersen_conditional_coverage``+ Both at once: ``LR_cc = LR_uc + LR_ind``, the sum being exact because the+ two restrictions are nested. Reported alongside its components, never+ instead of them, because a rejection tells you nothing about which half+ failed.++``basel_traffic_light`` is the supervisory overlay: the zone follows from the+cumulative binomial probability of the observed exception count, which is the+general form of the rule. The 1996 Basel scaling-factor table, by contrast, is+tabulated for a **250-day window at 99%** and is only reported when the sample+actually matches that; applying those multipliers to a 60-day sample would be a+category error dressed as a regulatory figure. See+:data:`BASEL_SCALING_FACTORS`.++WHAT COUNTS AS A BREACH+-----------------------+``return < -var``. The sign convention is inherited unchanged from+:mod:`src.quantlib.risk`: **a loss is a positive number**, so a 99% VaR of+``0.028`` means "a 2.8% loss", and a day returning ``-0.031`` breaches it while a+day returning ``-0.019`` does not. A VaR series that arrives negative is not+silently flipped -- see :func:`violation_indicator`.++ALIGNMENT IS NOT ASSUMED+------------------------+When both the returns and the VaR arrive as pandas Series, they are joined on+their index and any non-overlapping observation is an **error**, not a silent+drop. An off-by-one join between a return series and the VaR that was supposed+to have been forecast for it produces a plausible-looking exception count from+comparing each day against the wrong day's forecast, and nothing downstream can+detect it.+"""++from __future__ import annotations++from collections.abc import Sequence+from dataclasses import dataclass++import numpy as np+import pandas as pd+from scipy.special import xlogy+from scipy.stats import binom, chi2++__all__ = [+ "BASEL_GREEN_MAX_CDF",+ "BASEL_RED_MIN_CDF",+ "BASEL_SCALING_FACTORS",+ "BASEL_WINDOW",+ "BASEL_CONFIDENCE",+ "ConditionalCoverageResult",+ "IndependenceResult",+ "KupiecResult",+ "TrafficLightResult",+ "VarBacktestReport",+ "violation_indicator",+ "kupiec_pof",+ "christoffersen_independence",+ "christoffersen_conditional_coverage",+ "basel_traffic_light",+ "var_backtest",+]++#: Cumulative binomial probability at or above which the Basel zone leaves green.+BASEL_GREEN_MAX_CDF: float = 0.95++#: Cumulative binomial probability at or above which the Basel zone becomes red.+BASEL_RED_MIN_CDF: float = 0.9999++#: Observation count the Basel scaling-factor table is tabulated for.+BASEL_WINDOW: int = 250++#: VaR confidence level the Basel scaling-factor table is tabulated for.+BASEL_CONFIDENCE: float = 0.99++#: Basel (1996) capital scaling factors by exception count, for a 250-day+#: backtest of a 99% VaR. Counts of 10 or more sit in the red zone at 4.00.+#: Keyed by exception count; only defined over the yellow zone and its+#: boundaries, because green is flat at 3.00 and red is flat at 4.00.+BASEL_SCALING_FACTORS: dict[int, float] = {+ 0: 3.00, 1: 3.00, 2: 3.00, 3: 3.00, 4: 3.00,+ 5: 3.40, 6: 3.50, 7: 3.65, 8: 3.75, 9: 3.85,+}++#: Scaling factor applied to every red-zone exception count.+BASEL_RED_SCALING_FACTOR: float = 4.00+++@dataclass(frozen=True)+class KupiecResult:+ """Outcome of the Kupiec proportion-of-failures test.++ Attributes:+ observations: Number of paired observations tested.+ violations: Number of days the loss exceeded VaR.+ expected_violations: ``observations * (1 - confidence)``.+ violation_rate: Realised breach frequency, ``violations / observations``.+ expected_rate: ``1 - confidence``, the rate the model claims.+ statistic: Likelihood-ratio statistic ``LR_uc``, chi-square with 1 df.+ p_value: Probability of a statistic this large if the model is correct.+ rejected: True when ``p_value < significance``.+ significance: Significance level the rejection was judged at.+ """++ observations: int+ violations: int+ expected_violations: float+ violation_rate: float+ expected_rate: float+ statistic: float+ p_value: float+ rejected: bool+ significance: float+++@dataclass(frozen=True)+class IndependenceResult:+ """Outcome of the Christoffersen independence test.++ Attributes:+ transitions: Counts ``(n00, n01, n10, n11)`` of consecutive state pairs,+ where state 1 is a breach day.+ prob_breach_after_calm: Estimated P(breach tomorrow | no breach today).+ prob_breach_after_breach: Estimated P(breach tomorrow | breach today).+ statistic: Likelihood-ratio statistic ``LR_ind``, chi-square with 1 df.+ p_value: Probability of a statistic this large under independence.+ rejected: True when ``p_value < significance``.+ significance: Significance level the rejection was judged at.+ identified: False when the sample cannot distinguish the two transition+ probabilities at all -- no breach occurred, or every breach sits at+ the very end of the sample. The statistic is then 0 by construction+ and the test carries no evidence either way.+ """++ transitions: tuple[int, int, int, int]+ prob_breach_after_calm: float+ prob_breach_after_breach: float+ statistic: float+ p_value: float+ rejected: bool+ significance: float+ identified: bool+++@dataclass(frozen=True)+class ConditionalCoverageResult:+ """Outcome of the joint Christoffersen conditional-coverage test.++ Attributes:+ statistic: ``LR_cc = LR_uc + LR_ind``, chi-square with 2 df.+ p_value: Probability of a statistic this large if the model is correct.+ rejected: True when ``p_value < significance``.+ significance: Significance level the rejection was judged at.+ kupiec: The unconditional-coverage component.+ independence: The independence component.+ """++ statistic: float+ p_value: float+ rejected: bool+ significance: float+ kupiec: KupiecResult+ independence: IndependenceResult+++@dataclass(frozen=True)+class TrafficLightResult:+ """Basel supervisory zone for an observed exception count.++ Attributes:+ zone: ``"green"``, ``"yellow"`` or ``"red"``.+ violations: Observed exception count.+ observations: Number of paired observations tested.+ cumulative_probability: ``P(X <= violations)`` under the model's own+ claimed breach probability. This is what the zone is cut on.+ scaling_factor: Basel capital multiplier, or None when the sample does+ not match the tabulated basis (see ``scaling_factor_basis``).+ scaling_factor_basis: Why ``scaling_factor`` is or is not populated.+ """++ zone: str+ violations: int+ observations: int+ cumulative_probability: float+ scaling_factor: float | None+ scaling_factor_basis: str+++@dataclass(frozen=True)+class VarBacktestReport:+ """Every test in this module, run over one aligned return/VaR pair.++ Attributes:+ confidence: VaR confidence level tested.+ observations: Number of paired observations after alignment.+ violations: Number of breaches.+ dropped_observations: Pairs discarded because either side was non-finite.+ kupiec: Unconditional-coverage result.+ independence: Independence result.+ conditional_coverage: Joint result.+ traffic_light: Basel zone.+ breach_dates: Index labels of the breaches when the inputs carried an+ index, else None. A risk committee reads the dates, not the count.+ """++ confidence: float+ observations: int+ violations: int+ dropped_observations: int+ kupiec: KupiecResult+ independence: IndependenceResult+ conditional_coverage: ConditionalCoverageResult+ traffic_light: TrafficLightResult+ breach_dates: tuple[object, ...] | None+++def _align(+ returns: pd.Series | np.ndarray | Sequence[float],+ var: pd.Series | np.ndarray | Sequence[float] | float,+) -> tuple[np.ndarray, np.ndarray, pd.Index | None, int]:+ """Pair each return with the VaR forecast that was made for it.++ Args:+ returns: Realised returns, signed (a loss is negative).+ var: VaR forecasts as positive loss magnitudes, either one per return or+ a single scalar applied to every return.++ Returns:+ Tuple of ``(returns, var, index, dropped)``: two equal-length finite+ float arrays, the surviving index when the inputs carried one, and the+ number of pairs dropped for holding a non-finite value.++ Raises:+ ValueError: If either input is not 1-D, if two indexed Series do not+ cover exactly the same labels, if the lengths differ, or if no+ finite pair survives.+ """+ ret_index = returns.index if isinstance(returns, pd.Series) else None+ var_index = var.index if isinstance(var, pd.Series) else None++ if ret_index is not None and var_index is not None:+ if not ret_index.equals(var_index):+ only_ret = ret_index.difference(var_index)+ only_var = var_index.difference(ret_index)+ raise ValueError(+ "returns and var must cover exactly the same labels; "+ f"{len(only_ret)} label(s) only in returns and "+ f"{len(only_var)} only in var. Align them explicitly -- a "+ "partial join silently compares each day against another day's "+ "forecast."+ )++ ret_values = np.asarray(returns, dtype=float)+ if ret_values.ndim > 1:+ raise ValueError(f"returns must be 1-D, got shape {ret_values.shape}")+ ret_values = ret_values.ravel()++ var_values = np.asarray(var, dtype=float)+ if var_values.ndim == 0:+ var_values = np.full(ret_values.shape, float(var_values))+ else:+ if var_values.ndim > 1:+ raise ValueError(f"var must be 1-D or scalar, got shape {var_values.shape}")+ var_values = var_values.ravel()++ if ret_values.size != var_values.size:+ raise ValueError(+ f"returns and var must be the same length, got {ret_values.size} "+ f"and {var_values.size}"+ )+ if ret_values.size == 0:+ raise ValueError("returns is empty")++ keep = np.isfinite(ret_values) & np.isfinite(var_values)+ dropped = int((~keep).sum())+ if not keep.any():+ raise ValueError("no observation has a finite return and a finite var")++ index = ret_index if ret_index is not None else var_index+ kept_index = index[keep] if index is not None else None+ return ret_values[keep], var_values[keep], kept_index, dropped+++def violation_indicator(+ returns: pd.Series | np.ndarray | Sequence[float],+ var: pd.Series | np.ndarray | Sequence[float] | float,+) -> np.ndarray:+ """Flag the days on which the realised loss exceeded the VaR forecast.++ Args:+ returns: Realised returns, signed. A 3% loss is ``-0.03``.+ var: VaR forecasts as positive loss magnitudes, one per return or a+ single scalar. A negative entry is not flipped: it is taken at face+ value, meaning "the model expects a gain even in the tail", which is+ almost always a caller-side sign error and shows up here as an+ implausible breach count rather than as a silently corrected input.++ Returns:+ Boolean array, True where ``return < -var``. Equality is not a breach:+ a loss exactly equal to VaR is the level the model promised, not an+ excess of it.++ Raises:+ ValueError: If the inputs cannot be aligned (see :func:`_align`).+ """+ ret_values, var_values, _, _ = _align(returns, var)+ return ret_values < -var_values+++def kupiec_pof(+ violations: int,+ observations: int,+ confidence: float = 0.99,+ significance: float = 0.05,+) -> KupiecResult:+ """Test whether the breach *count* matches the model's claimed level.++ The Kupiec proportion-of-failures test compares the realised breach rate+ against ``1 - confidence`` by likelihood ratio::++ LR_uc = -2 * [ (n-x)*ln(1-p) + x*ln(p)+ - (n-x)*ln(1-x/n) - x*ln(x/n) ]++ distributed chi-square with 1 degree of freedom. The ``0 * ln(0) = 0``+ convention makes the zero-breach and all-breach cases well defined rather+ than special.++ Args:+ violations: Number of days the loss exceeded VaR.+ observations: Number of days tested.+ confidence: VaR confidence level the model claims, e.g. 0.99.+ significance: Level at which ``rejected`` is decided.++ Returns:+ A :class:`KupiecResult`.++ Raises:+ ValueError: If ``observations`` is not positive, if ``violations`` is+ negative or exceeds ``observations``, or if either probability is+ not strictly between 0 and 1.+ """+ if observations <= 0:+ raise ValueError(f"observations must be > 0, got {observations}")+ if not 0 <= violations <= observations:+ raise ValueError(+ f"violations must be in [0, {observations}], got {violations}"+ )+ if not 0.0 < confidence < 1.0:+ raise ValueError(f"confidence must be in (0, 1), got {confidence}")+ if not 0.0 < significance < 1.0:+ raise ValueError(f"significance must be in (0, 1), got {significance}")++ expected_rate = 1.0 - confidence+ observed_rate = violations / observations+ calm = observations - violations++ restricted = xlogy(calm, 1.0 - expected_rate) + xlogy(violations, expected_rate)+ unrestricted = xlogy(calm, 1.0 - observed_rate) + xlogy(violations, observed_rate)+ statistic = float(max(-2.0 * (restricted - unrestricted), 0.0))+ p_value = float(chi2.sf(statistic, df=1))++ return KupiecResult(+ observations=observations,+ violations=violations,+ expected_violations=observations * expected_rate,+ violation_rate=observed_rate,+ expected_rate=expected_rate,+ statistic=statistic,+ p_value=p_value,+ rejected=p_value < significance,+ significance=significance,+ )+++def christoffersen_independence(+ breaches: Sequence[bool] | np.ndarray,+ significance: float = 0.05,+) -> IndependenceResult:+ """Test whether breaches cluster in time.++ Fits a first-order Markov chain to the breach sequence and tests the+ restriction that the two transition probabilities are equal::++ LR_ind = -2 * [ (n00+n10)*ln(1-pi) + (n01+n11)*ln(pi)+ - n00*ln(1-pi01) - n01*ln(pi01)+ - n10*ln(1-pi11) - n11*ln(pi11) ]++ distributed chi-square with 1 degree of freedom. This is the test that+ catches a model whose exception count looks fine because all ten breaches+ landed in the same fortnight.++ Args:+ breaches: Boolean sequence in chronological order, True on breach days.+ significance: Level at which ``rejected`` is decided.++ Returns:+ An :class:`IndependenceResult`. When the sample holds no breach, or+ holds breaches only in its final position, the transition probabilities+ are not separately identified; the statistic is then 0 with+ ``identified=False`` rather than an arbitrary number.++ Raises:+ ValueError: If ``breaches`` holds fewer than two observations or is not+ 1-D, or if ``significance`` is not strictly between 0 and 1.+ """+ if not 0.0 < significance < 1.0:+ raise ValueError(f"significance must be in (0, 1), got {significance}")++ flags = np.asarray(breaches)+ if flags.ndim != 1:+ raise ValueError(f"breaches must be 1-D, got shape {flags.shape}")+ if flags.size < 2:+ raise ValueError(+ f"breaches needs at least 2 observations to hold a transition, got {flags.size}"+ )+ flags = flags.astype(bool)++ prev, curr = flags[:-1], flags[1:]+ n00 = int(np.sum(~prev & ~curr))+ n01 = int(np.sum(~prev & curr))+ n10 = int(np.sum(prev & ~curr))+ n11 = int(np.sum(prev & curr))++ from_calm = n00 + n01+ from_breach = n10 + n11+ total = from_calm + from_breach++ pi01 = n01 / from_calm if from_calm else 0.0+ pi11 = n11 / from_breach if from_breach else 0.0+ pi = (n01 + n11) / total if total else 0.0++ # Not identified when no day follows a breach: pi11 has no sample behind it,+ # so the restriction it is supposed to relax cannot be tested.+ identified = from_breach > 0 and from_calm > 0++ if not identified:+ statistic = 0.0+ else:+ restricted = xlogy(n00 + n10, 1.0 - pi) + xlogy(n01 + n11, pi)+ unrestricted = (+ xlogy(n00, 1.0 - pi01)+ + xlogy(n01, pi01)+ + xlogy(n10, 1.0 - pi11)+ + xlogy(n11, pi11)+ )+ statistic = float(max(-2.0 * (restricted - unrestricted), 0.0))++ p_value = float(chi2.sf(statistic, df=1))+ return IndependenceResult(+ transitions=(n00, n01, n10, n11),+ prob_breach_after_calm=pi01,+ prob_breach_after_breach=pi11,+ statistic=statistic,+ p_value=p_value,+ rejected=identified and p_value < significance,+ significance=significance,+ identified=identified,+ )+++def christoffersen_conditional_coverage(+ breaches: Sequence[bool] | np.ndarray,+ confidence: float = 0.99,+ significance: float = 0.05,+) -> ConditionalCoverageResult:+ """Test coverage and independence jointly.++ ``LR_cc = LR_uc + LR_ind`` with 2 degrees of freedom. The components are+ returned alongside it because the joint statistic alone cannot say whether+ the model failed on level, on timing, or on both -- and the remedies differ.++ Args:+ breaches: Boolean sequence in chronological order, True on breach days.+ confidence: VaR confidence level the model claims.+ significance: Level at which each ``rejected`` flag is decided.++ Returns:+ A :class:`ConditionalCoverageResult`.++ Raises:+ ValueError: Propagated from the component tests.+ """+ flags = np.asarray(breaches)+ if flags.ndim != 1:+ raise ValueError(f"breaches must be 1-D, got shape {flags.shape}")+ flags = flags.astype(bool)++ kupiec = kupiec_pof(+ violations=int(flags.sum()),+ observations=int(flags.size),+ confidence=confidence,+ significance=significance,+ )+ independence = christoffersen_independence(flags, significance=significance)++ statistic = kupiec.statistic + independence.statistic+ p_value = float(chi2.sf(statistic, df=2))+ return ConditionalCoverageResult(+ statistic=statistic,+ p_value=p_value,+ rejected=p_value < significance,+ significance=significance,+ kupiec=kupiec,+ independence=independence,+ )+++def basel_traffic_light(+ violations: int,+ observations: int,+ confidence: float = BASEL_CONFIDENCE,+) -> TrafficLightResult:+ """Place an exception count in the Basel supervisory zone.++ The zone is cut on the cumulative binomial probability of the observed+ count under the model's own claimed breach probability -- green below+ :data:`BASEL_GREEN_MAX_CDF`, red at or above :data:`BASEL_RED_MIN_CDF`,+ yellow between. That is the general form of the rule and it holds for any+ sample size.++ The capital scaling factor is a different matter. :data:`BASEL_SCALING_FACTORS`+ is tabulated for a 250-day backtest of a 99% VaR, and is reported only when+ the sample matches that basis. On any other sample the zone is still+ meaningful but the multiplier is not, so it comes back None rather than+ borrowed from a table that was never fitted to it.++ Args:+ violations: Observed exception count.+ observations: Number of days tested.+ confidence: VaR confidence level the model claims.++ Returns:+ A :class:`TrafficLightResult`.++ Raises:+ ValueError: If ``observations`` is not positive, if ``violations`` is+ outside ``[0, observations]``, or if ``confidence`` is not strictly+ between 0 and 1.+ """+ if observations <= 0:+ raise ValueError(f"observations must be > 0, got {observations}")+ if not 0 <= violations <= observations:+ raise ValueError(+ f"violations must be in [0, {observations}], got {violations}"+ )+ if not 0.0 < confidence < 1.0:+ raise ValueError(f"confidence must be in (0, 1), got {confidence}")++ breach_prob = 1.0 - confidence+ cdf = float(binom.cdf(violations, observations, breach_prob))++ if cdf < BASEL_GREEN_MAX_CDF:+ zone = "green"+ elif cdf < BASEL_RED_MIN_CDF:+ zone = "yellow"+ else:+ zone = "red"++ on_basis = observations == BASEL_WINDOW and confidence == BASEL_CONFIDENCE+ if not on_basis:+ scaling_factor = None+ basis = (+ f"not reported: the Basel table is tabulated for {BASEL_WINDOW} "+ f"observations at {BASEL_CONFIDENCE:.0%} confidence, this sample is "+ f"{observations} at {confidence:.0%}"+ )+ else:+ scaling_factor = BASEL_SCALING_FACTORS.get(violations, BASEL_RED_SCALING_FACTOR)+ basis = (+ f"Basel (1996) table for {BASEL_WINDOW} observations at "+ f"{BASEL_CONFIDENCE:.0%} confidence"+ )++ return TrafficLightResult(+ zone=zone,+ violations=violations,+ observations=observations,+ cumulative_probability=cdf,+ scaling_factor=scaling_factor,+ scaling_factor_basis=basis,+ )+++def var_backtest(+ returns: pd.Series | np.ndarray | Sequence[float],+ var: pd.Series | np.ndarray | Sequence[float] | float,+ confidence: float = 0.99,+ significance: float = 0.05,+) -> VarBacktestReport:+ """Run every test in this module over one return/VaR pair.++ Args:+ returns: Realised returns, signed, in chronological order.+ var: VaR forecasts as positive loss magnitudes -- one per return, or a+ scalar for a constant-VaR model. When both sides are indexed Series+ the labels must match exactly.+ confidence: VaR confidence level the model claims, e.g. 0.99.+ significance: Level at which each ``rejected`` flag is decided.++ Returns:+ A :class:`VarBacktestReport` carrying the Kupiec, independence, joint+ and Basel results plus the breach dates when an index was supplied.++ Raises:+ ValueError: If the inputs cannot be aligned, if fewer than two finite+ pairs survive, or if either probability is out of range.+ """+ ret_values, var_values, index, dropped = _align(returns, var)+ if ret_values.size < 2:+ raise ValueError(+ f"var_backtest needs at least 2 aligned observations, got {ret_values.size}"+ )++ breaches = ret_values < -var_values+ conditional = christoffersen_conditional_coverage(+ breaches, confidence=confidence, significance=significance+ )+ traffic = basel_traffic_light(+ violations=int(breaches.sum()),+ observations=int(breaches.size),+ confidence=confidence,+ )+ breach_dates = tuple(index[breaches]) if index is not None else None++ return VarBacktestReport(+ confidence=confidence,+ observations=int(breaches.size),+ violations=int(breaches.sum()),+ dropped_observations=dropped,+ kupiec=conditional.kupiec,+ independence=conditional.independence,+ conditional_coverage=conditional,+ traffic_light=traffic,+ breach_dates=breach_dates,+ )diff --git a/agent/src/tools/orderbook_depth_tool.py b/agent/src/tools/orderbook_depth_tool.pynew file mode 100644index 000000000..1112066c1--- /dev/null+++ b/agent/src/tools/orderbook_depth_tool.py@@ -0,0 +1,507 @@+"""Read-only crypto L2 order-book depth tool (OKX / Binance spot, via ccxt).++Built to close a documented gap: ``src/swarm/presets/statistical_arbitrage_desk.yaml``+tells its microstructure analyst "There is no order-book depth or quote feed+here" because that is true for the equity data sources this project has for+free — but it is *not* true for crypto. OKX and Binance both publish full L2+order-book snapshots over public, no-auth REST, and this project already+depends on ``ccxt>=4.0.0`` (see ``pyproject.toml``) and already talks to both+venues for OHLCV (``backtest/loaders/okx.py``, ``backtest/loaders/binance_loader.py``).+This tool reuses that same connectivity — ccxt's unified ``fetch_order_book``+— instead of hand-rolling per-venue REST parsing.++Symbol convention matches the rest of this repo (see CLAUDE.md: "OKX pairs+use ``BTC-USDT`` format, hyphen, uppercase") and ``ccxt_loader._parse_ccxt_symbol``:+the caller passes ``BASE-QUOTE`` (e.g. ``BTC-USDT``), which is upper-cased and+translated to ccxt's ``BASE/QUOTE`` form before the request. Perpetuals+(``-PERP``) are out of scope here — this tool is spot-book depth only.++What ccxt's ``fetch_order_book`` actually returns (read from the installed+``ccxt==4.5.54`` source, not assumed): ``parse_order_book`` always returns+``{"symbol", "bids", "asks", "timestamp", "datetime", "nonce"}`` where+``bids`` is sorted descending by price and ``asks`` ascending — i.e. index 0+on each side is always the best price, by construction of+``Exchange.parse_order_book``. This module still re-sorts defensively before+using either side (cheap, and removes any reliance on that upstream+invariant holding for every exchange/version). ``timestamp`` is venue+end-to-end epoch milliseconds when the venue's payload carries one — for+Binance *spot* depth (``GET /api/v3/depth``) it does not: ccxt's own+``fetch_order_book`` reads a ``"T"`` field that only appears in the+futures/options response shapes (see ``ccxt.binance.fetch_order_book``+docstring examples), so ``timestamp`` comes back ``None`` for Binance spot.+When that happens this tool falls back to the local fetch time and marks+``timestamp_source`` accordingly, rather than silently passing a null-dated+snapshot to the caller (an order book is only valid for seconds — the reader+must be able to tell how fresh it is either way).++The network call is isolated in :func:`_fetch_raw_book` for exactly one+reason: tests monkeypatch that single function and never touch the network,+same pattern as ``tests/test_prediction_market_tool.py`` monkeypatching+``throttled_get_json`` on its own tool module.++Domain decisions worth being explicit about (also covered in the tests):++* **Units.** Every ``amount``/``amount_base`` is a quantity of the pair's+ BASE asset. Every ``*_notional_quote`` / ``notional_quote`` / price is in+ the pair's QUOTE asset — USDT for ``BTC-USDT``, but BTC for ``ETH-BTC``.+ These are never averaged or added together; the ``units`` block on every+ response spells this out so a caller cannot mix them by accident.+* **Mid price** is always ``(best_bid + best_ask) / 2``. If either side of+ the book is empty this tool refuses to compute a mid price (or anything+ downstream of it) rather than guessing — see the empty-book handling below.+* **Crossed book** (``best_bid >= best_ask``) is treated as a data error and+ rejected outright. A negative or zero spread is never returned.+* **Impact-cost sizing.** "A market order for $10,000 notional" is sized+ identically for both directions: ``base_qty_target = notional_quote /+ mid_price``, computed once from the pre-trade mid. The buy side then walks+ the (fully fetched, not just the displayed) ask ladder consuming that many+ base units; the sell side walks the bid ladder the same way. This keeps+ buy and sell directly comparable (same order size) instead of the sell+ side chasing a moving quote-proceeds target, which would make the two+ sides answer different questions.+* **Partial fills are always reported, never disguised as full fills.** If+ the fetched ladder (``_BOOK_FETCH_LIMIT`` levels — see below) cannot+ satisfy ``base_qty_target``, the response carries ``fully_filled: false``,+ the actual ``filled_base_qty`` / ``filled_notional_quote`` (which will be+ less than requested), and an explanatory ``note``. The average price and+ slippage are still computed over whatever *was* filled — a partial number+ is more honest than no number, as long as it is labelled partial.+* **Fetch depth vs. requested depth are different knobs.** ``levels``+ (1..``_MAX_LEVELS``) controls how many rows are echoed back in ``depth``+ and how many are used for the imbalance ratio. Impact cost always walks+ the full ``_BOOK_FETCH_LIMIT``-level ladder pulled from the exchange+ (100 levels — a valid discrete Binance depth tier and well under OKX's+ 400-row default-endpoint cap), regardless of ``levels``, since a $10k+ order can easily need more rows than a human wants echoed back.+"""++from __future__ import annotations++import json+import logging+import math+from datetime import datetime, timezone+from typing import Any++from backtest.loaders.ccxt_loader import _CCXT_TIMEOUT_MS, _ccxt_proxy_config+from src.agent.tools import BaseTool++logger = logging.getLogger(__name__)++_EXCHANGES = ("okx", "binance")+_DEFAULT_EXCHANGE = "okx"++_DEFAULT_LEVELS = 10+_MAX_LEVELS = 50++# Rows pulled from the exchange per call. Fixed (not caller-configurable):+# impact-cost needs headroom beyond whatever `levels` the caller wants+# echoed back, and 100 is a valid discrete Binance order-book depth tier+# (5/10/20/50/100/500/1000/5000) while sitting comfortably under OKX's+# default-endpoint 400-row cap — one request works cleanly against both.+_BOOK_FETCH_LIMIT = 100++_DEFAULT_NOTIONAL_QUOTE = 10_000.0++_UNITS = {+ "amount_base": "quantity of the pair's BASE asset (e.g. BTC in BTC-USDT) — never a currency value",+ "price": "quote-asset price of 1 unit of base (e.g. USDT per BTC in BTC-USDT)",+ "notional_quote / *_notional_quote / filled_notional_quote": (+ "value denominated in the pair's QUOTE asset (USDT for BTC-USDT, but "+ "BTC for ETH-BTC — read the quote leg off the symbol, do not assume USD)"+ ),+ "relative_bps / slippage_bps": "basis points (1 bps = 0.01%), relative to mid_price at fetch time",+ "normalized_imbalance": (+ "(bid_notional_quote - ask_notional_quote) / (bid_notional_quote + ask_notional_quote), "+ "in [-1, 1]. Positive = more resting buy-side notional (bid-heavy), negative = ask-heavy"+ ),+}+++def _fetch_raw_book(exchange_id: str, ccxt_symbol: str, limit: int) -> dict[str, Any]:+ """Fetch one L2 order-book snapshot via ccxt's public REST API.++ Isolated as its own function so tests can monkeypatch exactly this name+ and never open a socket — see the module docstring.++ Args:+ exchange_id: ``"okx"`` or ``"binance"`` (a ccxt exchange id).+ ccxt_symbol: Unified ccxt symbol, e.g. ``"BTC/USDT"``.+ limit: Number of levels per side requested from the venue.++ Returns:+ A ccxt ``OrderBook`` dict: ``{"symbol", "bids", "asks", "timestamp",+ "datetime", "nonce"}``.++ Raises:+ Exception: Whatever ccxt raises for a network, symbol, or venue error.+ """+ import ccxt++ exchange_cls = getattr(ccxt, exchange_id)+ config: dict[str, Any] = {"enableRateLimit": True, "timeout": _CCXT_TIMEOUT_MS}+ proxies = _ccxt_proxy_config()+ if proxies:+ config["proxies"] = proxies+ exchange = exchange_cls(config)+ return exchange.fetch_order_book(ccxt_symbol, limit)+++def _error(message: str) -> str:+ """Build the failure envelope as a JSON string."""+ return json.dumps({"ok": False, "error": message}, ensure_ascii=False)+++def _parse_symbol(raw: Any) -> tuple[str, str] | None:+ """Validate + normalize a ``BASE-QUOTE`` symbol into ``(display, ccxt)`` forms.++ Args:+ raw: Caller-supplied symbol, e.g. ``"btc-usdt"``.++ Returns:+ ``(normalized_hyphen_symbol, ccxt_slash_symbol)``, or ``None`` when+ ``raw`` is not a well-formed ``BASE-QUOTE`` string.+ """+ if not isinstance(raw, str):+ return None+ normalized = raw.strip().upper()+ parts = normalized.split("-")+ if len(parts) != 2 or not parts[0] or not parts[1]:+ return None+ if not parts[0].isalnum() or not parts[1].isalnum():+ return None+ return normalized, f"{parts[0]}/{parts[1]}"+++def _coerce_int(value: Any) -> int | None:+ """Coerce a parameter to int, accepting the JSON shapes an LLM tends to send."""+ if isinstance(value, bool):+ return None+ if isinstance(value, int):+ return value+ if isinstance(value, float):+ return int(value) if value.is_integer() else None+ if isinstance(value, str):+ try:+ number = float(value.strip())+ except ValueError:+ return None+ return int(number) if number.is_integer() else None+ return None+++def _coerce_float(value: Any) -> float | None:+ """Coerce a parameter to a finite float."""+ if isinstance(value, bool):+ return None+ if isinstance(value, (int, float)):+ number = float(value)+ elif isinstance(value, str):+ try:+ number = float(value.strip())+ except ValueError:+ return None+ else:+ return None+ return number if math.isfinite(number) else None+++def _clean_levels(raw: Any) -> list[tuple[float, float]]:+ """Normalize a ccxt bids/asks array into sorted-by-caller ``(price, amount)`` pairs.++ Rows with a non-positive or non-finite price/amount are dropped rather+ than propagated into downstream arithmetic (a zero-amount row would+ silently no-op through the impact walk; a negative one would corrupt it).++ Args:+ raw: The ``bids`` or ``asks`` value from a ccxt order-book dict.++ Returns:+ A list of ``(price, amount)`` float pairs, in whatever order ``raw``+ had them (the caller sorts).+ """+ out: list[tuple[float, float]] = []+ if not isinstance(raw, list):+ return out+ for row in raw:+ if not isinstance(row, (list, tuple)) or len(row) < 2:+ continue+ try:+ price = float(row[0])+ amount = float(row[1])+ except (TypeError, ValueError):+ continue+ if not math.isfinite(price) or not math.isfinite(amount):+ continue+ if price <= 0 or amount <= 0:+ continue+ out.append((price, amount))+ return out+++def _walk_book(levels: list[tuple[float, float]], base_qty_target: float) -> dict[str, Any]:+ """Consume ``levels`` (best price first) until ``base_qty_target`` base units are filled.++ Args:+ levels: ``(price, amount)`` pairs in walk order (best price first);+ the caller is responsible for that ordering.+ base_qty_target: Base-asset quantity the simulated market order wants+ to fill.++ Returns:+ ``{"filled_base_qty", "filled_notional_quote", "avg_price",+ "levels_used", "fully_filled", "unfilled_base_qty"}``. ``avg_price``+ is ``None`` only when nothing at all could be filled (e.g. the side+ was empty, though callers already reject that case upstream).+ """+ remaining = base_qty_target+ base_filled = 0.0+ quote_filled = 0.0+ levels_used = 0+ for price, amount in levels:+ if remaining <= 0:+ break+ take = min(amount, remaining)+ base_filled += take+ quote_filled += take * price+ remaining -= take+ levels_used += 1+ # Tolerance absorbs float noise from the running subtraction above; it is+ # not a relaxed pass/fail threshold on the caller's requested size.+ fully_filled = remaining <= 1e-9+ return {+ "filled_base_qty": base_filled,+ "filled_notional_quote": quote_filled,+ "avg_price": (quote_filled / base_filled) if base_filled > 0 else None,+ "levels_used": levels_used,+ "fully_filled": fully_filled,+ "unfilled_base_qty": max(remaining, 0.0),+ }+++class OrderBookDepthTool(BaseTool):+ """Read-only crypto L2 order-book depth: raw levels, spread, imbalance, impact cost."""++ name = "orderbook_depth"+ repeatable = True+ is_readonly = True+ description = (+ "READ-ONLY crypto L2 order-book snapshot from OKX or Binance spot "+ "public REST (via ccxt) — the depth/quote feed equity sources here "+ "cannot provide. Returns: (1) raw bid/ask levels (price + base-asset "+ "amount, up to 'levels' per side); (2) bid-ask spread, absolute and "+ "relative in bps; (3) depth imbalance within 'levels' — "+ "bid-notional/ask-notional ratio and a normalized (B-A)/(B+A) score "+ "in [-1, 1]; (4) impact cost — for a simulated market order sized at "+ "'notional_quote' (in the pair's quote asset, e.g. USDT for "+ "BTC-USDT), the volume-weighted average fill price and slippage in "+ "bps vs. mid price, computed BOTH for a buy (walking asks) and a "+ "sell (walking bids). A snapshot is only valid for seconds — every "+ "response carries a timestamp and 'exchange'. A quote-side that "+ "can't fill the full requested notional reports 'fully_filled: "+ "false' with the actually-filled amount, never a fabricated full "+ "fill. An empty book, a one-sided-empty book, or a crossed book "+ "(best_bid >= best_ask, a data error) is refused with an explicit "+ "error rather than a guessed number. Spot only, no perpetuals. "+ 'Example: {"symbol": "BTC-USDT", "exchange": "okx", "levels": 10, '+ '"notional_quote": 10000}.'+ )+ parameters = {+ "type": "object",+ "properties": {+ "symbol": {+ "type": "string",+ "description": (+ "BASE-QUOTE pair, hyphenated and uppercase (OKX-style), "+ "e.g. 'BTC-USDT' or 'ETH-BTC'. Required."+ ),+ },+ "exchange": {+ "type": "string",+ "enum": list(_EXCHANGES),+ "description": "Which venue's public order book to read.",+ "default": _DEFAULT_EXCHANGE,+ },+ "levels": {+ "type": "integer",+ "description": (+ f"Number of price levels per side to return in 'depth' "+ f"and to use for the imbalance calculation (1-{_MAX_LEVELS})."+ ),+ "default": _DEFAULT_LEVELS,+ },+ "notional_quote": {+ "type": "number",+ "description": (+ "Simulated market-order size, in the pair's QUOTE asset "+ "(USDT for BTC-USDT), used for the impact-cost "+ "calculation. Must be positive."+ ),+ "default": _DEFAULT_NOTIONAL_QUOTE,+ },+ },+ "required": ["symbol"],+ }++ def execute(self, **kwargs: Any) -> str:+ """Fetch one order-book snapshot and return the depth/spread/imbalance/impact envelope.++ Args:+ **kwargs: ``symbol`` (required), plus optional ``exchange``,+ ``levels``, ``notional_quote``.++ Returns:+ A JSON string. On success: ``{"ok": true, "source": "ccxt",+ "market": "crypto", "units": {...}, "data": {...}}``. On failure+ (bad params, empty/one-sided/crossed book, or a request error):+ ``{"ok": false, "error": str}``.+ """+ parsed = _parse_symbol(kwargs.get("symbol"))+ if parsed is None:+ return _error(+ "symbol is required and must be BASE-QUOTE, hyphenated and "+ "uppercase, e.g. 'BTC-USDT' (got "+ f"{kwargs.get('symbol')!r})"+ )+ display_symbol, ccxt_symbol = parsed++ exchange_id = kwargs.get("exchange", _DEFAULT_EXCHANGE)+ if exchange_id not in _EXCHANGES:+ return _error(f"exchange must be one of {list(_EXCHANGES)}, got {exchange_id!r}")++ levels_raw = kwargs.get("levels", _DEFAULT_LEVELS)+ levels = _coerce_int(levels_raw)+ if levels is None or levels < 1 or levels > _MAX_LEVELS:+ return _error(+ f"levels must be an integer between 1 and {_MAX_LEVELS} "+ f"(got {levels_raw!r})"+ )++ notional_raw = kwargs.get("notional_quote", _DEFAULT_NOTIONAL_QUOTE)+ notional_quote = _coerce_float(notional_raw)+ if notional_quote is None or notional_quote <= 0:+ return _error(f"notional_quote must be a positive number (got {notional_raw!r})")++ try:+ raw_book = _fetch_raw_book(exchange_id, ccxt_symbol, _BOOK_FETCH_LIMIT)+ except Exception as exc: # noqa: BLE001 - surface as error envelope+ return _error(f"{exchange_id} order book request failed for {display_symbol}: {exc}")++ if not isinstance(raw_book, dict):+ return _error(f"unexpected order book payload shape from {exchange_id}")++ bids = sorted(_clean_levels(raw_book.get("bids")), key=lambda lvl: lvl[0], reverse=True)+ asks = sorted(_clean_levels(raw_book.get("asks")), key=lambda lvl: lvl[0])++ if not bids and not asks:+ return _error(f"order book for {display_symbol} on {exchange_id} is empty (no bids or asks)")+ if not bids:+ return _error(+ f"order book for {display_symbol} on {exchange_id} has no bids — "+ "refusing to compute mid price / spread from a one-sided book"+ )+ if not asks:+ return _error(+ f"order book for {display_symbol} on {exchange_id} has no asks — "+ "refusing to compute mid price / spread from a one-sided book"+ )++ best_bid_price, best_bid_qty = bids[0]+ best_ask_price, best_ask_qty = asks[0]+ if best_bid_price >= best_ask_price:+ return _error(+ f"crossed book for {display_symbol} on {exchange_id}: "+ f"best_bid {best_bid_price} >= best_ask {best_ask_price}. "+ "This is a data error — refusing to compute a spread from it."+ )++ mid_price = (best_bid_price + best_ask_price) / 2.0+ spread_abs = best_ask_price - best_bid_price+ spread_bps = (spread_abs / mid_price) * 10_000.0++ timestamp_ms = raw_book.get("timestamp")+ if isinstance(timestamp_ms, (int, float)) and not isinstance(timestamp_ms, bool):+ timestamp = (+ datetime.fromtimestamp(timestamp_ms / 1000.0, tz=timezone.utc)+ .isoformat()+ .replace("+00:00", "Z")+ )+ timestamp_source = "exchange"+ else:+ # Binance spot depth carries no server timestamp field at all+ # (ccxt's parser only finds one in the futures/options response+ # shapes) — fetch time is the honest fallback, explicitly labelled+ # so a caller never mistakes it for a venue-stamped time.+ timestamp = datetime.now(tz=timezone.utc).isoformat().replace("+00:00", "Z")+ timestamp_source = "local_fetch_time"++ depth_bids = bids[:levels]+ depth_asks = asks[:levels]+ bid_notional = sum(p * a for p, a in depth_bids)+ ask_notional = sum(p * a for p, a in depth_asks)+ total_notional = bid_notional + ask_notional+ normalized_imbalance = (+ (bid_notional - ask_notional) / total_notional if total_notional > 0 else 0.0+ )++ base_qty_target = notional_quote / mid_price+ buy = _walk_book(asks, base_qty_target)+ buy["notional_quote_requested"] = notional_quote+ buy["slippage_bps"] = (+ ((buy["avg_price"] - mid_price) / mid_price) * 10_000.0+ if buy["avg_price"] is not None+ else None+ )+ sell = _walk_book(bids, base_qty_target)+ sell["notional_quote_requested"] = notional_quote+ sell["slippage_bps"] = (+ ((mid_price - sell["avg_price"]) / mid_price) * 10_000.0+ if sell["avg_price"] is not None+ else None+ )+ for side_name, side in (("buy", buy), ("sell", sell)):+ if not side["fully_filled"]:+ side["note"] = (+ f"could not fill the full {notional_quote} notional within the "+ f"{len(asks) if side_name == 'buy' else len(bids)} "+ f"{'ask' if side_name == 'buy' else 'bid'} level(s) fetched "+ f"(exchange fetch limit={_BOOK_FETCH_LIMIT}); filled_notional_quote "+ "and avg_price reflect only the partial fill actually achieved. "+ "This may mean genuinely thin liquidity, or just that the book "+ "goes deeper than this snapshot's fetched window."+ )++ data = {+ "exchange": exchange_id,+ "symbol": display_symbol,+ "ccxt_symbol": ccxt_symbol,+ "timestamp": timestamp,+ "timestamp_source": timestamp_source,+ "best_bid": {"price": best_bid_price, "amount_base": best_bid_qty},+ "best_ask": {"price": best_ask_price, "amount_base": best_ask_qty},+ "mid_price": mid_price,+ "spread": {"absolute_quote": spread_abs, "relative_bps": spread_bps},+ "depth": {+ "levels": levels,+ "bids": [{"price": p, "amount_base": a} for p, a in depth_bids],+ "asks": [{"price": p, "amount_base": a} for p, a in depth_asks],+ },+ "imbalance": {+ "levels": levels,+ "bid_notional_quote": bid_notional,+ "ask_notional_quote": ask_notional,+ "ratio_bid_over_ask": (bid_notional / ask_notional) if ask_notional > 0 else None,+ "normalized_imbalance": normalized_imbalance,+ },+ "impact_cost": {+ "notional_quote": notional_quote,+ "base_qty_target": base_qty_target,+ "buy": buy,+ "sell": sell,+ },+ "levels_available": {"bids": len(bids), "asks": len(asks)},+ }+ return json.dumps(+ {"ok": True, "source": "ccxt", "market": "crypto", "units": _UNITS, "data": data},+ ensure_ascii=False,+ )diff --git a/agent/src/tools/quantlib_tool.py b/agent/src/tools/quantlib_tool.pynew file mode 100644index 000000000..cdcff3638--- /dev/null+++ b/agent/src/tools/quantlib_tool.py@@ -0,0 +1,449 @@+"""Reach the finance-math layer from every transport, without a shell.++``src/quantlib`` holds ~250 tested functions, and until now the only way an+agent could run them was ``bash`` plus an ``import``. That gate is off by+default on the API and MCP transports, and correctly so: process-control tools+are an RCE surface regardless of transport, and force-enabling them on stdio was+the subject of two published advisories (see+``mcp_server._resolve_include_shell_tools``). So on Web, API and MCP the maths+layer was simply unreachable.++Widening the shell gate to fix that would trade a real security property for a+convenience. This tool takes the other route: one stable contract that can call+any *public* function of an allowlisted quantlib module, and nothing else.++WHY THIS IS NOT ARBITRARY CODE EXECUTION+----------------------------------------+Three structural limits, in order of what they rule out:++1. **Module allowlist.** Only the modules in :data:`ALLOWED_MODULES` are+ reachable. There is no path from a caller-supplied string to an arbitrary+ import -- the string is looked up in a dict, never passed to ``importlib``.+2. **``__all__`` only.** Within a module, only names the module itself exports+ are callable. A private helper, a re-exported third-party symbol, or a+ dunder is not reachable.+3. **No file-writing entry points.** Names matching :data:`_WRITER_PREFIXES` are+ refused even when exported, because they take a destination path. Everything+ left is pure computation: no filesystem, no network, no process. Use+ ``write_file`` if a file is what you want.++WHAT THIS DOES NOT DO+---------------------+It does not fetch data. Every argument comes from the caller, which usually+means a data tool ran first. A function that needs a price history needs you to+have retrieved that history.++PASSING PANDAS OBJECTS OVER JSON+--------------------------------+Several functions need a real indexed ``Series`` or ``DataFrame``, and a bare+JSON list loses the index -- which for an event study or a cash-flow series is+the part that carries the meaning. Two envelopes are therefore understood+anywhere in ``kwargs``::++ {"__series__": {"index": [...], "values": [...]}}+ {"__dataframe__": {"index": [...], "columns": [...], "data": [[...], ...]}}++A plain list stays a plain list, because most functions accept a sequence and+coercing every list into a Series would break the ones that do not.+"""++from __future__ import annotations++import dataclasses+import inspect+import json+import math+from enum import Enum+from typing import Any++from src.agent.tools import BaseTool++__all__ = ["ALLOWED_MODULES", "QuantlibCallTool"]++#: Short name -> dotted module path. A caller names the short form; nothing a+#: caller sends is ever handed to ``importlib``.+ALLOWED_MODULES: dict[str, str] = {+ "options": "src.quantlib.options",+ "fixedincome": "src.quantlib.fixedincome",+ "credit": "src.quantlib.credit",+ "timeseries": "src.quantlib.timeseries",+ "risk": "src.quantlib.risk",+ "var_backtest": "src.quantlib.var_backtest",+ "attribution": "src.quantlib.attribution",+ "impact": "src.quantlib.impact",+ "fundmath": "src.quantlib.fundmath",+ "performance": "src.quantlib.performance",+ "eventstudy": "src.quantlib.eventstudy",+ "factormodel": "src.quantlib.factormodel",+ "multipletesting": "src.quantlib.multipletesting",+ "crossvalidation": "src.quantlib.crossvalidation",+ "valuation.dcf": "src.quantlib.valuation.dcf",+ "valuation.comps": "src.quantlib.valuation.comps",+ "valuation.threestatement": "src.quantlib.valuation.threestatement",+ "valuation.artifact": "src.quantlib.valuation.artifact",+ "valuation.contracts": "src.quantlib.valuation.contracts",+}++#: Exported names refused because they write to a caller-supplied path. This+#: tool stays pure-compute; file creation belongs to ``write_file``.+_WRITER_PREFIXES: tuple[str, ...] = ("export_",)++#: Largest number of leaf values serialized back to the caller. A factor panel+#: or a full CSCV logit vector can be enormous, and silently returning 200k+#: numbers into a context window helps nobody.+_MAX_RESULT_LEAVES = 5000+++def _import_module(short_name: str) -> Any:+ """Import an allowlisted module by its short name.++ Args:+ short_name: Key of :data:`ALLOWED_MODULES`.++ Returns:+ The imported module.++ Raises:+ KeyError: If the name is not allowlisted.+ """+ import importlib++ return importlib.import_module(ALLOWED_MODULES[short_name])+++def _public_names(module: Any) -> list[str]:+ """Callable public names of a module, writers excluded.++ Args:+ module: An imported quantlib module.++ Returns:+ Sorted names from ``__all__`` that are callable and not file writers.+ """+ exported = getattr(module, "__all__", [])+ out = []+ for name in exported:+ if name.startswith(_WRITER_PREFIXES):+ continue+ obj = getattr(module, name, None)+ if callable(obj):+ out.append(name)+ return sorted(out)+++def _decode(value: Any) -> Any:+ """Turn JSON envelopes into the pandas objects some functions require.++ Args:+ value: A decoded-JSON value, possibly a ``__series__`` or+ ``__dataframe__`` envelope, possibly nested inside a container.++ Returns:+ The value with any envelope replaced by the pandas object it describes.++ Raises:+ ValueError: If an envelope is malformed.+ """+ import pandas as pd++ if isinstance(value, dict):+ if "__series__" in value:+ spec = value["__series__"]+ if not isinstance(spec, dict) or "values" not in spec:+ raise ValueError("__series__ needs a 'values' list")+ return pd.Series(spec["values"], index=spec.get("index"))+ if "__dataframe__" in value:+ spec = value["__dataframe__"]+ if not isinstance(spec, dict) or "data" not in spec:+ raise ValueError("__dataframe__ needs a 'data' list of rows")+ return pd.DataFrame(+ spec["data"], index=spec.get("index"), columns=spec.get("columns")+ )+ return {k: _decode(v) for k, v in value.items()}+ if isinstance(value, list):+ return [_decode(v) for v in value]+ return value+++class _Budget:+ """Mutable leaf counter shared across one serialization pass."""++ def __init__(self) -> None:+ self.leaves = 0+ self.truncated = False+++def _encode(value: Any, budget: _Budget) -> Any:+ """Serialize a quantlib result into JSON-safe data.++ Dataclasses become dicts, enums become their value, numpy and pandas objects+ become plain containers, and non-finite floats become explicit strings so a+ NaN cannot arrive at the caller as ``null`` and read as "absent".++ Args:+ value: Anything a quantlib function returns.+ budget: Shared leaf counter; once exhausted, containers are truncated+ and the fact is reported rather than hidden.++ Returns:+ A JSON-serializable structure.+ """+ import numpy as np+ import pandas as pd++ if budget.leaves >= _MAX_RESULT_LEAVES:+ budget.truncated = True+ return "<truncated>"++ if value is None or isinstance(value, (bool, int, str)):+ budget.leaves += 1+ return value+ if isinstance(value, float):+ budget.leaves += 1+ if math.isnan(value):+ return "NaN"+ if math.isinf(value):+ return "Infinity" if value > 0 else "-Infinity"+ return value+ if isinstance(value, Enum):+ budget.leaves += 1+ return value.value+ if isinstance(value, (np.integer, np.floating, np.bool_)):+ return _encode(value.item(), budget)+ if isinstance(value, np.ndarray):+ return [_encode(v, budget) for v in value.tolist()]+ if isinstance(value, pd.Series):+ return {+ "__series__": {+ "index": [_encode(i, budget) for i in value.index.tolist()],+ "values": [_encode(v, budget) for v in value.tolist()],+ }+ }+ if isinstance(value, pd.DataFrame):+ return {+ "__dataframe__": {+ "index": [_encode(i, budget) for i in value.index.tolist()],+ "columns": [str(c) for c in value.columns],+ "data": [[_encode(v, budget) for v in row] for row in value.to_numpy().tolist()],+ }+ }+ if dataclasses.is_dataclass(value) and not isinstance(value, type):+ return {+ f.name: _encode(getattr(value, f.name), budget)+ for f in dataclasses.fields(value)+ }+ if isinstance(value, dict):+ return {str(k): _encode(v, budget) for k, v in value.items()}+ if isinstance(value, (list, tuple, set, frozenset)):+ return [_encode(v, budget) for v in value]++ budget.leaves += 1+ return str(value)+++class QuantlibCallTool(BaseTool):+ """Call any public function of the tested finance-math layer."""++ name = "quantlib_call"+ description = (+ "Run a function from the tested finance-math library (src/quantlib): "+ "Black-Scholes and implied vol, bond math and curve fitting, Altman Z "+ "and Merton/KMV, stationarity/cointegration/GARCH/regime switching, "+ "VaR/CVaR/EVT and VaR backtesting (Kupiec/Christoffersen/Basel), "+ "Brinson-Fachler attribution, market impact, fund maths "+ "(XIRR/MOIC/DPI/TVPI/PME/waterfalls), TWR/Dietz/MWR, event studies "+ "(CAR/CAAR/Patell/BMP), style factor models, deflated Sharpe and PBO, "+ "purged cross-validation, and the valuation engine (DCF / comps / "+ "three-statement). Read-only and pure-compute: it fetches no data and "+ "writes no files. Start with action='list' to see modules, then "+ "action='list' with a module to see its functions, then "+ "action='describe' for a signature. "+ 'Example: quantlib_call(action="call", module="risk", '+ 'function="historical_var", kwargs={"returns": [0.01, -0.02], "confidence": 0.95}).'+ )+ is_readonly = True+ repeatable = True+ parameters = {+ "type": "object",+ "properties": {+ "action": {+ "type": "string",+ "enum": ["list", "describe", "call"],+ "description": (+ "'list' enumerates modules (or a module's functions when "+ "'module' is given); 'describe' returns one function's "+ "signature and docstring; 'call' runs it."+ ),+ "default": "list",+ },+ "module": {+ "type": "string",+ "description": (+ "Short module name, e.g. 'risk', 'options', 'valuation.dcf'. "+ "Required for 'describe' and 'call'."+ ),+ },+ "function": {+ "type": "string",+ "description": "Public function name. Required for 'describe' and 'call'.",+ },+ "kwargs": {+ "type": "object",+ "description": (+ "Keyword arguments. Pass an indexed pandas Series as "+ '{"__series__": {"index": [...], "values": [...]}} and a '+ 'DataFrame as {"__dataframe__": {"index": [...], '+ '"columns": [...], "data": [[...]]}}; a plain list stays a list.'+ ),+ "default": {},+ },+ },+ "required": ["action"],+ }++ def execute(self, **kwargs: Any) -> str:+ """Dispatch a list / describe / call request.++ Args:+ **kwargs: See :attr:`parameters`.++ Returns:+ A JSON envelope. Every failure path returns ``ok=false`` with an+ actionable ``error`` rather than raising, matching the other+ read-only tools.+ """+ action = str(kwargs.get("action") or "list").strip().lower()+ module_name = kwargs.get("module")+ function_name = kwargs.get("function")++ try:+ if action == "list":+ return self._list(module_name)+ if action not in ("describe", "call"):+ return self._error(f"unknown action {action!r}; use list, describe or call")+ if not module_name or not function_name:+ return self._error(f"action='{action}' needs both 'module' and 'function'")++ resolved = self._resolve(str(module_name), str(function_name))+ if isinstance(resolved, str):+ return resolved+ func = resolved++ if action == "describe":+ return self._describe(str(module_name), str(function_name), func)+ return self._call(str(module_name), str(function_name), func, kwargs.get("kwargs") or {})+ except Exception as exc: # noqa: BLE001 - envelope, never raise to the loop+ return self._error(f"{type(exc).__name__}: {exc}")++ def _resolve(self, module_name: str, function_name: str) -> Any:+ """Look up a callable, or return an error envelope string.++ Args:+ module_name: Short module name.+ function_name: Public function name.++ Returns:+ The callable, or a JSON error envelope string.+ """+ if module_name not in ALLOWED_MODULES:+ return self._error(+ f"unknown module {module_name!r}; available: {sorted(ALLOWED_MODULES)}"+ )+ module = _import_module(module_name)+ allowed = _public_names(module)+ if function_name not in allowed:+ if function_name.startswith(_WRITER_PREFIXES):+ return self._error(+ f"{function_name!r} writes to a path and is not callable here; "+ "this tool is pure-compute"+ )+ return self._error(+ f"{function_name!r} is not a public function of {module_name!r}; "+ f"available: {allowed}"+ )+ return getattr(module, function_name)++ def _list(self, module_name: Any) -> str:+ """List modules, or one module's public functions."""+ if not module_name:+ return json.dumps(+ {+ "ok": True,+ "modules": sorted(ALLOWED_MODULES),+ "hint": "call again with module=<name> to list its functions",+ },+ ensure_ascii=False,+ )+ name = str(module_name)+ if name not in ALLOWED_MODULES:+ return self._error(f"unknown module {name!r}; available: {sorted(ALLOWED_MODULES)}")+ module = _import_module(name)+ functions = []+ for fn_name in _public_names(module):+ fn = getattr(module, fn_name)+ doc = (inspect.getdoc(fn) or "").strip().splitlines()+ functions.append({"name": fn_name, "summary": doc[0] if doc else ""})+ return json.dumps(+ {"ok": True, "module": name, "functions": functions}, ensure_ascii=False+ )++ def _describe(self, module_name: str, function_name: str, func: Any) -> str:+ """Return one function's signature and docstring."""+ try:+ signature = str(inspect.signature(func))+ except (TypeError, ValueError):+ signature = "(signature unavailable)"+ return json.dumps(+ {+ "ok": True,+ "module": module_name,+ "function": function_name,+ "signature": signature,+ "doc": inspect.getdoc(func) or "",+ },+ ensure_ascii=False,+ )++ def _call(self, module_name: str, function_name: str, func: Any, raw_kwargs: Any) -> str:+ """Run the function and serialize its result."""+ if not isinstance(raw_kwargs, dict):+ return self._error("'kwargs' must be an object")+ try:+ decoded = {str(k): _decode(v) for k, v in raw_kwargs.items()}+ except ValueError as exc:+ return self._error(f"bad argument envelope: {exc}")++ try:+ result = func(**decoded)+ except TypeError as exc:+ # Almost always a wrong/missing argument; hand back the signature so+ # the next attempt is informed rather than another guess.+ try:+ signature = str(inspect.signature(func))+ except (TypeError, ValueError):+ signature = "(signature unavailable)"+ return self._error(f"{exc}", signature=signature)+ except Exception as exc: # noqa: BLE001+ # A domain refusal (bad confidence level, missing input, no sign+ # change) is information, not a crash: surface it verbatim.+ return self._error(f"{type(exc).__name__}: {exc}")++ budget = _Budget()+ payload = {+ "ok": True,+ "module": module_name,+ "function": function_name,+ "result": _encode(result, budget),+ }+ if budget.truncated:+ payload["truncated"] = True+ payload["truncation_note"] = (+ f"result exceeded {_MAX_RESULT_LEAVES} values and was truncated; "+ "narrow the inputs or request a summary statistic instead"+ )+ return json.dumps(payload, ensure_ascii=False)++ @staticmethod+ def _error(message: str, **extra: Any) -> str:+ """Build a uniform failure envelope."""+ return json.dumps({"ok": False, "error": message, **extra}, ensure_ascii=False)diff --git a/agent/tests/quantlib/test_crossvalidation.py b/agent/tests/quantlib/test_crossvalidation.pynew file mode 100644index 000000000..da1f0f461--- /dev/null+++ b/agent/tests/quantlib/test_crossvalidation.py@@ -0,0 +1,282 @@+"""Tests for src.quantlib.crossvalidation.++The central test is the one that shows a NAIVE split leaks and the purged split+does not, over identical data. Asserting only that the purged splitter is clean+would pass just as well if purging were a no-op.+"""++import math++import numpy as np+import pandas as pd+import pytest++from src.quantlib.crossvalidation import (+ DEFAULT_EMBARGO_FRACTION,+ MIN_FOLDS,+ Split,+ combinatorial_purged_splits,+ detect_boundary_leakage,+ purged_kfold_splits,+ purged_walk_forward_splits,+)+++def _overlapping_labels(n=1000, horizon=20):+ """Label i resolves `horizon` bars later, so labels overlap heavily."""+ return np.minimum(np.arange(n) + horizon, n - 1)+++# --- the leak exists, and purging is what removes it ---+++def test_a_naive_split_leaks_and_the_purged_split_does_not():+ n, horizon = 1000, 20+ labels = _overlapping_labels(n, horizon)+ test = np.arange(400, 600)++ naive = Split(+ train=np.setdiff1d(np.arange(n), test),+ test=test,+ purged=0,+ embargoed=0,+ test_bounds=(400, 599),+ )+ naive_report = detect_boundary_leakage(naive, labels, n_samples=n)+ assert not naive_report.clean+ # Exactly the observations whose 20-bar label window reaches into the test+ # block: starts 380..399 before it, plus everything the test's own labels+ # cover after it.+ assert naive_report.overlapping.size > 0++ purged = next(+ s for s in purged_kfold_splits(n, labels, n_folds=5, embargo_fraction=0.0)+ if s.test_bounds == (400, 599)+ )+ assert detect_boundary_leakage(purged, labels, n_samples=n).clean+ assert purged.purged > 0+++def test_purging_removes_exactly_the_overlapping_observations():+ n, horizon = 200, 10+ labels = _overlapping_labels(n, horizon)+ splits = list(purged_kfold_splits(n, labels, n_folds=4, embargo_fraction=0.0))+ fold = splits[1] # test block 50..99+ assert fold.test_bounds == (50, 99)++ first_test = 50+ test_span_end = max(99, int(labels[np.arange(50, 100)].max()))+ expected_removed = {+ i+ for i in range(n)+ if i not in range(50, 100) and i <= test_span_end and labels[i] >= first_test+ }+ assert set(np.setdiff1d(np.arange(n), np.union1d(fold.train, fold.test))) == expected_removed+ assert fold.purged == len(expected_removed)+++def test_no_observation_is_in_both_train_and_test():+ n = 500+ labels = _overlapping_labels(n, 15)+ for split in purged_kfold_splits(n, labels, n_folds=5):+ assert np.intersect1d(split.train, split.test).size == 0+++def test_labels_touching_at_a_single_instant_count_as_overlapping():+ # Closed intervals on both ends. Observation 39's label ends exactly at 40,+ # the first test bar, so it must be purged.+ n = 100+ labels = np.arange(n) + 1+ labels[39] = 40+ split = next(+ s for s in purged_kfold_splits(n, labels, n_folds=5, embargo_fraction=0.0)+ if s.test_bounds[0] == 40+ )+ assert 39 not in split.train+++# --- embargo ---+++def test_embargo_removes_observations_after_the_test_block():+ n = 1000+ labels = np.arange(n) # labels resolve same-bar, so purging alone does nothing+ embargo_fraction = 0.02+ embargo_size = int(round(n * embargo_fraction))++ split = next(+ s for s in purged_kfold_splits(n, labels, n_folds=5, embargo_fraction=embargo_fraction)+ if s.test_bounds == (200, 399)+ )+ assert split.embargoed == embargo_size+ # Nothing in (399, 399 + embargo] survives in training.+ assert not ((split.train > 399) & (split.train <= 399 + embargo_size)).any()+ # But training resumes immediately after the embargo.+ assert (split.train > 399 + embargo_size).any()+++def test_zero_embargo_keeps_the_bar_right_after_the_test_block():+ n = 500+ labels = np.arange(n)+ split = next(+ s for s in purged_kfold_splits(n, labels, n_folds=5, embargo_fraction=0.0)+ if s.test_bounds == (100, 199)+ )+ assert split.embargoed == 0+ assert 200 in split.train+++def test_detect_boundary_leakage_flags_a_missing_embargo():+ n = 300+ labels = np.arange(n)+ test = np.arange(100, 200)+ unembargoed = Split(+ train=np.setdiff1d(np.arange(n), test),+ test=test,+ purged=0,+ embargoed=0,+ test_bounds=(100, 199),+ )+ report = detect_boundary_leakage(unembargoed, labels, n_samples=n, embargo_size=10)+ assert report.embargo_violations.size == 10+ assert not report.clean+++def test_default_embargo_fraction_is_small_but_nonzero():+ assert 0.0 < DEFAULT_EMBARGO_FRACTION < 0.1+++# --- walk-forward ---+++def test_walk_forward_never_trains_on_the_future():+ n = 1000+ labels = _overlapping_labels(n, 20)+ for split in purged_walk_forward_splits(n, labels, n_folds=5):+ assert split.train.max() < split.test.min()+++def test_walk_forward_purges_past_labels_that_reach_into_the_test_block():+ n, horizon = 500, 25+ labels = _overlapping_labels(n, horizon)+ split = next(purged_walk_forward_splits(n, labels, n_folds=5))+ start = split.test.min()+ # Every retained training observation's label resolves strictly before the+ # test block opens.+ assert (labels[split.train] < start).all()+ assert split.purged > 0+++def test_walk_forward_expanding_grows_and_rolling_does_not():+ n = 1000+ labels = np.arange(n)+ expanding = [s.train.size for s in purged_walk_forward_splits(n, labels, n_folds=5)]+ rolling = [+ s.train.size for s in purged_walk_forward_splits(n, labels, n_folds=5, expanding=False)+ ]+ assert expanding == sorted(expanding)+ assert expanding[-1] > expanding[0]+ assert max(rolling) - min(rolling) <= 1+++def test_walk_forward_splits_are_leak_free():+ n = 800+ labels = _overlapping_labels(n, 30)+ for split in purged_walk_forward_splits(n, labels, n_folds=6):+ assert detect_boundary_leakage(split, labels, n_samples=n).clean+++# --- combinatorial ---+++def test_combinatorial_yields_every_combination():+ n = 600+ labels = np.arange(n)+ splits = list(combinatorial_purged_splits(n, labels, n_groups=6, n_test_groups=2))+ assert len(splits) == math.comb(6, 2)+++def test_combinatorial_test_blocks_are_disjoint_from_training():+ n = 600+ labels = _overlapping_labels(n, 12)+ for split in combinatorial_purged_splits(n, labels, n_groups=6, n_test_groups=2):+ assert np.intersect1d(split.train, split.test).size == 0+ assert detect_boundary_leakage(split, labels, n_samples=n).clean+++def test_combinatorial_holds_out_more_than_one_block_at_a_time():+ n = 600+ splits = list(combinatorial_purged_splits(n, np.arange(n), n_groups=6, n_test_groups=3))+ for split in splits:+ assert split.test.size >= 3 * (n // 6) - 3+++# --- label end times as a pandas Series of timestamps ---+++def test_label_end_times_accepts_a_timestamp_series():+ index = pd.date_range("2024-01-01", periods=200, freq="B")+ # Each label resolves 5 business days later.+ ends = pd.Series(index.to_series().shift(-5).bfill().values, index=index)+ splits = list(purged_kfold_splits(len(index), ends, n_folds=4, embargo_fraction=0.0))+ assert len(splits) == 4+ for split in splits:+ assert np.intersect1d(split.train, split.test).size == 0+ assert split.purged >= 0+++def test_a_label_ending_before_it_starts_is_rejected():+ bad = np.arange(100) - 5+ with pytest.raises(ValueError, match="cannot end before"):+ purged_kfold_splits(100, bad, n_folds=4).__next__()+++# --- fold accounting and validation ---+++def test_every_observation_is_tested_exactly_once_across_kfold():+ n = 1000+ tested = np.concatenate([s.test for s in purged_kfold_splits(n, np.arange(n), n_folds=5)])+ assert np.array_equal(np.sort(tested), np.arange(n))+++def test_folds_come_back_in_chronological_order():+ n = 500+ bounds = [s.test_bounds for s in purged_kfold_splits(n, np.arange(n), n_folds=5)]+ assert bounds == sorted(bounds)++[email protected]("n_folds", [0, 1, MIN_FOLDS - 1])+def test_too_few_folds_rejected(n_folds):+ with pytest.raises(ValueError, match="at least"):+ list(purged_kfold_splits(100, np.arange(100), n_folds=n_folds))+++def test_more_folds_than_samples_rejected():+ with pytest.raises(ValueError, match="cannot make"):+ list(purged_kfold_splits(3, np.arange(3), n_folds=5))++[email protected]("fraction", [-0.01, 1.0, 2.0])+def test_bad_embargo_fraction_rejected(fraction):+ with pytest.raises(ValueError, match="embargo_fraction"):+ list(purged_kfold_splits(100, np.arange(100), n_folds=4, embargo_fraction=fraction))+++def test_mismatched_label_length_rejected():+ with pytest.raises(ValueError, match="entries but the sample has"):+ list(purged_kfold_splits(100, np.arange(50), n_folds=4))++[email protected]("n_test_groups", [0, 6, 7])+def test_bad_combinatorial_group_count_rejected(n_test_groups):+ with pytest.raises(ValueError, match="n_test_groups"):+ list(combinatorial_purged_splits(600, np.arange(600), n_groups=6, n_test_groups=n_test_groups))+++def test_purge_counts_are_reported_not_hidden():+ n = 1000+ labels = _overlapping_labels(n, 25)+ for split in purged_kfold_splits(n, labels, n_folds=5):+ removed = n - split.train.size - split.test.size+ assert split.purged + split.embargoed == removeddiff --git a/agent/tests/quantlib/test_eventstudy.py b/agent/tests/quantlib/test_eventstudy.pynew file mode 100644index 000000000..e98c4125e--- /dev/null+++ b/agent/tests/quantlib/test_eventstudy.py@@ -0,0 +1,313 @@+"""Tests for src.quantlib.eventstudy.++Two-sided throughout: a sample with no event effect must NOT be called+significant, and a sample with an injected effect must be.+"""++import numpy as np+import pandas as pd+import pytest++from src.quantlib.eventstudy import (+ DEFAULT_ESTIMATION_GAP,+ MIN_ESTIMATION_OBSERVATIONS,+ estimate_market_model,+ event_study,+)+++def _panel(n_days=400, n_symbols=30, seed=0, beta=1.2, alpha=0.0002, vol=0.012):+ """Build a return frame generated by a known market model."""+ rng = np.random.default_rng(seed)+ index = pd.date_range("2020-01-01", periods=n_days, freq="B")+ market = pd.Series(rng.normal(0.0003, 0.009, n_days), index=index, name="market")+ symbols = [f"S{i:02d}" for i in range(n_symbols)]+ data = {+ s: alpha + beta * market.to_numpy() + rng.normal(0.0, vol, n_days)+ for s in symbols+ }+ return pd.DataFrame(data, index=index), market+++# --- market model fitting ---+++def test_market_model_recovers_known_alpha_and_beta():+ rng = np.random.default_rng(5)+ market = rng.normal(0.0, 0.01, 500)+ asset = 0.0005 + 1.4 * market + rng.normal(0.0, 0.002, 500)+ fit = estimate_market_model(asset, market)+ assert fit.beta == pytest.approx(1.4, abs=0.03)+ assert fit.alpha == pytest.approx(0.0005, abs=0.0003)+ assert fit.residual_std == pytest.approx(0.002, rel=0.15)+ assert fit.observations == 500+++def test_market_adjusted_model_fixes_beta_at_one():+ rng = np.random.default_rng(6)+ market = rng.normal(0.0, 0.01, 200)+ asset = market + rng.normal(0.0, 0.001, 200)+ fit = estimate_market_model(asset, market, model="market_adjusted")+ assert fit.alpha == 0.0+ assert fit.beta == 1.0+++def test_mean_adjusted_model_ignores_the_market():+ rng = np.random.default_rng(7)+ market = rng.normal(0.0, 0.01, 200)+ asset = 0.001 + rng.normal(0.0, 0.003, 200)+ fit = estimate_market_model(asset, market, model="mean_adjusted")+ assert fit.beta == 0.0+ assert fit.alpha == pytest.approx(asset.mean())+++def test_short_estimation_window_is_an_error():+ with pytest.raises(ValueError, match="at least"):+ estimate_market_model(np.zeros(10), np.zeros(10))+++def test_constant_market_leaves_beta_unidentified():+ rng = np.random.default_rng(8)+ with pytest.raises(ValueError, match="not identified"):+ estimate_market_model(rng.normal(0, 0.01, 100), np.zeros(100))+++def test_unknown_model_rejected():+ with pytest.raises(ValueError, match="model must be one of"):+ estimate_market_model(np.zeros(100), np.zeros(100), model="cape")+++# --- the null: no effect must not be called significant ---+++def test_no_effect_sample_is_not_significant():+ returns, market = _panel(seed=101)+ events = [(s, returns.index[250]) for s in returns.columns]+ result = event_study(returns, market, events, event_window=(-2, 2))++ assert abs(result.caar_total) < 0.01+ assert result.bmp_p_value > 0.05+ assert result.t_p_value > 0.05+++# --- an injected effect must be found, at the right size ---+++def test_injected_event_day_jump_is_recovered_in_caar():+ returns, market = _panel(seed=202)+ event_row = 250+ jump = 0.05+ returns = returns.copy()+ returns.iloc[event_row] += jump++ events = [(s, returns.index[event_row]) for s in returns.columns]+ result = event_study(returns, market, events, event_window=(-2, 2))++ assert result.caar_total == pytest.approx(jump, abs=0.01)+ assert result.aar.loc[0] == pytest.approx(jump, abs=0.01)+ # Days either side of the event carry no injected effect.+ assert abs(result.aar.loc[-1]) < 0.01+ assert abs(result.aar.loc[1]) < 0.01+ assert result.bmp_p_value < 0.01+ assert result.patell_p_value < 0.01+ assert result.t_p_value < 0.01+++def test_car_is_exactly_the_sum_of_the_abnormal_returns():+ returns, market = _panel(seed=303)+ events = [(s, returns.index[250]) for s in returns.columns[:5]]+ result = event_study(returns, market, events, event_window=(-3, 3))+ for outcome in result.events:+ assert outcome.car == pytest.approx(float(outcome.abnormal_returns.sum()))+++def test_caar_is_the_running_sum_of_aar():+ returns, market = _panel(seed=304)+ events = [(s, returns.index[250]) for s in returns.columns]+ result = event_study(returns, market, events, event_window=(-4, 4))+ assert result.caar.to_numpy() == pytest.approx(np.cumsum(result.aar.to_numpy()))+ assert result.caar_total == pytest.approx(result.caar.iloc[-1])+++# --- the estimation window must not see the event ---+++def test_estimation_window_excludes_the_event_window():+ returns, market = _panel(seed=404)+ event_row = 250+ contaminated = returns.copy()+ # A violent, sustained move confined to the event window. If the estimation+ # window overlapped it, beta would be dragged and the abnormal return would+ # shrink toward zero -- the study would under-report its own finding.+ contaminated.iloc[event_row - 5 : event_row + 6] += 0.25++ events = [(s, returns.index[event_row]) for s in returns.columns]+ clean = event_study(returns, market, events, event_window=(-5, 5))+ dirty = event_study(contaminated, market, events, event_window=(-5, 5))++ # The fitted betas are unchanged: the estimation window never saw the shock.+ for a, b in zip(clean.events, dirty.events):+ assert a.fit.beta == pytest.approx(b.fit.beta, rel=1e-12)+ # And the whole injected move shows up as abnormal return: 11 days x 0.25.+ assert dirty.caar_total == pytest.approx(clean.caar_total + 11 * 0.25, abs=0.02)+++def test_estimation_gap_is_respected():+ returns, market = _panel(seed=405)+ event_row = 250+ contaminated = returns.copy()+ # Poison only the gap rows, which sit between the estimation and event+ # windows and must be used by neither.+ gap_start = event_row - 5 - DEFAULT_ESTIMATION_GAP+ contaminated.iloc[gap_start : event_row - 5] += 0.30++ events = [(s, returns.index[event_row]) for s in returns.columns]+ clean = event_study(returns, market, events, event_window=(-5, 5))+ dirty = event_study(contaminated, market, events, event_window=(-5, 5))++ for a, b in zip(clean.events, dirty.events):+ assert a.fit.beta == pytest.approx(b.fit.beta, rel=1e-12)+ assert a.car == pytest.approx(b.car, rel=1e-12)+++# --- BMP vs Patell under event-induced variance ---+++def test_bmp_survives_event_induced_variance_where_patell_over_rejects():+ # The null is true: no mean effect. But the event window is three times as+ # volatile as the estimation window, which is what real events do. Patell+ # assumes event-window variance equals estimation-window variance and+ # therefore rejects far too often; BMP takes the cross-sectional variance of+ # the standardised values and holds its size.+ rng = np.random.default_rng(909)+ patell_rejections = 0+ bmp_rejections = 0+ trials = 60++ for trial in range(trials):+ n_days, n_symbols = 320, 40+ index = pd.date_range("2020-01-01", periods=n_days, freq="B")+ market = pd.Series(rng.normal(0.0, 0.008, n_days), index=index)+ event_row = 250+ data = {}+ for i in range(n_symbols):+ noise = rng.normal(0.0, 0.01, n_days)+ noise[event_row - 2 : event_row + 3] *= 3.0 # variance, not mean+ data[f"S{i:02d}"] = 1.0 * market.to_numpy() + noise+ frame = pd.DataFrame(data, index=index)+ events = [(s, index[event_row]) for s in frame.columns]+ result = event_study(frame, market, events, event_window=(-2, 2))+ patell_rejections += result.patell_p_value < 0.05+ bmp_rejections += result.bmp_p_value < 0.05++ patell_rate = patell_rejections / trials+ bmp_rate = bmp_rejections / trials+ assert bmp_rate <= 0.15, f"BMP should hold its size, got {bmp_rate:.2%}"+ assert patell_rate > bmp_rate, (+ f"Patell should over-reject under event-induced variance "+ f"(patell {patell_rate:.2%} vs bmp {bmp_rate:.2%})"+ )+++# --- dropped events are reported, never silently skipped ---+++def test_unknown_symbol_is_dropped_with_a_reason():+ returns, market = _panel(seed=505)+ events = [("S00", returns.index[250]), ("NOPE", returns.index[250])]+ result = event_study(returns, market, events)+ assert len(result.events) == 1+ assert result.dropped == (("NOPE", returns.index[250], "symbol not in returns frame"),)+++def test_event_too_early_for_an_estimation_window_is_dropped():+ returns, market = _panel(seed=506)+ events = [("S00", returns.index[5])]+ with pytest.raises(ValueError, match="no event could be measured"):+ event_study(returns, market, events)+++def test_event_window_running_past_the_frame_is_dropped():+ returns, market = _panel(seed=507)+ events = [("S00", returns.index[250]), ("S01", returns.index[-2])]+ result = event_study(returns, market, events, event_window=(-1, 5))+ reasons = [r for _, _, r in result.dropped]+ assert reasons == ["event window runs past the frame end"]+++def test_non_finite_event_window_is_dropped():+ returns, market = _panel(seed=508)+ returns = returns.copy()+ returns.iloc[250, returns.columns.get_loc("S00")] = np.nan+ events = [("S00", returns.index[250]), ("S01", returns.index[250])]+ result = event_study(returns, market, events, event_window=(-1, 1))+ assert [s for s, _, _ in result.dropped] == ["S00"]+ assert [o.symbol for o in result.events] == ["S01"]+++# --- clustering disclosure ---+++def test_shared_event_dates_are_flagged():+ returns, market = _panel(seed=606)+ same_day = returns.index[250]+ events = [(s, same_day) for s in returns.columns[:4]]+ result = event_study(returns, market, events)+ assert result.shared_event_dates == (same_day,)+++def test_distinct_event_dates_are_not_flagged():+ returns, market = _panel(seed=607)+ events = [+ ("S00", returns.index[240]),+ ("S01", returns.index[250]),+ ("S02", returns.index[260]),+ ]+ result = event_study(returns, market, events)+ assert result.shared_event_dates == ()+++# --- input validation ---+++def test_inverted_event_window_rejected():+ returns, market = _panel(seed=707)+ with pytest.raises(ValueError, match="start must be <= end"):+ event_study(returns, market, [("S00", returns.index[250])], event_window=(3, -3))+++def test_negative_estimation_gap_rejected():+ returns, market = _panel(seed=708)+ with pytest.raises(ValueError, match="estimation_gap must be >= 0"):+ event_study(returns, market, [("S00", returns.index[250])], estimation_gap=-1)+++def test_too_short_estimation_window_rejected():+ returns, market = _panel(seed=709)+ with pytest.raises(ValueError, match="estimation_window must be at least"):+ event_study(+ returns,+ market,+ [("S00", returns.index[250])],+ estimation_window=MIN_ESTIMATION_OBSERVATIONS - 1,+ )+++def test_empty_events_rejected():+ returns, market = _panel(seed=710)+ with pytest.raises(ValueError, match="events is empty"):+ event_study(returns, market, [])+++def test_market_missing_labels_is_an_error():+ returns, market = _panel(seed=711)+ with pytest.raises(ValueError, match="missing"):+ event_study(returns, market.iloc[10:], [("S00", returns.index[250])])+++def test_post_event_only_window_is_allowed():+ returns, market = _panel(seed=712)+ events = [(s, returns.index[250]) for s in returns.columns]+ result = event_study(returns, market, events, event_window=(1, 5))+ assert result.event_window == (1, 5)+ assert list(result.aar.index) == [1, 2, 3, 4, 5]diff --git a/agent/tests/quantlib/test_factormodel.py b/agent/tests/quantlib/test_factormodel.pynew file mode 100644index 000000000..aaf1450fa--- /dev/null+++ b/agent/tests/quantlib/test_factormodel.py@@ -0,0 +1,427 @@+"""Tests for src.quantlib.factormodel.++The recoverability tests build a cross-section from known factor returns and+check the regression gets them back. The standardisation tests pin the two+conventions that make an exposure mean what it claims: cap-weighted centring and+equal-weighted scaling.+"""++import numpy as np+import pandas as pd+import pytest++from src.quantlib.factormodel import (+ MARKET_FACTOR,+ MIN_CROSS_SECTION,+ STYLE_FACTOR_DEFINITIONS,+ build_style_exposures,+ cross_sectional_factor_returns,+ factor_return_attribution,+ portfolio_style_exposure,+ standardise_exposures,+ style_drift,+)+++def _assets(n=200):+ return [f"A{i:03d}" for i in range(n)]+++# --- standardisation ---+++def test_standardised_exposure_has_unit_equal_weighted_dispersion():+ rng = np.random.default_rng(1)+ values = pd.Series(rng.normal(5.0, 2.0, 500), index=_assets(500))+ exposures = standardise_exposures(values, winsorise=0.0)++ assert exposures.mean() == pytest.approx(0.0, abs=1e-12)+ assert exposures.std(ddof=1) == pytest.approx(1.0, rel=1e-12)+++def test_cap_weighted_centring_puts_the_market_portfolio_at_zero():+ # This is the property that makes a portfolio exposure readable as a tilt+ # away from the market rather than an absolute level.+ rng = np.random.default_rng(2)+ index = _assets(300)+ values = pd.Series(rng.normal(0.0, 1.0, 300), index=index)+ caps = pd.Series(rng.lognormal(10, 1.5, 300), index=index)++ exposures = standardise_exposures(values, market_caps=caps, winsorise=0.0)+ market_weights = caps / caps.sum()++ assert float((exposures * market_weights).sum()) == pytest.approx(0.0, abs=1e-12)+++def test_equal_weighted_scaling_is_not_cap_weighted():+ # The asymmetry is deliberate: a few megacaps must not set the scale.+ rng = np.random.default_rng(3)+ index = _assets(300)+ values = pd.Series(rng.normal(0.0, 1.0, 300), index=index)+ caps = pd.Series(np.r_[np.full(5, 1e12), np.full(295, 1e8)], index=index)++ exposures = standardise_exposures(values, market_caps=caps, winsorise=0.0)+ assert exposures.std(ddof=1) == pytest.approx(1.0, rel=1e-12)+++def test_winsorising_stops_one_outlier_compressing_the_cross_section():+ index = _assets(200)+ clean = pd.Series(np.linspace(-1, 1, 200), index=index)+ poisoned = clean.copy()+ poisoned.iloc[0] = 500.0++ without = standardise_exposures(poisoned, winsorise=0.0)+ with_winsor = standardise_exposures(poisoned, winsorise=0.025)++ # Without winsorising the outlier eats the scale and everything else+ # collapses toward zero.+ assert without.drop(index[0]).abs().max() < 0.1+ assert with_winsor.drop(index[0]).abs().max() > 1.0+++def test_standardise_rejects_a_constant_characteristic():+ with pytest.raises(ValueError, match="no cross-sectional variation"):+ standardise_exposures(pd.Series(np.full(50, 3.0), index=_assets(50)))+++def test_standardise_rejects_a_cross_section_too_small_to_scale():+ small = pd.Series(np.arange(float(MIN_CROSS_SECTION - 1)), index=_assets(MIN_CROSS_SECTION - 1))+ with pytest.raises(ValueError, match="at least"):+ standardise_exposures(small)+++def test_standardise_rejects_bad_winsorise_fraction():+ values = pd.Series(np.arange(50.0), index=_assets(50))+ for bad in (-0.01, 0.5, 0.9):+ with pytest.raises(ValueError, match="winsorise must be"):+ standardise_exposures(values, winsorise=bad)+++def test_standardise_rejects_market_caps_that_do_not_cover_the_universe():+ index = _assets(50)+ values = pd.Series(np.arange(50.0), index=index)+ caps = pd.Series(np.arange(1.0, 41.0), index=index[:40])+ with pytest.raises(ValueError, match="missing"):+ standardise_exposures(values, market_caps=caps)+++# --- exposure assembly ---+++def test_build_style_exposures_uses_the_documented_signs():+ rng = np.random.default_rng(4)+ index = _assets(200)+ characteristics = pd.DataFrame(+ {+ "log_market_cap": rng.normal(0, 1, 200),+ "book_to_price": rng.normal(0, 1, 200),+ },+ index=index,+ )+ exposures, _ = build_style_exposures(characteristics)++ # size is defined as -1 * log_market_cap: small caps get the large exposure.+ assert exposures["size"].corr(characteristics["log_market_cap"]) < -0.9+ # value is +1 * book_to_price: cheap names get the large exposure.+ assert exposures["value"].corr(characteristics["book_to_price"]) > 0.9+++def test_multi_input_factor_averages_its_standardised_parts():+ rng = np.random.default_rng(5)+ index = _assets(200)+ # earnings_to_price has a hugely wider raw spread than book_to_price. If the+ # factor averaged the RAW inputs it would be an earnings-yield factor with a+ # book-to-price rounding error attached.+ characteristics = pd.DataFrame(+ {+ "book_to_price": rng.normal(0, 0.01, 200),+ "earnings_to_price": rng.normal(0, 100.0, 200),+ },+ index=index,+ )+ exposures, _ = build_style_exposures(characteristics)++ b = standardise_exposures(characteristics["book_to_price"])+ e = standardise_exposures(characteristics["earnings_to_price"])+ assert exposures["value"].corr(b) == pytest.approx(exposures["value"].corr(e), abs=0.15)+++def test_missing_characteristic_cells_become_zero_and_are_counted():+ rng = np.random.default_rng(6)+ index = _assets(100)+ values = pd.Series(rng.normal(0, 1, 100), index=index)+ values.iloc[:20] = np.nan+ exposures, filled = build_style_exposures(pd.DataFrame({"book_to_price": values}))++ assert filled["value"] == 20+ assert (exposures["value"].iloc[:20] == 0.0).all()+++def test_factors_with_no_supplied_characteristic_are_skipped_not_faked():+ rng = np.random.default_rng(7)+ frame = pd.DataFrame({"book_to_price": rng.normal(0, 1, 100)}, index=_assets(100))+ exposures, _ = build_style_exposures(frame)++ assert list(exposures.columns) == ["value"]+ assert "momentum" not in exposures.columns+++def test_build_rejects_a_frame_with_no_usable_characteristic():+ frame = pd.DataFrame({"unrelated_column": np.arange(100.0)}, index=_assets(100))+ with pytest.raises(ValueError, match="no factor could be built"):+ build_style_exposures(frame)+++def test_build_rejects_an_empty_frame():+ with pytest.raises(ValueError, match="empty"):+ build_style_exposures(pd.DataFrame())+++def test_every_documented_factor_declares_at_least_one_characteristic():+ for factor, recipe in STYLE_FACTOR_DEFINITIONS.items():+ assert recipe, f"{factor} has no characteristics"+ assert all(sign in (1, -1) for sign in recipe.values()), factor+++# --- cross-sectional factor returns ---+++def test_factor_returns_recover_the_generating_coefficients():+ rng = np.random.default_rng(8)+ index = _assets(400)+ exposures = pd.DataFrame(+ {+ "value": rng.normal(0, 1, 400),+ "momentum": rng.normal(0, 1, 400),+ "size": rng.normal(0, 1, 400),+ },+ index=index,+ )+ true_market, true_value, true_momentum, true_size = 0.004, 0.002, -0.003, 0.0015+ returns = pd.Series(+ true_market+ + true_value * exposures["value"]+ + true_momentum * exposures["momentum"]+ + true_size * exposures["size"]+ + rng.normal(0, 0.002, 400),+ index=index,+ )++ fit = cross_sectional_factor_returns(returns, exposures)++ assert fit.factor_returns[MARKET_FACTOR] == pytest.approx(true_market, abs=0.0004)+ assert fit.factor_returns["value"] == pytest.approx(true_value, abs=0.0004)+ assert fit.factor_returns["momentum"] == pytest.approx(true_momentum, abs=0.0004)+ assert fit.factor_returns["size"] == pytest.approx(true_size, abs=0.0004)+ assert fit.r_squared > 0.7+ assert fit.observations == 400+++def test_market_factor_is_always_present_as_the_intercept():+ rng = np.random.default_rng(9)+ index = _assets(100)+ exposures = pd.DataFrame({"value": rng.normal(0, 1, 100)}, index=index)+ # Everything returns +2% regardless of exposure: that is a market move and+ # it must land on the market factor, not on value.+ returns = pd.Series(np.full(100, 0.02), index=index)++ fit = cross_sectional_factor_returns(returns, exposures)++ assert fit.factor_returns[MARKET_FACTOR] == pytest.approx(0.02, abs=1e-9)+ assert fit.factor_returns["value"] == pytest.approx(0.0, abs=1e-9)+++def test_residuals_are_the_specific_returns_and_sum_with_the_fit():+ rng = np.random.default_rng(10)+ index = _assets(150)+ exposures = pd.DataFrame({"value": rng.normal(0, 1, 150)}, index=index)+ returns = pd.Series(0.001 + 0.002 * exposures["value"] + rng.normal(0, 0.001, 150), index=index)++ fit = cross_sectional_factor_returns(returns, exposures)+ reconstructed = (+ fit.factor_returns[MARKET_FACTOR]+ + fit.factor_returns["value"] * exposures["value"]+ + fit.residuals+ )+ assert reconstructed.to_numpy() == pytest.approx(returns.to_numpy(), abs=1e-12)+++def test_cap_weighting_changes_the_fit_toward_the_larger_names():+ rng = np.random.default_rng(11)+ index = _assets(200)+ exposures = pd.DataFrame({"value": rng.normal(0, 1, 200)}, index=index)+ returns = pd.Series(rng.normal(0, 0.01, 200), index=index)+ # Big names all get an extra +5% that the small ones do not.+ caps = pd.Series(np.r_[np.full(20, 1e12), np.full(180, 1e8)], index=index)+ returns.iloc[:20] += 0.05++ unweighted = cross_sectional_factor_returns(returns, exposures)+ weighted = cross_sectional_factor_returns(returns, exposures, market_caps=caps)++ assert weighted.factor_returns[MARKET_FACTOR] > unweighted.factor_returns[MARKET_FACTOR]+++def test_collinear_exposures_are_rejected_not_silently_pseudo_inverted():+ rng = np.random.default_rng(12)+ index = _assets(100)+ base = rng.normal(0, 1, 100)+ exposures = pd.DataFrame({"a": base, "b": base * 2.0}, index=index)+ returns = pd.Series(rng.normal(0, 0.01, 100), index=index)++ with pytest.raises(ValueError, match="collinear"):+ cross_sectional_factor_returns(returns, exposures)+++def test_constant_exposure_column_is_collinear_with_the_market():+ index = _assets(100)+ exposures = pd.DataFrame({"dud": np.ones(100)}, index=index)+ returns = pd.Series(np.random.default_rng(13).normal(0, 0.01, 100), index=index)++ with pytest.raises(ValueError, match="collinear"):+ cross_sectional_factor_returns(returns, exposures)+++def test_too_few_assets_rejected():+ index = _assets(5)+ exposures = pd.DataFrame({"value": np.arange(5.0)}, index=index)+ returns = pd.Series(np.arange(5.0) / 100, index=index)++ with pytest.raises(ValueError, match="at least"):+ cross_sectional_factor_returns(returns, exposures)+++def test_non_positive_market_caps_rejected():+ rng = np.random.default_rng(14)+ index = _assets(100)+ exposures = pd.DataFrame({"value": rng.normal(0, 1, 100)}, index=index)+ returns = pd.Series(rng.normal(0, 0.01, 100), index=index)+ caps = pd.Series(np.r_[np.zeros(1), np.full(99, 1e9)], index=index)++ with pytest.raises(ValueError, match="must be positive"):+ cross_sectional_factor_returns(returns, exposures, market_caps=caps)+++# --- portfolio exposure ---+++def test_portfolio_exposure_is_the_weighted_sum():+ index = _assets(4)+ exposures = pd.DataFrame({"value": [1.0, -1.0, 2.0, 0.0]}, index=index)+ holdings = pd.Series([0.25, 0.25, 0.25, 0.25], index=index)++ result = portfolio_style_exposure(holdings, exposures)+ assert result["value"] == pytest.approx(0.5)+ assert result["unmatched_weight"] == 0.0+++def test_active_exposure_subtracts_the_benchmark():+ index = _assets(4)+ exposures = pd.DataFrame({"value": [1.0, 1.0, -1.0, -1.0]}, index=index)+ holdings = pd.Series([0.5, 0.5, 0.0, 0.0], index=index)+ benchmark = pd.Series([0.25, 0.25, 0.25, 0.25], index=index)++ active = portfolio_style_exposure(holdings, exposures, benchmark=benchmark)+ assert active["value"] == pytest.approx(1.0)+++def test_holdings_without_exposure_data_are_disclosed_not_dropped():+ exposures = pd.DataFrame({"value": [1.0, 1.0]}, index=["A000", "A001"])+ holdings = pd.Series([0.3, 0.3, 0.4], index=["A000", "A001", "UNKNOWN"])++ result = portfolio_style_exposure(holdings, exposures)+ assert result["value"] == pytest.approx(0.6)+ assert result["unmatched_weight"] == pytest.approx(0.4)+++def test_partially_invested_book_reports_a_scaled_exposure():+ exposures = pd.DataFrame({"value": [1.0, 1.0]}, index=["A000", "A001"])+ half_invested = pd.Series([0.3, 0.3], index=["A000", "A001"])+ assert portfolio_style_exposure(half_invested, exposures)["value"] == pytest.approx(0.6)+++def test_empty_holdings_rejected():+ exposures = pd.DataFrame({"value": [1.0]}, index=["A000"])+ with pytest.raises(ValueError, match="holdings is empty"):+ portfolio_style_exposure(pd.Series(dtype=float), exposures)+++# --- style drift ---+++def test_style_drift_measures_movement_not_endpoints():+ # A fund that ends where it started but went somewhere else in between has+ # drifted, and total_change alone would say it had not.+ history = pd.DataFrame(+ {"value": [0.0, 1.5, -1.5, 0.0], "size": [0.2, 0.2, 0.2, 0.2]},+ index=pd.date_range("2024-01-31", periods=4, freq="ME"),+ )+ drift = style_drift(history)++ assert drift.total_change["value"] == pytest.approx(0.0)+ assert drift.max_abs_change["value"] == pytest.approx(3.0)+ assert drift.std_exposure["value"] > drift.std_exposure["size"]+ assert drift.std_exposure["size"] == pytest.approx(0.0)+++def test_style_drift_reports_first_and_last():+ history = pd.DataFrame(+ {"momentum": [-1.0, 0.0, 1.0]},+ index=pd.date_range("2024-01-31", periods=3, freq="ME"),+ )+ drift = style_drift(history)+ assert drift.first_exposure["momentum"] == -1.0+ assert drift.last_exposure["momentum"] == 1.0+ assert drift.total_change["momentum"] == pytest.approx(2.0)+++def test_style_drift_ignores_the_unmatched_weight_column():+ history = pd.DataFrame(+ {"value": [0.5, 0.7], "unmatched_weight": [0.1, 0.2]},+ index=pd.date_range("2024-01-31", periods=2, freq="ME"),+ )+ drift = style_drift(history)+ assert "unmatched_weight" not in drift.mean_exposure.index+++def test_style_drift_needs_two_dates():+ history = pd.DataFrame({"value": [0.5]}, index=pd.date_range("2024-01-31", periods=1))+ with pytest.raises(ValueError, match="at least 2 dates"):+ style_drift(history)+++# --- attribution ---+++def test_attribution_parts_sum_to_the_portfolio_return_exactly():+ exposures = pd.Series({"value": 0.5, "momentum": -0.3, "unmatched_weight": 0.1})+ factor_returns = pd.Series({"value": 0.02, "momentum": 0.01, MARKET_FACTOR: 0.005})++ result = factor_return_attribution(exposures, factor_returns, portfolio_return=0.015)++ parts = result.drop(labels=["total"])+ assert float(parts.sum()) == pytest.approx(0.015, abs=1e-15)+ assert result["total"] == pytest.approx(0.015)+ assert result["value"] == pytest.approx(0.5 * 0.02)+ assert result["momentum"] == pytest.approx(-0.3 * 0.01)+++def test_attribution_residual_absorbs_whatever_the_factors_miss():+ exposures = pd.Series({"value": 1.0})+ factor_returns = pd.Series({"value": 0.01})+ result = factor_return_attribution(exposures, factor_returns, portfolio_return=0.05)+ assert result["specific"] == pytest.approx(0.04)+++def test_attribution_ignores_the_unmatched_weight_entry():+ exposures = pd.Series({"value": 1.0, "unmatched_weight": 0.9})+ factor_returns = pd.Series({"value": 0.01, "unmatched_weight": 99.0})+ result = factor_return_attribution(exposures, factor_returns, portfolio_return=0.02)+ assert "unmatched_weight" not in result.index+ assert result["specific"] == pytest.approx(0.01)+++def test_attribution_rejects_disjoint_factor_sets():+ with pytest.raises(ValueError, match="share no factor"):+ factor_return_attribution(+ pd.Series({"value": 1.0}), pd.Series({"momentum": 0.01}), portfolio_return=0.0+ )diff --git a/agent/tests/quantlib/test_fundmath.py b/agent/tests/quantlib/test_fundmath.pyindex 7c15510d7..64e658d46 100644--- a/agent/tests/quantlib/test_fundmath.py+++ b/agent/tests/quantlib/test_fundmath.py@@ -16,6 +16,7 @@ test agree with itself.import datetime as dtimport numpy as np+import pandas as pdimport pytestfrom src.entities.cashflow import CashFlow, CashFlowSeries@@ -25,19 +26,27 @@ from src.quantlib.fundmath import (TIER_CATCH_UP,TIER_PREFERRED_RETURN,TIER_RETURN_OF_CAPITAL,+ AmericanWaterfallResult,+ ClawbackResult,FundMultiples,NoSignChangeError,+ PMEPlusResult,WaterfallResult,WaterfallTier,XIRRConvergenceError,XIRRError,+ american_waterfall,+ direct_alpha,distributed_capital,dpi,european_waterfall,fund_multiples,+ gp_clawback,+ ks_pme,moic,npv,paid_in_capital,+ pme_plus,preferred_return_amount,residual_value,rvpi,@@ -724,3 +733,495 @@ def test_the_series_waterfall_distributes_realised_cash_by_default():def test_the_series_waterfall_refuses_a_bare_list():with pytest.raises(TypeError, match="CashFlowSeries"):european_waterfall([-100.0, 150.0], preferred_rate=0.08, carry_rate=0.2)+++# --------------------------------------------------------------------------+# PME — shared fixtures+# --------------------------------------------------------------------------+#+# One index, used everywhere below: 100 on 2019-01-01, 150 on 2020-01-01 (a+# 50% index return over exactly one year -- 2019 is not a leap year, so the+# span is exactly 365 days and every hand-computed rate below is a clean+# fraction under the module's own days_per_year=365 default).++INDEX = pd.Series({dt.date(2019, 1, 1): 100.0, dt.date(2020, 1, 1): 150.0})+++# --------------------------------------------------------------------------+# ks_pme+# --------------------------------------------------------------------------+++def test_ks_pme_of_a_fund_that_beat_the_index():+ """-1000 in, +2000 out, one year later, index +50% over the same year.++ FV(contributions) = 1000 * 150/100 = 1500+ FV(distributions) = 2000 * 150/150 = 2000+ KS-PME = 2000 / 1500 = 4/3+ """+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ assert ks_pme(series, INDEX) == pytest.approx(4.0 / 3.0, abs=1e-12)+++def test_ks_pme_of_a_fund_that_lagged_the_index():+ """-1000 in, +900 out: FV(contrib)=1500, FV(dist)=900, KS-PME = 0.6."""+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 900.0, "distribution")]+ )+ assert ks_pme(series, INDEX) == pytest.approx(0.6, abs=1e-12)+++def test_ks_pme_double_sided_guard():+ """Outperformance -> KS-PME > 1; underperformance -> KS-PME < 1."""+ winner = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ loser = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 900.0, "distribution")]+ )+ assert ks_pme(winner, INDEX) > 1.0+ assert ks_pme(loser, INDEX) < 1.0+++def test_ks_pme_includes_terminal_nav_via_residual_value():+ """-1000 in, +600 realised, +700 NAV, all valued as of 2020-01-01.++ FV(contrib) = 1500, FV(dist) = 600, FV(NAV) = 700 (factor 1, same date).+ KS-PME = (600 + 700) / 1500 = 13/15.+ """+ series = make_series(+ [+ ("2019-01-01", -1000.0, "capital_call"),+ ("2020-01-01", 600.0, "distribution"),+ ("2020-01-01", 700.0, "nav"),+ ]+ )+ assert ks_pme(series, INDEX) == pytest.approx(1300.0 / 1500.0, abs=1e-12)+++def test_ks_pme_only_the_latest_mark_counts_matching_residual_value():+ """Two marks, an early stale one and the terminal one; only the terminal counts."""+ with_stale_mark = make_series(+ [+ ("2019-01-01", -1000.0, "capital_call"),+ ("2019-06-01", 5000.0, "nav"), # stale, must be ignored+ ("2020-01-01", 600.0, "distribution"),+ ("2020-01-01", 700.0, "nav"),+ ]+ )+ index_with_extra_date = pd.Series(+ {dt.date(2019, 1, 1): 100.0, dt.date(2019, 6, 1): 120.0, dt.date(2020, 1, 1): 150.0}+ )+ assert ks_pme(with_stale_mark, index_with_extra_date) == pytest.approx(+ 1300.0 / 1500.0, abs=1e-12+ )+++def test_ks_pme_refuses_no_contributions():+ series = make_series([("2020-01-01", 100.0, "distribution")])+ with pytest.raises(ValueError, match="no contributions"):+ ks_pme(series, INDEX)+++def test_ks_pme_refuses_a_missing_index_date():+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ sparse_index = pd.Series({dt.date(2020, 1, 1): 150.0}) # missing 2019-01-01+ with pytest.raises(ValueError, match="no entry for 2019-01-01"):+ ks_pme(series, sparse_index)+++def test_ks_pme_refuses_a_bare_list():+ with pytest.raises(TypeError, match="CashFlowSeries"):+ ks_pme([-1000.0, 2000.0], INDEX)+++def test_ks_pme_refuses_a_non_series_index():+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ with pytest.raises(TypeError, match="pandas Series"):+ ks_pme(series, {dt.date(2019, 1, 1): 100.0})+++def test_ks_pme_refuses_an_empty_index():+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ with pytest.raises(ValueError, match="empty"):+ ks_pme(series, pd.Series(dtype=float))+++# --------------------------------------------------------------------------+# pme_plus+# --------------------------------------------------------------------------+++def test_pme_plus_scales_distributions_to_match_actual_nav():+ """No NAV (fully realised): lambda = FV(contrib)/FV(dist) = 1500/2000 = 0.75.++ Scaled series: -1000 @ 2019-01-01, +1500 @ 2020-01-01 -> IRR = 0.5.+ """+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ result = pme_plus(series, INDEX)+ assert isinstance(result, PMEPlusResult)+ assert result.scaling_factor == pytest.approx(0.75, abs=1e-12)+ assert result.irr == pytest.approx(0.5, abs=1e-9)+ # Fund's own realised IRR (100%) exceeds the PME+ IRR (50%): outperformance.+ assert xirr(series) > result.irr+++def test_pme_plus_with_a_terminal_nav():+ """+600 realised, +700 NAV, both dated 2020-01-01.++ lambda = (FV(contrib) - FV(NAV)) / FV(dist) = (1500 - 700) / 600 = 4/3.+ Scaled distribution = 600 * 4/3 = 800; scaled series -1000, +800, +700 (nav)+ at the same date collapse to -1000 + 1500 one year later -> IRR = 0.5.+ """+ series = make_series(+ [+ ("2019-01-01", -1000.0, "capital_call"),+ ("2020-01-01", 600.0, "distribution"),+ ("2020-01-01", 700.0, "nav"),+ ]+ )+ result = pme_plus(series, INDEX)+ assert result.scaling_factor == pytest.approx(4.0 / 3.0, abs=1e-12)+ assert result.irr == pytest.approx(0.5, abs=1e-9)+ # Fund's own realised IRR (30%) is below the PME+ IRR (50%): underperformance,+ # consistent with this same series' KS-PME of 13/15 < 1.+ assert xirr(series) < result.irr+++def test_pme_plus_refuses_no_distributions():+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 1200.0, "nav")]+ )+ with pytest.raises(ValueError, match="no distributions"):+ pme_plus(series, INDEX)+++def test_pme_plus_refuses_no_contributions():+ series = make_series([("2020-01-01", 100.0, "distribution")])+ with pytest.raises(ValueError, match="no contributions"):+ pme_plus(series, INDEX)+++def test_pme_plus_refuses_a_missing_index_date():+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ sparse_index = pd.Series({dt.date(2019, 1, 1): 100.0}) # missing 2020-01-01+ with pytest.raises(ValueError, match="no entry for 2020-01-01"):+ pme_plus(series, sparse_index)+++# --------------------------------------------------------------------------+# direct_alpha+# --------------------------------------------------------------------------+++def test_direct_alpha_of_a_fund_that_beat_the_index():+ """Deflated series: -1000/100=-10 @ t0, 2000/150=13.3333 @ t0+1y.++ IRR of (-10, +40/3 one year later) solves 1+r = (40/3)/10 = 4/3 -> r = 1/3.+ """+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ assert direct_alpha(series, INDEX) == pytest.approx(1.0 / 3.0, abs=1e-9)+++def test_direct_alpha_of_a_fund_that_lagged_the_index():+ """Deflated series: -10 @ t0, 900/150=6 @ t0+1y -> 1+r=0.6 -> r=-0.4."""+ series = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 900.0, "distribution")]+ )+ assert direct_alpha(series, INDEX) == pytest.approx(-0.4, abs=1e-9)+++def test_direct_alpha_double_sided_guard():+ winner = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ loser = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 900.0, "distribution")]+ )+ assert direct_alpha(winner, INDEX) > 0.0+ assert direct_alpha(loser, INDEX) < 0.0+++def test_direct_alpha_agrees_with_ks_pme_and_pme_plus_on_direction():+ """All three metrics must agree on which of two funds outperformed."""+ winner = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 2000.0, "distribution")]+ )+ loser = make_series(+ [("2019-01-01", -1000.0, "capital_call"), ("2020-01-01", 900.0, "distribution")]+ )+ assert ks_pme(winner, INDEX) > 1.0 and direct_alpha(winner, INDEX) > 0.0+ assert xirr(winner) > pme_plus(winner, INDEX).irr+ assert ks_pme(loser, INDEX) < 1.0 and direct_alpha(loser, INDEX) < 0.0+ assert xirr(loser) < pme_plus(loser, INDEX).irr+++def test_direct_alpha_needs_the_index_to_cover_every_mark_not_only_the_terminal_one():+ """Unlike ks_pme/pme_plus, direct_alpha deflates every flow before the+ valuation policy runs, so even a mark that "terminal" will later drop+ still needs an index entry.+ """+ series = make_series(+ [+ ("2019-01-01", -1000.0, "capital_call"),+ ("2019-06-01", 5000.0, "nav"), # stale mark, dropped by the default policy+ ("2020-01-01", 600.0, "distribution"),+ ("2020-01-01", 700.0, "nav"),+ ]+ )+ # INDEX has no entry for 2019-06-01, the stale mark's date.+ with pytest.raises(ValueError, match="no entry for 2019-06-01"):+ direct_alpha(series, INDEX)+++def test_direct_alpha_on_an_all_valuation_series_raises():+ """No contributions, no distributions -- only two NAV marks.++ The default "terminal" valuation policy collapses this to one flow, which+ xirr() already refuses; direct_alpha inherits that refusal unchanged.+ """+ series = make_series([("2019-01-01", 100.0, "nav"), ("2020-01-01", 120.0, "nav")])+ with pytest.raises(ValueError, match="at least two flows"):+ direct_alpha(series, INDEX)+++def test_direct_alpha_refuses_a_bare_list():+ with pytest.raises(TypeError, match="CashFlowSeries"):+ direct_alpha([-1000.0, 2000.0], INDEX)+++# --------------------------------------------------------------------------+# american_waterfall+# --------------------------------------------------------------------------+++def test_a_single_deal_american_waterfall_matches_european_waterfall():+ """A one-deal American waterfall must reduce exactly to a European one."""+ series = make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2022-01-01", 150.0, "distribution")]+ )+ american = american_waterfall(+ {"only": series},+ preferred_rate=0.08,+ carry_rate=0.20,+ catch_up_rate=1.0,+ compounding="simple",+ )+ european = european_waterfall(+ series, preferred_rate=0.08, carry_rate=0.20, catch_up_rate=1.0, compounding="simple"+ )+ assert american.gp_total == pytest.approx(european.gp_total)+ assert american.lp_total == pytest.approx(european.lp_total)+ assert american.distributable == pytest.approx(european.distributable)+ assert american.deals["only"].gp_total == pytest.approx(european.gp_total)+++def test_american_waterfall_pays_carry_deal_by_deal_hand_computed():+ """Two deals, 0% pref (so preferred/catch-up tiers vanish), 20% carry.++ Deal A: 100 in, 250 out -> profit 150 -> GP 30, LP 220.+ Deal B: 100 in, 20 out -> a loss, no profit -> GP 0, LP 20.+ Aggregate: GP 30, LP 240, distributable 270.+ """+ deals = {+ "A": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2020-06-01", 250.0, "distribution")]+ ),+ "B": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2021-01-01", 20.0, "distribution")]+ ),+ }+ result = american_waterfall(deals, preferred_rate=0.0, carry_rate=0.20, catch_up_rate=1.0)+ assert isinstance(result, AmericanWaterfallResult)+ assert result.deals["A"].gp_total == pytest.approx(30.0)+ assert result.deals["A"].lp_total == pytest.approx(220.0)+ assert result.deals["B"].gp_total == pytest.approx(0.0)+ assert result.deals["B"].lp_total == pytest.approx(20.0)+ assert result.gp_total == pytest.approx(30.0)+ assert result.lp_total == pytest.approx(240.0)+ assert result.distributable == pytest.approx(270.0)+++def test_american_waterfall_catch_up_is_reused_unchanged_from_waterfall_split():+ """Deal-level catch-up must match the existing worked example exactly."""+ series = make_series(+ [("2018-01-01", -100.0, "capital_call"), ("2020-01-01", 200.0, "distribution")]+ )+ result = american_waterfall(+ {"deal": series}, preferred_rate=0.08, carry_rate=0.20, catch_up_rate=0.50+ )+ deal_result = result.deals["deal"]+ assert deal_result.gp_total == pytest.approx(20.0)+ assert deal_result.gp_profit_share == pytest.approx(0.20)+++def test_american_waterfall_refuses_empty_deals():+ with pytest.raises(ValueError, match="deals is empty"):+ american_waterfall({}, preferred_rate=0.08, carry_rate=0.20)+++def test_american_waterfall_refuses_a_non_mapping():+ with pytest.raises(TypeError, match="mapping"):+ american_waterfall([("only", None)], preferred_rate=0.08, carry_rate=0.20)+++def test_american_waterfall_refuses_mixed_currencies():+ deals = {+ "A": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2021-01-01", 150.0, "distribution")],+ currency="USD",+ ),+ "B": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2021-01-01", 150.0, "distribution")],+ currency="EUR",+ ),+ }+ with pytest.raises(ValueError, match="multiple currencies"):+ american_waterfall(deals, preferred_rate=0.08, carry_rate=0.20)+++# --------------------------------------------------------------------------+# gp_clawback — the headline test: same cash flows, European=0, American>0+# --------------------------------------------------------------------------+++def test_european_never_claws_back_but_american_does_on_the_same_cash_flows():+ """The single most important test in this file.++ Same two deals as the hand-computed American test above (0% pref, 20%+ carry, 100% catch-up):++ Deal A: 100 in, 250 out (day ~150) -> profit 150 -> GP carry 30+ Deal B: 100 in, 20 out (later) -> a loss -> GP carry 0++ American (deal-by-deal): carry_received = 30 (paid the moment deal A+ exits, with no visibility into deal B's eventual loss).++ Pooled/European (whole-of-fund): contributed 200, distributed 270,+ profit 70, entitled GP carry = 0.20 * 70 = 14. A European structure only+ ever pays carry once, off exactly this pooled number, so its "received"+ and "entitled" are the same 14 by construction -- clawback is always 0.++ American clawback = max(0, 30 - 14) = 16 > 0: the GP was paid 30 on deal+ A's early profit but only 14 was ever earned once deal B's loss is+ counted, so 16 must come back.+ """+ deals = {+ "A": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2020-06-01", 250.0, "distribution")]+ ),+ "B": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2021-01-01", 20.0, "distribution")]+ ),+ }++ american = gp_clawback(deals, preferred_rate=0.0, carry_rate=0.20, catch_up_rate=1.0)+ assert isinstance(american, ClawbackResult)+ assert american.carry_received == pytest.approx(30.0)+ assert american.carry_entitled == pytest.approx(14.0)+ assert american.clawback_amount == pytest.approx(16.0)+ assert american.clawback_amount > 0.0++ pooled = make_series(+ [+ ("2020-01-01", -100.0, "capital_call"),+ ("2020-06-01", 250.0, "distribution"),+ ("2020-01-01", -100.0, "capital_call"),+ ("2021-01-01", 20.0, "distribution"),+ ]+ )+ european = european_waterfall(pooled, preferred_rate=0.0, carry_rate=0.20, catch_up_rate=1.0)+ assert european.gp_total == pytest.approx(14.0)+ # European pays once off the pooled totals: "received" and "entitled" are+ # the same number by construction, so the clawback is exactly zero.+ european_carry_received = european.gp_total+ european_carry_entitled = european.gp_total+ european_clawback = max(0.0, european_carry_received - european_carry_entitled)+ assert european_clawback == 0.0+++def test_gp_clawback_tax_adjustment_scales_down_the_gross_amount():+ """Same scenario, 30% GP tax rate: net clawback = 16 * (1 - 0.30) = 11.2."""+ deals = {+ "A": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2020-06-01", 250.0, "distribution")]+ ),+ "B": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2021-01-01", 20.0, "distribution")]+ ),+ }+ gross = gp_clawback(deals, preferred_rate=0.0, carry_rate=0.20, catch_up_rate=1.0)+ net = gp_clawback(+ deals, preferred_rate=0.0, carry_rate=0.20, catch_up_rate=1.0, gp_tax_rate=0.30+ )+ assert gross.tax_adjusted is False+ assert gross.gp_tax_rate is None+ assert net.tax_adjusted is True+ assert net.gp_tax_rate == pytest.approx(0.30)+ assert net.clawback_amount == pytest.approx(11.2)+ assert net.clawback_amount == pytest.approx(gross.clawback_amount * 0.70)+ # The received/entitled figures themselves are unaffected by tax.+ assert net.carry_received == pytest.approx(gross.carry_received)+ assert net.carry_entitled == pytest.approx(gross.carry_entitled)+++def test_gp_clawback_is_zero_when_no_deal_outpaced_the_pooled_entitlement():+ """A single profitable deal: deal-by-deal and pooled totals coincide."""+ deals = {+ "only": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2021-01-01", 150.0, "distribution")]+ )+ }+ result = gp_clawback(deals, preferred_rate=0.0, carry_rate=0.20, catch_up_rate=1.0)+ assert result.carry_received == pytest.approx(result.carry_entitled)+ assert result.clawback_amount == 0.0+++def test_gp_clawback_refuses_out_of_range_tax_rate():+ deals = {+ "only": make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2021-01-01", 150.0, "distribution")]+ )+ }+ with pytest.raises(ValueError, match="gp_tax_rate"):+ gp_clawback(deals, preferred_rate=0.08, carry_rate=0.20, gp_tax_rate=1.0)+ with pytest.raises(ValueError, match="gp_tax_rate"):+ gp_clawback(deals, preferred_rate=0.08, carry_rate=0.20, gp_tax_rate=-0.1)+++def test_gp_clawback_refuses_empty_deals():+ with pytest.raises(ValueError, match="deals is empty"):+ gp_clawback({}, preferred_rate=0.08, carry_rate=0.20)+++def test_clawback_result_rejects_an_inconsistent_tax_flag():+ with pytest.raises(ValueError, match="tax_adjusted"):+ ClawbackResult(+ carry_received=10.0,+ carry_entitled=5.0,+ clawback_amount=5.0,+ tax_adjusted=True,+ gp_tax_rate=None,+ )+ with pytest.raises(ValueError, match="tax_adjusted"):+ ClawbackResult(+ carry_received=10.0,+ carry_entitled=5.0,+ clawback_amount=5.0,+ tax_adjusted=False,+ gp_tax_rate=0.3,+ )diff --git a/agent/tests/quantlib/test_multipletesting.py b/agent/tests/quantlib/test_multipletesting.pynew file mode 100644index 000000000..fecdf65cf--- /dev/null+++ b/agent/tests/quantlib/test_multipletesting.py@@ -0,0 +1,342 @@+"""Tests for src.quantlib.multipletesting.++The load-bearing tests here are the ones that show a correction actually bites:+a Sharpe that passes uncorrected and fails once the trial count is admitted, and+a pure-noise strategy set whose PBO comes out near or above one half.+"""++import math++import numpy as np+import pandas as pd+import pytest+from scipy.stats import norm++from src.quantlib.multipletesting import (+ DEFAULT_CSCV_SPLITS,+ EULER_MASCHERONI,+ GAUSSIAN_KURTOSIS,+ MIN_OBSERVATIONS,+ benjamini_hochberg,+ deflated_sharpe_ratio,+ expected_maximum_sharpe,+ probabilistic_sharpe_ratio,+ probability_of_backtest_overfitting,+ sharpe_ratio,+)+++# --- sharpe helper ---+++def test_sharpe_is_per_observation_not_annualised():+ rng = np.random.default_rng(0)+ daily = rng.normal(0.0005, 0.01, 5000)+ sr = sharpe_ratio(daily)+ assert sr == pytest.approx(0.05, abs=0.02)+ # An annualised reading would be ~sqrt(252) larger. It is not.+ assert sr < 0.5+++def test_sharpe_ddof_is_exposed_because_the_repo_has_two_conventions():+ values = np.array([0.01, -0.005, 0.02, 0.0, 0.015])+ ratio = sharpe_ratio(values, ddof=1) / sharpe_ratio(values, ddof=0)+ assert ratio == pytest.approx(math.sqrt((len(values) - 1) / len(values)))+++def test_sharpe_is_nan_without_dispersion():+ assert math.isnan(sharpe_ratio(np.full(50, 0.01)))+++def test_sharpe_needs_two_observations():+ with pytest.raises(ValueError, match="at least 2"):+ sharpe_ratio([0.01])+++# --- probabilistic Sharpe ---+++def test_psr_matches_the_closed_form_under_gaussian_moments():+ sr, n = 0.10, 500+ expected = norm.cdf(sr * math.sqrt(n - 1) / math.sqrt(1 + 0.5 * sr**2))+ assert probabilistic_sharpe_ratio(sr, n) == pytest.approx(expected, rel=1e-12)+++def test_psr_rises_with_sample_length():+ a = probabilistic_sharpe_ratio(0.05, 100)+ b = probabilistic_sharpe_ratio(0.05, 1000)+ assert b > a+++def test_negative_skew_and_fat_tails_both_reduce_confidence():+ base = probabilistic_sharpe_ratio(0.10, 500, skew=0.0, kurtosis=GAUSSIAN_KURTOSIS)+ skewed = probabilistic_sharpe_ratio(0.10, 500, skew=-1.5, kurtosis=GAUSSIAN_KURTOSIS)+ fat = probabilistic_sharpe_ratio(0.10, 500, skew=0.0, kurtosis=12.0)++ assert skewed < base+ assert fat < base+++def test_excess_kurtosis_passed_by_mistake_is_rejected_not_absorbed():+ # scipy.stats.kurtosis and pandas .kurt both return EXCESS kurtosis, which+ # is 0 for a Gaussian. Silently accepting 0 would shrink the variance term+ # and overstate confidence, so it must be an error.+ with pytest.raises(ValueError, match="non-excess"):+ probabilistic_sharpe_ratio(0.10, 500, kurtosis=0.0)+++def test_psr_rejects_a_sample_too_short_for_its_own_moments():+ with pytest.raises(ValueError, match="at least"):+ probabilistic_sharpe_ratio(0.10, MIN_OBSERVATIONS - 1)+++def test_psr_rejects_mutually_inconsistent_moments():+ with pytest.raises(ValueError, match="not\\s+positive|mutually inconsistent"):+ probabilistic_sharpe_ratio(2.0, 500, skew=5.0, kurtosis=1.0)+++# --- expected maximum Sharpe ---+++def test_expected_maximum_grows_with_the_number_of_trials():+ bars = [expected_maximum_sharpe(n, 0.1) for n in (2, 10, 100, 1000)]+ assert bars == sorted(bars)+ assert all(b > 0 for b in bars)+++def test_expected_maximum_matches_the_closed_form():+ n, std = 462, 0.08+ expected = std * (+ (1 - EULER_MASCHERONI) * norm.ppf(1 - 1 / n)+ + EULER_MASCHERONI * norm.ppf(1 - 1 / (n * math.e))+ )+ assert expected_maximum_sharpe(n, std) == pytest.approx(expected, rel=1e-12)+++def test_expected_maximum_is_zero_without_a_search():+ assert expected_maximum_sharpe(1, 0.1) == 0.0+ assert expected_maximum_sharpe(500, 0.0) == 0.0+++def test_expected_maximum_scales_linearly_in_trial_dispersion():+ assert expected_maximum_sharpe(100, 0.2) == pytest.approx(+ 2 * expected_maximum_sharpe(100, 0.1)+ )+++def test_expected_maximum_rejects_impossible_inputs():+ with pytest.raises(ValueError, match="n_trials"):+ expected_maximum_sharpe(0, 0.1)+ with pytest.raises(ValueError, match="trial_sharpe_std"):+ expected_maximum_sharpe(10, -0.1)+++# --- deflated Sharpe: the correction has to actually bite ---+++def test_a_sharpe_that_passes_uncorrected_fails_once_the_search_is_admitted():+ # This is the whole point of the module. Same observed Sharpe, same sample:+ # one trial and it is convincing, 462 trials and it is not.+ observed, n_obs, dispersion = 0.09, 1000, 0.06++ undeflated = probabilistic_sharpe_ratio(observed, n_obs)+ assert undeflated > 0.99++ deflated = deflated_sharpe_ratio(+ observed_sharpe=observed,+ n_trials=462,+ n_observations=n_obs,+ trial_sharpe_std=dispersion,+ )+ assert deflated.expected_maximum_sharpe > 0.15+ assert deflated.deflated_sharpe_ratio < 0.05+ assert not deflated.survives+++def test_a_genuinely_strong_result_still_survives_the_correction():+ # Two-sided: the correction must not reject everything, or it is useless.+ strong = deflated_sharpe_ratio(+ observed_sharpe=0.30,+ n_trials=462,+ n_observations=2000,+ trial_sharpe_std=0.06,+ )+ assert strong.survives+ assert strong.deflated_sharpe_ratio > 0.95+++def test_deflation_bar_is_exactly_the_expected_maximum():+ result = deflated_sharpe_ratio(0.2, n_trials=100, n_observations=500, trial_sharpe_std=0.05)+ assert result.expected_maximum_sharpe == pytest.approx(+ expected_maximum_sharpe(100, 0.05)+ )+ assert result.deflated_sharpe_ratio == pytest.approx(+ probabilistic_sharpe_ratio(0.2, 500, benchmark_sharpe=result.expected_maximum_sharpe)+ )+++def test_more_trials_monotonically_lowers_the_deflated_ratio():+ values = [+ deflated_sharpe_ratio(0.15, n, 1000, 0.05).deflated_sharpe_ratio+ for n in (1, 10, 100, 1000)+ ]+ assert values == sorted(values, reverse=True)+++def test_deflated_result_carries_the_inputs_it_was_judged_on():+ result = deflated_sharpe_ratio(0.15, 50, 800, 0.04, skew=-0.4, kurtosis=6.0)+ assert result.n_trials == 50+ assert result.n_observations == 800+ assert result.skew == -0.4+ assert result.kurtosis == 6.0+ assert result.confidence == 0.95+++def test_deflated_rejects_a_bad_confidence():+ with pytest.raises(ValueError, match="confidence"):+ deflated_sharpe_ratio(0.1, 10, 500, 0.05, confidence=1.5)+++# --- Benjamini-Hochberg ---+++def test_bh_rejects_nothing_when_every_null_is_true():+ rng = np.random.default_rng(1)+ p_values = rng.uniform(0, 1, 1000) # uniform under the null+ result = benjamini_hochberg(p_values, fdr=0.05)+ assert result.n_rejected <= 50 # expected false discoveries bounded by fdr+++def test_bh_finds_the_planted_signals():+ rng = np.random.default_rng(2)+ p_values = np.r_[rng.uniform(0, 1e-6, 20), rng.uniform(0, 1, 480)]+ result = benjamini_hochberg(p_values, fdr=0.05)+ assert result.n_rejected >= 20+ assert result.rejected[:20].all()+++def test_bh_is_less_strict_than_bonferroni():+ # Fifty p-values just under 0.001 with n=1000: Bonferroni (0.05/1000 =+ # 5e-5) rejects none of them, BH rejects them all.+ p_values = np.r_[np.full(50, 9e-4), np.full(950, 0.5)]+ result = benjamini_hochberg(p_values, fdr=0.05)+ assert (p_values[:50] > 0.05 / 1000).all()+ assert result.n_rejected == 50+++def test_bh_adjusted_p_values_are_monotone_in_the_raw_ones():+ rng = np.random.default_rng(3)+ p_values = rng.uniform(0, 1, 200)+ result = benjamini_hochberg(p_values)+ order = np.argsort(p_values)+ adjusted_sorted = result.adjusted_p_values[order]+ assert np.all(np.diff(adjusted_sorted) >= -1e-15)+ assert (result.adjusted_p_values <= 1.0).all()+ assert (result.adjusted_p_values >= 0.0).all()+++def test_bh_results_come_back_in_the_callers_order():+ p_values = np.array([0.9, 1e-8, 0.4, 2e-8])+ result = benjamini_hochberg(p_values, fdr=0.05)+ assert result.rejected.tolist() == [False, True, False, True]+++def test_bh_rejection_set_is_exactly_the_step_up_rule():+ p_values = np.array([0.001, 0.008, 0.039, 0.041, 0.042, 0.6])+ n, fdr = len(p_values), 0.05+ ranks = np.arange(1, n + 1)+ expected_cutoff = int(ranks[np.sort(p_values) <= ranks / n * fdr].max())+ result = benjamini_hochberg(p_values, fdr=fdr)+ assert result.n_rejected == expected_cutoff++[email protected]("bad", [[], [0.5, 1.5], [0.5, -0.1], [0.5, np.nan]])+def test_bh_rejects_impossible_p_values(bad):+ with pytest.raises(ValueError):+ benjamini_hochberg(bad)+++def test_bh_rejects_a_bad_fdr():+ with pytest.raises(ValueError, match="fdr"):+ benjamini_hochberg([0.01, 0.02], fdr=0.0)+++# --- CSCV / PBO ---+++def test_pure_noise_strategies_give_a_pbo_around_one_half():+ # No strategy has any edge, so in-sample selection carries no information+ # and the winner lands either side of the OOS median about equally often.+ rng = np.random.default_rng(4)+ noise = pd.DataFrame(rng.normal(0.0, 0.01, (960, 12)))+ result = probability_of_backtest_overfitting(noise, n_splits=8)++ assert 0.3 < result.pbo < 0.75+ assert result.n_strategies == 12+++def test_a_genuinely_superior_strategy_drives_pbo_down():+ # One strategy really is better in every period, so the in-sample winner is+ # the same strategy out-of-sample and PBO collapses.+ rng = np.random.default_rng(5)+ data = rng.normal(0.0, 0.01, (960, 12))+ data[:, 3] += 0.004 # a large, persistent edge+ result = probability_of_backtest_overfitting(pd.DataFrame(data), n_splits=8)++ assert result.pbo < 0.05+++def test_performance_degradation_is_negative_when_selection_fits_noise():+ rng = np.random.default_rng(6)+ noise = pd.DataFrame(rng.normal(0.0, 0.01, (960, 15)))+ result = probability_of_backtest_overfitting(noise, n_splits=8)+ assert result.performance_degradation < 0+++def test_cscv_reports_rows_it_trimmed_rather_than_dropping_them_silently():+ rng = np.random.default_rng(7)+ # 1000 rows over 8 subsets leaves a remainder of 0; 1005 leaves 5.+ data = pd.DataFrame(rng.normal(0, 0.01, (1005, 5)))+ result = probability_of_backtest_overfitting(data, n_splits=8)+ assert result.dropped_observations == 1005 - (1005 // 8) * 8+ assert result.n_observations == (1005 // 8) * 8+++def test_cscv_split_count_is_the_full_combination_set():+ rng = np.random.default_rng(8)+ data = pd.DataFrame(rng.normal(0, 0.01, (480, 4)))+ result = probability_of_backtest_overfitting(data, n_splits=6)+ assert result.n_splits == math.comb(6, 3)+++def test_cscv_default_split_count_is_even_and_usable():+ assert DEFAULT_CSCV_SPLITS % 2 == 0+ assert DEFAULT_CSCV_SPLITS >= 4+++def test_cscv_rejects_an_odd_split_count():+ rng = np.random.default_rng(9)+ with pytest.raises(ValueError, match="even"):+ probability_of_backtest_overfitting(pd.DataFrame(rng.normal(0, 1, (200, 3))), n_splits=7)+++def test_cscv_needs_competing_strategies():+ rng = np.random.default_rng(10)+ with pytest.raises(ValueError, match="at least 2"):+ probability_of_backtest_overfitting(pd.DataFrame(rng.normal(0, 1, (200, 1))))+++def test_cscv_rejects_a_sample_too_short_for_its_subsets():+ rng = np.random.default_rng(11)+ with pytest.raises(ValueError, match="at least 2"):+ probability_of_backtest_overfitting(+ pd.DataFrame(rng.normal(0, 1, (10, 3))), n_splits=8+ )+++def test_cscv_logits_and_pbo_agree():+ rng = np.random.default_rng(12)+ data = pd.DataFrame(rng.normal(0, 0.01, (480, 6)))+ result = probability_of_backtest_overfitting(data, n_splits=6)+ assert result.pbo == pytest.approx((result.logits <= 0).mean())+ assert result.logits.size == result.n_splitsdiff --git a/agent/tests/quantlib/test_options.py b/agent/tests/quantlib/test_options.pyindex 2b030ef6c..af6a22299 100644--- a/agent/tests/quantlib/test_options.py+++ b/agent/tests/quantlib/test_options.py@@ -18,7 +18,12 @@ import mathimport pytest-from src.quantlib.options import bs_greeks, bs_price, implied_volatility+from src.quantlib.options import (+ bs_greeks,+ bs_price,+ implied_volatility,+ normalise_option_type,+)# Hull, Example 15.6: a six-month European option on a non-dividend stock._HULL_15_6 = {"S": 42.0, "K": 40.0, "T": 0.5, "r": 0.10, "sigma": 0.20}@@ -332,7 +337,10 @@ class TestEdgeCases:expected = bs_price(100.0, 100.0, 1.0, 0.05, 0.2, alias.strip().lower())assert bs_price(100.0, 100.0, 1.0, 0.05, 0.2, alias) == expected- @pytest.mark.parametrize("bad", ["c", "straddle", ""])+ # "c" used to appear here as an unknown type. It is now an accepted alias+ # (see _CALL_ALIASES), so the cases below are genuine typos and non-types --+ # the values for which guessing is unsafe.+ @pytest.mark.parametrize("bad", ["cal", "straddle", "", "1", "long"])def test_unknown_option_type_raises(self, bad: str) -> None:with pytest.raises(ValueError, match="option_type"):bs_price(100.0, 100.0, 1.0, 0.05, 0.2, bad)@@ -387,5 +395,64 @@ class TestEngineFoldsOptionTypeTheSameWay:def test_unknown_type_is_rejected_at_construction(self) -> None:from backtest.engines.options_portfolio import OptionPosition+ # A genuine typo, not "c" -- that is an accepted alias now.with pytest.raises(ValueError, match="option_type"):- OptionPosition("c", 100.0, "2026-01-01", 1, 5.0, "2025-10-01", "X")+ OptionPosition("cal", 100.0, "2026-01-01", 1, 5.0, "2025-10-01", "X")++ def test_an_aliased_type_is_accepted_at_construction(self) -> None:+ from backtest.engines.options_portfolio import OptionPosition++ # The engine folds through the same rule, so a config typed "C" builds+ # a position that prices AND settles as a call.+ pos = OptionPosition("C", 100.0, "2026-01-01", 1, 5.0, "2025-10-01", "X")+ assert pos.option_type == "call"+++# --- option-type aliases: compatibility without reintroducing the defaulting bug ---+++ "raw", ["call", "Call", "CALL", " call ", "calls", "C", "c", "看涨", "认购"]+)+def test_unambiguous_call_spellings_are_accepted(raw):+ assert normalise_option_type(raw) == "call"+++ "raw", ["put", "Put", "PUT", " put ", "puts", "P", "p", "看跌", "认沽"]+)+def test_unambiguous_put_spellings_are_accepted(raw):+ assert normalise_option_type(raw) == "put"++[email protected]("raw", ["cal", "kall", "pu", "", " ", "option", "1", "long"])+def test_a_typo_still_raises_rather_than_being_guessed_at(raw):+ # This is the half of the contract that must NOT be relaxed. Defaulting an+ # unrecognised type to put is what settled ten in-the-money call contracts+ # at zero.+ with pytest.raises(ValueError, match="unrecognised option_type"):+ normalise_option_type(raw)+++def test_the_error_message_lists_what_is_accepted():+ with pytest.raises(ValueError) as excinfo:+ normalise_option_type("cal")+ message = str(excinfo.value)+ assert "calls" in message and "puts" in message+++def test_aliases_price_identically_to_the_canonical_spelling():+ canonical = bs_price(100, 100, 1.0, 0.05, 0.2, "call")+ for alias in ("C", "CALLS", " 认购 "):+ assert bs_price(100, 100, 1.0, 0.05, 0.2, alias) == pytest.approx(canonical)+++def test_an_aliased_leg_prices_and_settles_as_the_same_side():+ # The original defect in one assertion: whatever the leg was typed as, the+ # side used to price it must be the side used to settle it.+ for alias, expected in (("C", "call"), ("认沽", "put"), ("Puts", "put")):+ folded = normalise_option_type(alias)+ assert folded == expected+ deep_itm = bs_price(200, 100, 0.01, 0.0, 0.2, alias) if folded == "call" else \+ bs_price(50, 100, 0.01, 0.0, 0.2, alias)+ assert deep_itm > 45.0diff --git a/agent/tests/quantlib/test_timeseries.py b/agent/tests/quantlib/test_timeseries.pyindex 3e31a5c9e..88c6c94f8 100644--- a/agent/tests/quantlib/test_timeseries.py+++ b/agent/tests/quantlib/test_timeseries.py@@ -21,6 +21,7 @@ from src.quantlib.timeseries import (compute_half_life,find_hedge_ratio,fit_garch,+ fit_markov_regime,granger_test,heteroscedasticity_test,vif_test,@@ -659,6 +660,129 @@ def test_importing_the_module_does_not_require_the_optional_backends():module = importlib.import_module("src.quantlib.timeseries")- assert len(module.__all__) == 11+ assert len(module.__all__) == 12assert "statsmodels" not in module.__dict__assert "arch" not in module.__dict__+++# --- Markov regime switching ---+++def _two_regime_series(seed=3, calm_len=200, turbulent_len=50, cycles=3,+ calm_vol=0.005, turbulent_vol=0.03, start_calm=True):+ """Build a series alternating between a calm and a turbulent regime."""+ rng = np.random.default_rng(seed)+ segments = []+ truth = []+ for cycle in range(cycles * 2):+ calm = (cycle % 2 == 0) == start_calm+ length = calm_len if calm else turbulent_len+ vol = calm_vol if calm else turbulent_vol+ segments.append(rng.normal(0.0, vol, length))+ truth += [0 if calm else 1] * length+ return pd.Series(np.concatenate(segments)), np.array(truth)+++def test_markov_regime_recovers_known_volatilities():+ series, _ = _two_regime_series(seed=3)+ result = fit_markov_regime(series)++ assert result["converged"]+ assert result["regime_vols"][0] == pytest.approx(0.005, rel=0.15)+ assert result["regime_vols"][1] == pytest.approx(0.030, rel=0.15)+++def test_markov_regimes_are_ordered_calmest_first_regardless_of_fit_order():+ # Label switching is the classic reproducibility trap: the EM fit returns+ # states in an arbitrary order. Starting the series in the turbulent regime+ # instead of the calm one must not change which index means "calm".+ calm_first, _ = _two_regime_series(seed=11, start_calm=True)+ turbulent_first, _ = _two_regime_series(seed=11, start_calm=False)++ a = fit_markov_regime(calm_first)+ b = fit_markov_regime(turbulent_first)++ for result in (a, b):+ vols = result["regime_vols"]+ assert np.all(np.diff(vols) >= 0), f"regimes not ascending in vol: {vols}"+ assert vols[0] < vols[1]+++def test_markov_transition_matrix_is_row_stochastic():+ series, _ = _two_regime_series(seed=5)+ transition = fit_markov_regime(series)["transition_matrix"]++ assert transition.shape == (2, 2)+ assert transition.sum(axis=1) == pytest.approx(np.ones(2))+ assert np.all(transition >= 0.0)+++def test_markov_transition_rows_read_from_today_to_tomorrow():+ # The calm regime here lasts 200 periods and the turbulent one 50, so the+ # calm row's diagonal must be the larger of the two. Reading the matrix+ # transposed would swap these and silently mislabel which state is sticky.+ series, _ = _two_regime_series(seed=7, calm_len=200, turbulent_len=50)+ result = fit_markov_regime(series)+ transition = result["transition_matrix"]++ assert transition[0][0] > transition[1][1]+ assert result["expected_durations"][0] > result["expected_durations"][1]+++def test_markov_expected_durations_track_the_true_segment_lengths():+ series, _ = _two_regime_series(seed=13, calm_len=180, turbulent_len=60)+ durations = fit_markov_regime(series)["expected_durations"]++ assert durations[0] == pytest.approx(180, rel=0.5)+ assert durations[1] == pytest.approx(60, rel=0.5)+++def test_markov_identifies_the_regime_the_series_ends_in():+ # Ends in a turbulent segment.+ series, truth = _two_regime_series(seed=17, start_calm=True)+ result = fit_markov_regime(series)++ assert result["current_regime"] == int(truth[-1])+ assert result["current_regime_probability"] > 0.8+++def test_markov_smoothed_probabilities_are_a_distribution_on_the_input_index():+ series, _ = _two_regime_series(seed=19)+ result = fit_markov_regime(series)+ smoothed = result["smoothed_probabilities"]++ assert list(smoothed.index) == list(series.index)+ assert list(smoothed.columns) == ["regime_0", "regime_1"]+ assert smoothed.sum(axis=1).to_numpy() == pytest.approx(np.ones(len(series)), abs=1e-8)+++def test_markov_smoothed_probabilities_track_the_true_state():+ series, truth = _two_regime_series(seed=23)+ smoothed = fit_markov_regime(series)["smoothed_probabilities"]+ inferred = smoothed.to_numpy().argmax(axis=1)++ # Not every boundary period is classifiable, but the bulk must be.+ assert (inferred == truth).mean() > 0.9+++def test_markov_rejects_a_single_regime():+ series, _ = _two_regime_series(seed=29)+ with pytest.raises(ValueError, match="at least 2"):+ fit_markov_regime(series, n_regimes=1)+++def test_markov_rejects_a_series_too_short_to_mean_anything():+ with pytest.raises(ValueError, match="at least 50"):+ fit_markov_regime(pd.Series(np.random.default_rng(31).normal(0, 0.01, 40)))+++def test_markov_raises_an_actionable_error_when_statsmodels_is_absent():+ try:+ import statsmodels # noqa: F401+ except ImportError:+ pass+ else:+ pytest.skip("'statsmodels' is installed, so the missing-dependency path cannot be exercised")++ with pytest.raises(ImportError, match="pip install"):+ fit_markov_regime(pd.Series(np.random.default_rng(37).normal(0, 0.01, 100)))diff --git a/agent/tests/quantlib/test_var_backtest.py b/agent/tests/quantlib/test_var_backtest.pynew file mode 100644index 000000000..4d101dc10--- /dev/null+++ b/agent/tests/quantlib/test_var_backtest.py@@ -0,0 +1,332 @@+"""Tests for src.quantlib.var_backtest.++Every guard here is two-sided: a well-calibrated model must NOT be rejected and+a miscalibrated one MUST be. A one-sided guard can always be satisfied by making+the test weaker, which is exactly the failure mode these tests exist to prevent.+"""++import numpy as np+import pandas as pd+import pytest+from scipy.stats import chi2++from src.quantlib.var_backtest import (+ BASEL_SCALING_FACTORS,+ basel_traffic_light,+ christoffersen_conditional_coverage,+ christoffersen_independence,+ kupiec_pof,+ var_backtest,+ violation_indicator,+)+++# --- breach definition and sign convention ---+++def test_breach_is_loss_strictly_exceeding_var():+ returns = np.array([-0.031, -0.028, -0.019, 0.05])+ breaches = violation_indicator(returns, 0.028)+ # -0.031 breaches; -0.028 exactly equals the promised level and does not.+ assert breaches.tolist() == [True, False, False, False]+++def test_var_is_a_positive_loss_magnitude_not_a_signed_return():+ # A caller who passes a negative VaR gets an implausible breach count, not a+ # silently corrected input.+ returns = np.array([-0.01, -0.02, -0.03])+ assert violation_indicator(returns, 0.05).sum() == 0+ assert violation_indicator(returns, -0.05).sum() == 3+++def test_scalar_var_broadcasts_over_returns():+ returns = np.array([-0.05, 0.01, -0.06])+ assert violation_indicator(returns, 0.04).tolist() == [True, False, True]+++# --- alignment ---+++def test_mismatched_series_labels_are_an_error_not_a_partial_join():+ idx_a = pd.date_range("2024-01-01", periods=5, freq="D")+ idx_b = pd.date_range("2024-01-02", periods=5, freq="D")+ returns = pd.Series(np.full(5, -0.01), index=idx_a)+ var = pd.Series(np.full(5, 0.02), index=idx_b)+ with pytest.raises(ValueError, match="exactly the same labels"):+ violation_indicator(returns, var)+++def test_length_mismatch_rejected():+ with pytest.raises(ValueError, match="same length"):+ violation_indicator(np.zeros(5), np.zeros(4))+++def test_non_finite_pairs_are_dropped_and_counted():+ returns = pd.Series([-0.05, np.nan, -0.06, 0.01])+ var = pd.Series([0.02, 0.02, np.nan, 0.02])+ report = var_backtest(returns, var, confidence=0.95)+ assert report.observations == 2+ assert report.dropped_observations == 2+++def test_all_non_finite_is_an_error():+ with pytest.raises(ValueError, match="no observation"):+ violation_indicator([np.nan, np.nan], 0.02)+++# --- Kupiec unconditional coverage ---+++def test_kupiec_perfect_calibration_gives_zero_statistic():+ result = kupiec_pof(violations=10, observations=1000, confidence=0.99)+ assert result.statistic == pytest.approx(0.0, abs=1e-12)+ assert result.p_value == pytest.approx(1.0)+ assert not result.rejected+++def test_kupiec_rejects_a_model_breached_far_too_often():+ # 50 breaches where 10 were promised.+ result = kupiec_pof(violations=50, observations=1000, confidence=0.99)+ assert result.rejected+ assert result.violation_rate == pytest.approx(0.05)+ assert result.expected_violations == pytest.approx(10.0)+++def test_kupiec_rejects_a_model_that_never_breaches_when_it_should():+ # Zero breaches over 1000 days at 99% is a far too conservative model, and+ # over-conservatism is a real finding: it means capital is over-held.+ result = kupiec_pof(violations=0, observations=1000, confidence=0.99)+ assert result.rejected+ assert np.isfinite(result.statistic)+++def test_kupiec_matches_the_closed_form_likelihood_ratio():+ n, x, p = 250, 7, 0.01+ pi = x / n+ expected = -2.0 * (+ (n - x) * np.log(1 - p)+ + x * np.log(p)+ - (n - x) * np.log(1 - pi)+ - x * np.log(pi)+ )+ result = kupiec_pof(violations=x, observations=n, confidence=1 - p)+ assert result.statistic == pytest.approx(expected, rel=1e-12)+ assert result.p_value == pytest.approx(chi2.sf(expected, df=1), rel=1e-12)+++def test_kupiec_zero_and_full_breach_counts_are_finite():+ assert np.isfinite(kupiec_pof(0, 100, 0.99).statistic)+ assert np.isfinite(kupiec_pof(100, 100, 0.99).statistic)+++ "violations, observations, confidence",+ [(-1, 100, 0.99), (101, 100, 0.99), (5, 0, 0.99), (5, 100, 1.0), (5, 100, 0.0)],+)+def test_kupiec_rejects_impossible_inputs(violations, observations, confidence):+ with pytest.raises(ValueError):+ kupiec_pof(violations, observations, confidence)+++# --- Christoffersen independence ---+++def test_independence_not_rejected_when_breaches_are_independent():+ # The true null is Bernoulli draws, not a tidy pattern.+ rng = np.random.default_rng(31)+ breaches = rng.random(2000) < 0.05+ result = christoffersen_independence(breaches)+ assert result.identified+ assert not result.rejected+++def test_perfect_periodicity_is_dependence_and_is_rejected():+ # Every 10th day, exactly. The breach count is right and nothing clusters,+ # but a breach still predicts tomorrow perfectly: it says "not tomorrow".+ # Anti-clustering is dependence, and the test is supposed to catch it.+ breaches = np.zeros(500, dtype=bool)+ breaches[::10] = True+ result = christoffersen_independence(breaches)+ assert result.identified+ assert result.rejected+ assert result.prob_breach_after_breach == 0.0+ assert result.prob_breach_after_calm > 0.0+++def test_independence_rejected_when_breaches_cluster():+ # Same breach count as the scattered case, all consecutive.+ breaches = np.zeros(500, dtype=bool)+ breaches[100:150] = True+ result = christoffersen_independence(breaches)+ assert result.identified+ assert result.rejected+ assert result.prob_breach_after_breach > result.prob_breach_after_calm+++def test_clustering_is_invisible_to_kupiec_which_is_why_both_tests_exist():+ rng = np.random.default_rng(41)+ scattered = np.zeros(500, dtype=bool)+ scattered[rng.choice(500, size=50, replace=False)] = True+ clustered = np.zeros(500, dtype=bool)+ clustered[100:150] = True++ # Identical counts, so Kupiec cannot tell them apart at all.+ k_scattered = kupiec_pof(int(scattered.sum()), scattered.size, 0.90)+ k_clustered = kupiec_pof(int(clustered.sum()), clustered.size, 0.90)+ assert k_scattered.statistic == pytest.approx(k_clustered.statistic)++ # Independence separates them.+ assert not christoffersen_independence(scattered).rejected+ assert christoffersen_independence(clustered).rejected+++def test_independence_is_unidentified_with_no_breaches():+ result = christoffersen_independence(np.zeros(100, dtype=bool))+ assert not result.identified+ assert result.statistic == 0.0+ assert not result.rejected+++def test_independence_is_unidentified_when_the_only_breach_is_last():+ breaches = np.zeros(50, dtype=bool)+ breaches[-1] = True+ result = christoffersen_independence(breaches)+ assert not result.identified+ assert result.statistic == 0.0+++def test_independence_transition_counts_are_exact():+ breaches = np.array([False, True, True, False, False], dtype=bool)+ result = christoffersen_independence(breaches)+ # transitions: F->T, T->T, T->F, F->F+ assert result.transitions == (1, 1, 1, 1)+++def test_independence_needs_two_observations():+ with pytest.raises(ValueError, match="at least 2"):+ christoffersen_independence(np.array([True]))+++# --- conditional coverage ---+++def test_conditional_coverage_is_exactly_the_sum_of_its_components():+ rng = np.random.default_rng(20260806)+ breaches = rng.random(600) < 0.03+ result = christoffersen_conditional_coverage(breaches, confidence=0.99)+ assert result.statistic == pytest.approx(+ result.kupiec.statistic + result.independence.statistic, rel=1e-12+ )+ assert result.p_value == pytest.approx(chi2.sf(result.statistic, df=2), rel=1e-12)+++def test_conditional_coverage_passes_a_correctly_calibrated_model():+ rng = np.random.default_rng(7)+ breaches = rng.random(5000) < 0.01+ result = christoffersen_conditional_coverage(breaches, confidence=0.99)+ assert not result.rejected+++def test_conditional_coverage_catches_a_model_that_only_fails_on_timing():+ # Correct 10% breach rate, but delivered in one block.+ breaches = np.zeros(500, dtype=bool)+ breaches[200:250] = True+ result = christoffersen_conditional_coverage(breaches, confidence=0.90)+ assert not result.kupiec.rejected # level is right+ assert result.independence.rejected # timing is not+ assert result.rejected # joint test catches it+++# --- Basel traffic light ---+++ "violations, zone",+ [(0, "green"), (4, "green"), (5, "yellow"), (9, "yellow"), (10, "red"), (25, "red")],+)+def test_basel_zones_reproduce_the_official_250_day_table(violations, zone):+ result = basel_traffic_light(violations, observations=250, confidence=0.99)+ assert result.zone == zone++[email protected]("violations, factor", sorted(BASEL_SCALING_FACTORS.items()))+def test_basel_scaling_factors_match_the_1996_table(violations, factor):+ result = basel_traffic_light(violations, observations=250, confidence=0.99)+ assert result.scaling_factor == factor+++def test_basel_red_zone_scaling_factor_is_flat_at_four():+ for violations in (10, 15, 30):+ assert basel_traffic_light(violations, 250, 0.99).scaling_factor == 4.00+++def test_basel_scaling_factor_withheld_off_the_tabulated_basis():+ # The zone still means something at 60 days; the multiplier does not.+ result = basel_traffic_light(violations=3, observations=60, confidence=0.99)+ assert result.zone in {"green", "yellow", "red"}+ assert result.scaling_factor is None+ assert "250" in result.scaling_factor_basis++ wrong_confidence = basel_traffic_light(violations=3, observations=250, confidence=0.95)+ assert wrong_confidence.scaling_factor is None+++def test_basel_cumulative_probability_is_reported_so_the_cut_is_auditable():+ result = basel_traffic_light(violations=5, observations=250, confidence=0.99)+ assert 0.95 <= result.cumulative_probability < 0.9999+++# --- end-to-end report ---+++def test_var_backtest_end_to_end_on_a_calibrated_model():+ rng = np.random.default_rng(11)+ n = 2000+ returns = pd.Series(+ rng.normal(0.0, 0.01, n), index=pd.date_range("2018-01-01", periods=n, freq="B")+ )+ # A correctly specified parametric VaR for this generating process.+ var = 0.01 * 2.3263478740408408 # z_{0.99}+ report = var_backtest(returns, var, confidence=0.99)++ assert report.observations == n+ assert not report.conditional_coverage.rejected+ assert report.traffic_light.zone == "green"+ assert report.breach_dates is not None+ assert len(report.breach_dates) == report.violations+++def test_var_backtest_end_to_end_on_an_understated_model():+ rng = np.random.default_rng(12)+ n = 1000+ returns = pd.Series(rng.normal(0.0, 0.02, n))+ # VaR built for half the true volatility: breaches far too often.+ report = var_backtest(returns, 0.01 * 2.3263478740408408, confidence=0.99)++ assert report.kupiec.rejected+ assert report.conditional_coverage.rejected+ assert report.traffic_light.zone == "red"+++def test_var_backtest_breach_dates_are_the_actual_breach_labels():+ idx = pd.date_range("2024-01-01", periods=5, freq="D")+ returns = pd.Series([-0.10, 0.01, -0.20, 0.02, -0.005], index=idx)+ report = var_backtest(returns, 0.05, confidence=0.95)+ assert report.breach_dates == (idx[0], idx[2])+++def test_var_backtest_without_an_index_reports_no_dates():+ report = var_backtest(np.array([-0.10, 0.01, -0.20, 0.02]), 0.05, confidence=0.95)+ assert report.breach_dates is None+++def test_var_backtest_needs_two_observations():+ with pytest.raises(ValueError, match="at least 2"):+ var_backtest(np.array([-0.05]), 0.02)+++def test_time_varying_var_series_is_compared_day_by_day():+ returns = pd.Series([-0.03, -0.03, -0.03])+ var = pd.Series([0.02, 0.05, 0.02])+ report = var_backtest(returns, var, confidence=0.95)+ assert report.violations == 2diff --git a/agent/tests/quantlib/valuation/__init__.py b/agent/tests/quantlib/valuation/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/agent/tests/quantlib/valuation/test_artifact.py b/agent/tests/quantlib/valuation/test_artifact.pynew file mode 100644index 000000000..87c18d67e--- /dev/null+++ b/agent/tests/quantlib/valuation/test_artifact.py@@ -0,0 +1,932 @@+"""Tests for src.quantlib.valuation.artifact.++Structured around the six things the artifact module promises:++1. The input hash is stable under dict-key reordering and int/float/``-0.0``+ representation noise, and changes whenever any single input number changes+ (:class:`TestInputHashStability`).+2. The module never reads a clock -- checked both by grepping its own source+ (no ``datetime.now``/``time.time``) and by proving omission/naivety of+ ``generated_at`` raises rather than silently defaulting+ (:class:`TestNoHiddenClock`).+3. Every :class:`~src.quantlib.valuation.contracts.Assumption` in a result is+ captured with its ``basis``, and models that take no ``Assumption``+ objects (comps, three-statement) honestly report an empty tuple rather+ than fabricating one (:class:`TestAssumptionCapture`).+4. Two artifacts diff to the exact changed field and its numeric delta+ (:class:`TestDiff`).+5. Every xlsx export round-trips through ``openpyxl`` back to the values on+ the result object -- not just "the file exists" -- and the excluded/+ omitted/non-converged material is actually present in the workbook+ (:class:`TestDCFWorkbookExport`, :class:`TestCompsWorkbookExport`,+ :class:`TestThreeStatementWorkbookExport`).+6. The pptx summary carries the same input hash, assumptions and gap notes+ (:class:`TestSummaryDeckExport`).+"""++from __future__ import annotations++import ast+import inspect+from datetime import datetime, timedelta, timezone+from pathlib import Path++import openpyxl+import pandas as pd+import pytest+from pptx import Presentation++from src.quantlib.valuation import artifact as artifact_module+from src.quantlib.valuation.artifact import (+ AssumptionRecord,+ ModelArtifact,+ build_comps_artifact,+ build_dcf_artifact,+ build_three_statement_artifact,+ compute_input_hash,+ diff_artifacts,+ export_comps_workbook,+ export_dcf_workbook,+ export_summary_deck,+ export_three_statement_workbook,+)+from src.quantlib.valuation.comps import FlowMetricPeriods, PeerCompany, TargetCompany, run_comps+from src.quantlib.valuation.contracts import Assumption+from src.quantlib.valuation.dcf import run_dcf, sensitivity_grid+from src.quantlib.valuation.threestatement import project_three_statement++UTC = timezone.utc+FIXED_TIME = datetime(2026, 1, 15, 12, 0, 0, tzinfo=UTC)+++# ---------------------------------------------------------------------------+# Shared fixtures (self-contained -- not imported from the sibling test files)+# ---------------------------------------------------------------------------+++def _dcf_inputs() -> dict:+ """A small, valid ``run_dcf`` inputs mapping (target capital structure)."""+ return {+ "risk_free_rate": 0.04,+ "beta": 1.2,+ "equity_risk_premium": 0.05,+ "size_premium": 0.01,+ "country_risk_premium": 0.0,+ "pretax_cost_of_debt": 0.06,+ "tax_rate": 0.25,+ "ebit": [100.0, 105.0, 110.0],+ "depreciation_amortization": [20.0, 21.0, 22.0],+ "capex": [30.0, 28.0, 26.0],+ "delta_nwc": [5.0, 4.0, 3.0],+ "terminal_growth": Assumption(+ name="terminal_growth",+ value=0.03,+ basis="Long-run nominal GDP proxy for a mature-market perpetuity",+ source="analyst view",+ ),+ "exit_multiple": Assumption(+ name="exit_multiple",+ value=8.0,+ basis="Median EV/EBITDA of the comparable peer set",+ ),+ "total_debt": 200.0,+ "cash_and_equivalents": 50.0,+ "minority_interest": 10.0,+ "preferred_equity": 15.0,+ "associate_investments": 5.0,+ "diluted_shares": 100.0,+ "target_equity_weight": 0.7,+ "target_debt_weight": 0.3,+ }+++def _run_dcf_default(inputs: dict | None = None):+ return run_dcf(+ inputs if inputs is not None else _dcf_inputs(),+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+++def _build_dcf_artifact(inputs: dict | None = None, *, generated_at: datetime = FIXED_TIME):+ inputs = inputs if inputs is not None else _dcf_inputs()+ result = _run_dcf_default(inputs)+ return build_dcf_artifact(+ inputs=inputs,+ result=result,+ generated_at=generated_at,+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+++def _flow(last_full: float, *, ytd: float, prior_ytd: float, month: int = 12) -> FlowMetricPeriods:+ return FlowMetricPeriods(+ fiscal_year_end_month=month,+ last_full_fiscal_year=last_full,+ current_year_to_date=ytd,+ prior_year_to_date=prior_ytd,+ )+++def _comps_peers(*, include_excluded_peer: bool = True) -> list[PeerCompany]:+ peers = [+ PeerCompany(+ name="PEER_A",+ market_cap=1000.0,+ total_debt=200.0,+ cash_and_equivalents=100.0,+ ebitda=_flow(150.0, ytd=80.0, prior_ytd=70.0),+ ebit=_flow(100.0, ytd=55.0, prior_ytd=50.0),+ revenue=_flow(900.0, ytd=480.0, prior_ytd=420.0),+ diluted_eps=_flow(5.0, ytd=2.6, prior_ytd=2.2),+ price_per_share=54.0,+ book_value_of_equity=500.0,+ eps_basis="gaap",+ minority_interest=None,+ preferred_stock=None,+ investments_in_associates=None,+ ),+ PeerCompany(+ name="PEER_B",+ market_cap=1200.0,+ total_debt=250.0,+ cash_and_equivalents=120.0,+ ebitda=_flow(160.0, ytd=85.0, prior_ytd=75.0),+ ebit=_flow(110.0, ytd=58.0, prior_ytd=52.0),+ revenue=_flow(950.0, ytd=500.0, prior_ytd=440.0),+ diluted_eps=_flow(5.5, ytd=2.8, prior_ytd=2.4),+ price_per_share=60.0,+ book_value_of_equity=550.0,+ eps_basis="gaap",+ ),+ ]+ if include_excluded_peer:+ # Negative LTM EBITDA -> excluded from ev_ebitda's distribution.+ peers.append(+ PeerCompany(+ name="PEER_LOSSMAKER",+ market_cap=300.0,+ total_debt=400.0,+ cash_and_equivalents=20.0,+ ebitda=_flow(-50.0, ytd=-30.0, prior_ytd=-10.0),+ ebit=_flow(-60.0, ytd=-35.0, prior_ytd=-15.0),+ revenue=_flow(500.0, ytd=260.0, prior_ytd=240.0),+ diluted_eps=_flow(-1.0, ytd=-0.5, prior_ytd=-0.2),+ price_per_share=8.0,+ book_value_of_equity=90.0,+ eps_basis="gaap",+ )+ )+ return peers+++def _comps_target(*, omit_components: bool = True) -> TargetCompany:+ kwargs = dict(+ name="TARGET",+ total_debt=150.0,+ cash_and_equivalents=60.0,+ ebitda=_flow(140.0, ytd=75.0, prior_ytd=65.0),+ ebit=_flow(95.0, ytd=52.0, prior_ytd=45.0),+ revenue=_flow(850.0, ytd=460.0, prior_ytd=400.0),+ diluted_eps=_flow(4.5, ytd=2.4, prior_ytd=2.0),+ diluted_shares_outstanding=100.0,+ book_value_of_equity=420.0,+ eps_basis="gaap",+ )+ if not omit_components:+ kwargs.update(minority_interest=0.0, preferred_stock=0.0, investments_in_associates=0.0)+ return TargetCompany(**kwargs)+++def _build_comps_artifact(*, generated_at: datetime = FIXED_TIME):+ target = _comps_target()+ peers = _comps_peers()+ result = run_comps(target, peers, calendarisation_policy="ltm")+ art = build_comps_artifact(+ target=target,+ peers=peers,+ calendarisation_policy="ltm",+ result=result,+ generated_at=generated_at,+ )+ return target, peers, result, art+++def _three_statement_opening() -> dict:+ return {+ "revenue": 1_000_000.0,+ "cash": 200_000.0,+ "net_working_capital": 150_000.0,+ "ppe": 800_000.0,+ "revolver_balance": 300_000.0,+ "paid_in_capital": 500_000.0,+ "retained_earnings": 350_000.0,+ }+++def _three_statement_drivers() -> dict:+ # minimum_cash deliberately high in period 1 to force a revolver draw --+ # exercises the "declared plug" path the artifact must surface.+ return {+ "revenue_growth": [0.10, 0.08],+ "gross_margin": [0.40, 0.42],+ "opex_pct_revenue": [0.20, 0.19],+ "capex_pct_revenue": [0.05, 0.05],+ "nwc_pct_revenue": [0.15, 0.15],+ "tax_rate": [0.25, 0.25],+ "dividend_payout_ratio": [0.30, 0.30],+ "depreciation_amortization": [60_000.0, 65_000.0],+ "interest_rate": [0.06, 0.06],+ "minimum_cash": [400_000.0, 100_000.0],+ }+++def _build_three_statement_artifact(*, generated_at: datetime = FIXED_TIME):+ opening = _three_statement_opening()+ drivers = _three_statement_drivers()+ result = project_three_statement(opening, drivers)+ art = build_three_statement_artifact(+ opening=opening, drivers=drivers, result=result, generated_at=generated_at+ )+ return opening, drivers, result, art+++# ---------------------------------------------------------------------------+# 1. Input hash stability (both sides required by the task)+# ---------------------------------------------------------------------------+++class TestInputHashStability:+ def test_same_payload_hashes_identically_twice(self):+ payload = {"a": 1.0, "b": {"c": 2.0, "d": [1, 2, 3]}}+ assert compute_input_hash(payload) == compute_input_hash(payload)++ def test_hash_independent_of_dict_key_order(self):+ forward = {"total_debt": 200.0, "cash": 50.0, "tax_rate": 0.25}+ reversed_ = {"tax_rate": 0.25, "cash": 50.0, "total_debt": 200.0}+ assert compute_input_hash(forward) == compute_input_hash(reversed_)++ def test_hash_independent_of_nested_dict_key_order(self):+ forward = {"outer": {"x": 1.0, "y": 2.0}, "z": 3.0}+ reordered = {"z": 3.0, "outer": {"y": 2.0, "x": 1.0}}+ assert compute_input_hash(forward) == compute_input_hash(reordered)++ def test_hash_treats_int_and_float_as_the_same_value(self):+ assert compute_input_hash({"shares": 100}) == compute_input_hash({"shares": 100.0})++ def test_hash_collapses_negative_zero(self):+ assert compute_input_hash({"x": -0.0}) == compute_input_hash({"x": 0.0})++ @pytest.mark.parametrize(+ ("field", "changed_value"),+ [+ ("total_debt", 201.0),+ ("cash_and_equivalents", 51.0),+ ("tax_rate", 0.26),+ ("risk_free_rate", 0.041),+ ("diluted_shares", 101.0),+ ],+ )+ def test_hash_changes_when_a_single_scalar_input_changes(self, field, changed_value):+ baseline = _dcf_inputs()+ changed = _dcf_inputs()+ changed[field] = changed_value+ assert compute_input_hash(baseline) != compute_input_hash(changed)++ def test_hash_changes_when_a_sequence_entry_changes(self):+ baseline = _dcf_inputs()+ changed = _dcf_inputs()+ changed["ebit"] = [100.0, 105.0, 111.0] # last year bumped by 1.0+ assert compute_input_hash(baseline) != compute_input_hash(changed)++ def test_hash_changes_when_an_assumption_value_changes(self):+ baseline = _dcf_inputs()+ changed = _dcf_inputs()+ changed["terminal_growth"] = Assumption(+ name="terminal_growth", value=0.031, basis=baseline["terminal_growth"].basis+ )+ assert compute_input_hash(baseline) != compute_input_hash(changed)++ def test_hash_changes_when_only_an_assumption_basis_changes(self):+ baseline = _dcf_inputs()+ changed = _dcf_inputs()+ changed["terminal_growth"] = Assumption(+ name="terminal_growth", value=0.03, basis="A completely different justification"+ )+ assert compute_input_hash(baseline) != compute_input_hash(changed)++ def test_dcf_artifact_input_hash_independent_of_generated_at(self):+ """Same run, two different timestamps -> identical input_hash."""+ inputs = _dcf_inputs()+ result = _run_dcf_default(inputs)+ art_1 = build_dcf_artifact(+ inputs=inputs, result=result, generated_at=FIXED_TIME,+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ art_2 = build_dcf_artifact(+ inputs=inputs, result=result, generated_at=FIXED_TIME + timedelta(days=30),+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ assert art_1.input_hash == art_2.input_hash+ assert art_1.generated_at != art_2.generated_at+ assert art_1.model_version == art_2.model_version++ def test_dcf_artifact_input_hash_changes_when_a_config_knob_changes(self):+ """discounting_convention is not in `inputs` but materially changes the model."""+ inputs = _dcf_inputs()+ result_mid_year = run_dcf(+ inputs, capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ result_year_end = run_dcf(+ inputs, capital_structure_basis="target", discounting_convention="year_end",+ terminal_value_method="perpetuity_growth",+ )+ art_mid = build_dcf_artifact(+ inputs=inputs, result=result_mid_year, generated_at=FIXED_TIME,+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ art_year_end = build_dcf_artifact(+ inputs=inputs, result=result_year_end, generated_at=FIXED_TIME,+ capital_structure_basis="target", discounting_convention="year_end",+ terminal_value_method="perpetuity_growth",+ )+ assert art_mid.input_hash != art_year_end.input_hash++ def test_comps_and_three_statement_hashes_also_move_on_one_number(self):+ target = _comps_target()+ peers = _comps_peers()+ result = run_comps(target, peers, calendarisation_policy="ltm")+ baseline = build_comps_artifact(+ target=target, peers=peers, calendarisation_policy="ltm",+ result=result, generated_at=FIXED_TIME,+ )+ bumped_target = _comps_target()+ bumped_peers = _comps_peers()+ bumped_target = TargetCompany(+ **{**bumped_target.__dict__, "total_debt": bumped_target.total_debt + 1.0}+ )+ bumped_result = run_comps(bumped_target, bumped_peers, calendarisation_policy="ltm")+ updated = build_comps_artifact(+ target=bumped_target, peers=bumped_peers, calendarisation_policy="ltm",+ result=bumped_result, generated_at=FIXED_TIME,+ )+ assert baseline.input_hash != updated.input_hash+++# ---------------------------------------------------------------------------+# 2. No hidden clock+# ---------------------------------------------------------------------------+++class TestNoHiddenClock:+ def test_source_never_calls_datetime_now_or_time_time(self):+ """AST-based, not substring-based: the module docstring legitimately++ *mentions* ``datetime.now()`` in prose while explaining why it is+ never called, so a naive substring grep would false-positive on the+ documentation itself. This walks the actual parsed call sites.+ """+ tree = ast.parse(inspect.getsource(artifact_module))+ offending_calls = []+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):+ continue+ attr = node.func.attr+ base = node.func.value+ base_name = base.id if isinstance(base, ast.Name) else None+ if (base_name == "datetime" and attr == "now") or (base_name == "time" and attr == "time"):+ offending_calls.append(f"{base_name}.{attr}() at line {node.lineno}")+ assert offending_calls == []++ def test_missing_generated_at_is_a_typeerror_from_python_argument_binding(self):+ inputs = _dcf_inputs()+ result = _run_dcf_default(inputs)+ with pytest.raises(TypeError):+ build_dcf_artifact( # type: ignore[call-arg]+ inputs=inputs, result=result,+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )++ def test_non_datetime_generated_at_raises_typeerror(self):+ inputs = _dcf_inputs()+ result = _run_dcf_default(inputs)+ with pytest.raises(TypeError):+ build_dcf_artifact(+ inputs=inputs, result=result, generated_at="2026-01-15", # type: ignore[arg-type]+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )++ def test_naive_generated_at_raises_valueerror(self):+ inputs = _dcf_inputs()+ result = _run_dcf_default(inputs)+ with pytest.raises(ValueError):+ build_dcf_artifact(+ inputs=inputs, result=result, generated_at=datetime(2026, 1, 15),+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )++ def test_tz_aware_generated_at_is_accepted_and_preserved(self):+ art = _build_dcf_artifact(generated_at=FIXED_TIME)+ assert art.generated_at == FIXED_TIME+++# ---------------------------------------------------------------------------+# 3. Assumption capture+# ---------------------------------------------------------------------------+++class TestAssumptionCapture:+ def test_dcf_artifact_captures_both_assumptions_with_basis(self):+ art = _build_dcf_artifact()+ assert len(art.assumptions) == 2+ names = {r.assumption.name for r in art.assumptions}+ assert names == {"terminal_growth", "exit_multiple"}+ for record in art.assumptions:+ assert isinstance(record, AssumptionRecord)+ assert record.assumption.basis.strip() != ""+ assert record.path.startswith("$.terminal_value.")++ def test_dcf_artifact_assumption_values_match_the_result(self):+ art = _build_dcf_artifact()+ by_name = {r.assumption.name: r.assumption for r in art.assumptions}+ assert by_name["terminal_growth"].value == pytest.approx(0.03)+ assert by_name["exit_multiple"].value == pytest.approx(8.0)+ assert by_name["terminal_growth"].source == "analyst view"+ assert by_name["exit_multiple"].source is None++ def test_comps_artifact_has_no_assumptions(self):+ """comps.py takes no Assumption objects -- this must be an honest empty tuple."""+ _, _, _, art = _build_comps_artifact()+ assert art.assumptions == ()++ def test_three_statement_artifact_has_no_assumptions(self):+ """threestatement.py takes no Assumption objects either."""+ _, _, _, art = _build_three_statement_artifact()+ assert art.assumptions == ()+++# ---------------------------------------------------------------------------+# 3b. Exclusions / omissions surfaced on the artifact itself+# ---------------------------------------------------------------------------+++class TestGapExtraction:+ def test_comps_artifact_records_excluded_peer_and_omitted_components(self):+ _, _, result, art = _build_comps_artifact()+ joined = " | ".join(art.excluded)+ assert "PEER_LOSSMAKER" in joined+ assert "ev_ebitda" in joined+ assert "PEER_A" in joined # PEER_A omits all three optional EV-bridge items+ assert "minority_interest" in joined+ assert "target" in joined.lower() or "TARGET" in joined++ def test_three_statement_artifact_records_revolver_draw(self):+ _, _, result, art = _build_three_statement_artifact()+ joined = " | ".join(art.excluded)+ assert "revolver drew" in joined++ def test_dcf_artifact_always_notes_the_non_chosen_terminal_method(self):+ art = _build_dcf_artifact()+ joined = " | ".join(art.excluded)+ assert "exit_multiple" in joined+ assert "terminal_value_method" in joined+++# ---------------------------------------------------------------------------+# 4. Diff+# ---------------------------------------------------------------------------+++class TestDiff:+ def test_diff_across_model_names_raises(self):+ dcf_art = _build_dcf_artifact()+ _, _, _, comps_art = _build_comps_artifact()+ with pytest.raises(ValueError):+ diff_artifacts(dcf_art, comps_art)++ def test_diff_precisely_reports_a_single_changed_input_and_its_delta(self):+ baseline_inputs = _dcf_inputs()+ baseline_art = _build_dcf_artifact(baseline_inputs)++ updated_inputs = _dcf_inputs()+ updated_inputs["total_debt"] = 250.0+ updated_art = _build_dcf_artifact(updated_inputs)++ diff = diff_artifacts(baseline_art, updated_art)+ assert diff.input_hash_changed is True+ assert diff.model_version_changed is False++ by_path = {c.path: c for c in diff.changed_inputs}+ assert "$.model_inputs.total_debt" in by_path+ change = by_path["$.model_inputs.total_debt"]+ assert change.old == pytest.approx(200.0)+ assert change.new == pytest.approx(250.0)+ assert change.delta == pytest.approx(50.0)++ # Nothing else in the raw inputs should have moved.+ other_paths = [p for p in by_path if p != "$.model_inputs.total_debt"]+ assert other_paths == []++ def test_diff_reports_only_the_outputs_actually_affected_by_total_debt(self):+ baseline_inputs = _dcf_inputs()+ baseline_art = _build_dcf_artifact(baseline_inputs)++ updated_inputs = _dcf_inputs()+ updated_inputs["total_debt"] = 250.0+ updated_art = _build_dcf_artifact(updated_inputs)++ diff = diff_artifacts(baseline_art, updated_art)+ changed_paths = {c.path for c in diff.changed_outputs}++ # total_debt flows only through the net-debt bridge to equity value /+ # value per share -- enterprise value and WACC must be untouched.+ assert "$.net_debt_bridge.total_debt" in changed_paths+ assert "$.equity_value" in changed_paths+ assert "$.value_per_share" in changed_paths+ assert "$.net_debt_bridge.equity_value" in changed_paths+ assert "$.net_debt_bridge.value_per_share" in changed_paths+ assert "$.enterprise_value" not in changed_paths+ assert "$.wacc_build.wacc" not in changed_paths++ by_path = {c.path: c for c in diff.changed_outputs}+ expected_delta = -50.0 # equity_value = EV - total_debt + ... ; +50 debt -> -50 equity+ assert by_path["$.equity_value"].delta == pytest.approx(expected_delta)+ assert by_path["$.net_debt_bridge.equity_value"].delta == pytest.approx(expected_delta)++ def test_diff_of_identical_artifacts_has_no_changes(self):+ inputs = _dcf_inputs()+ art_1 = _build_dcf_artifact(inputs, generated_at=FIXED_TIME)+ art_2 = _build_dcf_artifact(inputs, generated_at=FIXED_TIME + timedelta(hours=1))+ diff = diff_artifacts(art_1, art_2)+ assert diff.changed_inputs == ()+ assert diff.changed_outputs == ()+ assert diff.input_hash_changed is False+++# ---------------------------------------------------------------------------+# 5. xlsx exports+# ---------------------------------------------------------------------------+++class TestDCFWorkbookExport:+ @pytest.fixture()+ def workbook_path(self, tmp_path: Path) -> Path:+ inputs = _dcf_inputs()+ result = _run_dcf_default(inputs)+ art = build_dcf_artifact(+ inputs=inputs, result=result, generated_at=FIXED_TIME,+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ grid = sensitivity_grid(+ result.fcff_bridge,+ wacc_values=[0.08, 0.0905, 0.10],+ growth_values=[0.02, 0.03, 0.04],+ discounting_convention="mid_year",+ total_debt=200.0, cash_and_equivalents=50.0, minority_interest=10.0,+ preferred_equity=15.0, associate_investments=5.0, diluted_shares=100.0,+ )+ out = tmp_path / "dcf.xlsx"+ export_dcf_workbook(art, out, sensitivity_grid=grid)+ return out, art, result, grid++ def test_all_five_sheets_present(self, workbook_path):+ out, *_ = workbook_path+ wb = openpyxl.load_workbook(out)+ assert set(wb.sheetnames) == {+ "FCFF Bridge", "WACC Build", "Terminal Value", "Sensitivity",+ "Assumptions & Data Quality",+ }++ def test_fcff_bridge_cells_match_result(self, workbook_path):+ out, _art, result, _grid = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["FCFF Bridge"]+ assert ws["A1"].value == "Year"+ for i, year in enumerate(result.fcff_bridge):+ row = i + 2+ assert ws.cell(row=row, column=1).value == year.year+ assert ws.cell(row=row, column=2).value == pytest.approx(year.ebit)+ assert ws.cell(row=row, column=8).value == pytest.approx(year.fcff)+ total_row = len(result.fcff_bridge) + 2+ assert ws.cell(row=total_row, column=10).value == pytest.approx(result.pv_of_explicit_fcff)++ def test_wacc_sheet_cells_match_result(self, workbook_path):+ out, _art, result, _grid = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["WACC Build"]+ values = {row[0].value: row[1].value for row in ws.iter_rows(min_row=2)}+ assert values["wacc"] == pytest.approx(result.wacc_build.wacc)+ assert values["cost_of_equity"] == pytest.approx(result.wacc_build.cost_of_equity)+ assert values["equity_weight"] == pytest.approx(0.7)++ def test_terminal_value_sheet_cells_match_result(self, workbook_path):+ out, _art, result, _grid = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Terminal Value"]+ values = {row[0].value: row[1].value for row in ws.iter_rows(min_row=2)}+ assert values["value_per_share"] == pytest.approx(result.value_per_share)+ assert values["enterprise_value"] == pytest.approx(result.enterprise_value)+ assert values["exit_multiple.basis"] == result.terminal_value.exit_multiple.basis+ assert values["growth_exceeds_gdp_ceiling"] == result.terminal_value.growth_exceeds_gdp_ceiling++ def test_sensitivity_sheet_matches_grid(self, workbook_path):+ out, _art, _result, grid = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Sensitivity"]+ # Header row: label + growth columns.+ assert ws.cell(row=1, column=1).value == "wacc \\ terminal_growth"+ for col_idx, growth in enumerate(grid.columns, start=2):+ assert ws.cell(row=1, column=col_idx).value == pytest.approx(float(growth))+ for row_idx, wacc_value in enumerate(grid.index, start=2):+ assert ws.cell(row=row_idx, column=1).value == pytest.approx(float(wacc_value))+ for col_idx, growth in enumerate(grid.columns, start=2):+ expected = grid.loc[wacc_value, growth]+ cell_value = ws.cell(row=row_idx, column=col_idx).value+ if pd.isna(expected):+ assert cell_value is None+ else:+ assert cell_value == pytest.approx(float(expected))++ def test_assumptions_and_gaps_sheet_has_hash_and_both_assumptions(self, workbook_path):+ out, art, _result, _grid = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Assumptions & Data Quality"]+ all_values = [cell.value for row in ws.iter_rows() for cell in row if cell.value is not None]+ assert art.input_hash in all_values+ assert art.model_version in all_values+ assert "terminal_growth" in all_values+ assert "exit_multiple" in all_values+ joined_text = " | ".join(str(v) for v in all_values)+ assert "Long-run nominal GDP proxy" in joined_text+++class TestCompsWorkbookExport:+ @pytest.fixture()+ def workbook_path(self, tmp_path: Path):+ target, peers, result, art = _build_comps_artifact()+ out = tmp_path / "comps.xlsx"+ export_comps_workbook(art, out)+ return out, target, peers, result, art++ def test_all_four_sheets_present(self, workbook_path):+ out, *_ = workbook_path+ wb = openpyxl.load_workbook(out)+ assert set(wb.sheetnames) == {+ "Peer Detail", "Multiple Matrix", "Implied Valuation", "Assumptions & Data Quality",+ }++ def test_peer_detail_cells_match_result(self, workbook_path):+ out, _target, _peers, result, _art = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Peer Detail"]+ header = [c.value for c in ws[1]]+ rows_by_name = {+ row[header.index("name")].value: row for row in ws.iter_rows(min_row=2)+ }+ peer_a = next(p for p in result.peer_multiples if p.name == "PEER_A")+ row = rows_by_name["PEER_A"]+ assert row[header.index("enterprise_value")].value == pytest.approx(peer_a.ev_bridge.enterprise_value)+ assert row[header.index("ev_ebitda")].value == pytest.approx(peer_a.ev_ebitda)+ lossmaker_row = rows_by_name["PEER_LOSSMAKER"]+ assert lossmaker_row[header.index("ev_ebitda")].value == "excluded"++ def test_multiple_matrix_includes_excluded_detail(self, workbook_path):+ out, _target, _peers, result, _art = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Multiple Matrix"]+ rows = list(ws.iter_rows(values_only=True))+ header_idx = next(i for i, r in enumerate(rows) if r and r[0] == "multiple")+ by_multiple = {r[0]: r for r in rows[header_idx + 1 : header_idx + 1 + len(list(result.distributions))]}+ ev_ebitda_row = by_multiple["ev_ebitda"]+ dist = result.distributions["ev_ebitda"]+ assert ev_ebitda_row[3] == pytest.approx(dist.median) # median column+ assert ev_ebitda_row[6] == len(dist.included)+ assert ev_ebitda_row[7] == len(dist.excluded)++ excluded_detail_rows = [r for r in rows if r and r[0] == "PEER_LOSSMAKER"]+ assert excluded_detail_rows, "excluded peer must appear in the Excluded detail block"+ assert any(r[1] == "ev_ebitda" for r in excluded_detail_rows)++ def test_implied_valuation_cells_match_result(self, workbook_path):+ out, _target, _peers, result, _art = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Implied Valuation"]+ rows = {r[0]: r for r in ws.iter_rows(min_row=2, values_only=True)}+ ev_ebitda_row = rows["ev_ebitda"]+ iv = result.implied_valuations["ev_ebitda"]+ assert ev_ebitda_row[2] == pytest.approx(iv.target_metric_value)+ # Columns: multiple(0), is_ev_multiple(1), target_metric_value(2),+ # then implied_ev min/p25/median/p75/max at indices 3..7.+ assert ev_ebitda_row[5] == pytest.approx(iv.implied_ev_by_quantile["median"])++ def test_assumptions_sheet_honestly_reports_no_assumptions(self, workbook_path):+ out, _target, _peers, result, art = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Assumptions & Data Quality"]+ all_values = [cell.value for row in ws.iter_rows() for cell in row if cell.value is not None]+ assert art.input_hash in all_values+ joined = " | ".join(str(v) for v in all_values)+ assert "no caller-supplied Assumption objects" in joined+ assert "PEER_LOSSMAKER" in joined+ assert "minority_interest" in joined+++class TestThreeStatementWorkbookExport:+ @pytest.fixture()+ def workbook_path(self, tmp_path: Path):+ opening, drivers, result, art = _build_three_statement_artifact()+ out = tmp_path / "three_statement.xlsx"+ export_three_statement_workbook(art, out)+ return out, opening, drivers, result, art++ def test_all_four_sheets_present(self, workbook_path):+ out, *_ = workbook_path+ wb = openpyxl.load_workbook(out)+ assert set(wb.sheetnames) == {+ "Income Statement", "Cash Flow Statement", "Balance Sheet", "Assumptions & Data Quality",+ }++ def test_income_statement_cells_match_result(self, workbook_path):+ out, _opening, _drivers, result, _art = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Income Statement"]+ for i, period in enumerate(result.periods):+ row = i + 2+ s = period.income_statement+ assert ws.cell(row=row, column=1).value == s.period+ assert ws.cell(row=row, column=2).value == pytest.approx(s.revenue)+ assert ws.cell(row=row, column=11).value == pytest.approx(s.net_income)++ def test_cash_flow_sheet_surfaces_revolver_draw_and_convergence(self, workbook_path):+ out, _opening, _drivers, result, _art = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Cash Flow Statement"]+ header = [c.value for c in ws[1]]+ draw_col = header.index("revolver_draw") + 1+ converged_col = header.index("converged") + 1+ iterations_col = header.index("iterations") + 1+ for i, period in enumerate(result.periods):+ row = i + 2+ c = period.cash_flow_statement+ assert ws.cell(row=row, column=draw_col).value == pytest.approx(c.revolver_draw)+ assert ws.cell(row=row, column=converged_col).value == period.converged+ assert ws.cell(row=row, column=iterations_col).value == period.iterations+ # Period 1's minimum_cash (400,000) forces a draw -- must be > 0 and present.+ assert ws.cell(row=2, column=draw_col).value > 0.0++ def test_balance_sheet_rows_balance_and_match_result(self, workbook_path):+ out, _opening, _drivers, result, _art = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Balance Sheet"]+ rows = list(ws.iter_rows(min_row=2, values_only=True))+ assert rows[0][0] == 0 # opening balance sheet first+ assert rows[0][1] == pytest.approx(result.opening_balance_sheet.cash)+ for row in rows:+ residual = row[-1]+ assert residual == pytest.approx(0.0, abs=1e-6)+ for i, period in enumerate(result.periods):+ row = rows[i + 1]+ assert row[1] == pytest.approx(period.balance_sheet.cash)+ assert row[4] == pytest.approx(period.balance_sheet.revolver_balance)++ def test_assumptions_sheet_reports_no_assumptions_and_revolver_note(self, workbook_path):+ out, _opening, _drivers, _result, art = workbook_path+ wb = openpyxl.load_workbook(out)+ ws = wb["Assumptions & Data Quality"]+ all_values = [cell.value for row in ws.iter_rows() for cell in row if cell.value is not None]+ assert art.input_hash in all_values+ joined = " | ".join(str(v) for v in all_values)+ assert "no caller-supplied Assumption objects" in joined+ assert "revolver drew" in joined+++# ---------------------------------------------------------------------------+# 6. pptx summary export+# ---------------------------------------------------------------------------+++def _all_text(prs: Presentation) -> str:+ chunks = []+ for slide in prs.slides:+ for shape in slide.shapes:+ if shape.has_text_frame:+ chunks.append(shape.text_frame.text)+ return "\n".join(chunks)+++class TestSummaryDeckExport:+ def test_dcf_deck_contains_value_per_share_hash_and_assumptions(self, tmp_path):+ inputs = _dcf_inputs()+ result = _run_dcf_default(inputs)+ art = build_dcf_artifact(+ inputs=inputs, result=result, generated_at=FIXED_TIME,+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ grid = sensitivity_grid(+ result.fcff_bridge, wacc_values=[0.08, 0.0905, 0.10], growth_values=[0.02, 0.03],+ discounting_convention="mid_year", total_debt=200.0, cash_and_equivalents=50.0,+ minority_interest=10.0, preferred_equity=15.0, associate_investments=5.0,+ diluted_shares=100.0,+ )+ out = tmp_path / "dcf_summary.pptx"+ export_summary_deck(art, out, sensitivity_grid=grid)++ prs = Presentation(out)+ assert len(prs.slides) == 1+ text = _all_text(prs)+ assert f"{result.value_per_share:,.4f}" in text+ assert art.input_hash in text+ assert "terminal_growth" in text+ assert "exit_multiple" in text+ assert "Sensitivity grid not supplied" not in text++ def test_dcf_deck_without_grid_says_so_explicitly(self, tmp_path):+ art = _build_dcf_artifact()+ out = tmp_path / "dcf_summary_no_grid.pptx"+ export_summary_deck(art, out)+ prs = Presentation(out)+ text = _all_text(prs)+ assert "Sensitivity grid not supplied" in text++ def test_comps_deck_reports_no_assumptions_and_exclusions(self, tmp_path):+ _, _, result, art = _build_comps_artifact()+ out = tmp_path / "comps_summary.pptx"+ export_summary_deck(art, out)+ prs = Presentation(out)+ text = _all_text(prs)+ assert "No caller-supplied Assumption objects" in text+ assert "PEER_LOSSMAKER" in text+ assert art.input_hash in text++ def test_three_statement_deck_reports_final_period_and_gaps(self, tmp_path):+ _, _, result, art = _build_three_statement_artifact()+ out = tmp_path / "three_statement_summary.pptx"+ export_summary_deck(art, out)+ prs = Presentation(out)+ text = _all_text(prs)+ last = result.periods[-1]+ assert f"{last.income_statement.net_income:,.2f}" in text+ assert "not defined for a three-statement projection" in text+ assert "revolver drew" in text+++# ---------------------------------------------------------------------------+# Construction guards+# ---------------------------------------------------------------------------+++class TestModelArtifactConstruction:+ def test_rejects_unknown_model_name(self):+ art = _build_dcf_artifact()+ with pytest.raises(ValueError):+ ModelArtifact(+ model_name="not_a_real_model",+ model_version=art.model_version,+ schema_version=art.schema_version,+ generated_at=art.generated_at,+ input_hash=art.input_hash,+ inputs=art.inputs,+ outputs=art.outputs,+ assumptions=art.assumptions,+ result=art.result,+ excluded=art.excluded,+ warnings=art.warnings,+ )++ def test_rejects_malformed_input_hash(self):+ art = _build_dcf_artifact()+ with pytest.raises(ValueError):+ ModelArtifact(+ model_name=art.model_name,+ model_version=art.model_version,+ schema_version=art.schema_version,+ generated_at=art.generated_at,+ input_hash="not-a-hash",+ inputs=art.inputs,+ outputs=art.outputs,+ assumptions=art.assumptions,+ result=art.result,+ excluded=art.excluded,+ warnings=art.warnings,+ )++ def test_result_type_mismatch_raises(self):+ inputs = _dcf_inputs()+ with pytest.raises(TypeError):+ build_dcf_artifact(+ inputs=inputs, result="not a DCFResult", generated_at=FIXED_TIME, # type: ignore[arg-type]+ capital_structure_basis="target", discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )diff --git a/agent/tests/quantlib/valuation/test_comps.py b/agent/tests/quantlib/valuation/test_comps.pynew file mode 100644index 000000000..a3e60a484--- /dev/null+++ b/agent/tests/quantlib/valuation/test_comps.py@@ -0,0 +1,778 @@+"""Tests for src.quantlib.valuation.comps.++The centerpiece is `test_full_hand_computed_example`: four peers and one+target, worked out with LITERAL ARITHMETIC EXPRESSIONS (e.g. ``1130 / 160``,+never a pre-rounded decimal typed by hand) so Python evaluates the same+formula the module's docstring states, independently of the module's own+code path. Percentiles are cross-checked against `_lin_percentile`, a ~10+line reimplementation of numpy's default linear-interpolation quantile,+written from the textbook formula rather than imported from the module under+test -- this is the repo's convention (see `test_attribution.py`) for how a+"hand computed" fixture stays hand computed instead of silently re-deriving+its own answer from the implementation.+"""++from __future__ import annotations++import pytest++from src.quantlib.valuation.comps import (+ CALENDARISATION_POLICIES,+ EPS_BASES,+ MIN_ROBUST_COMPS,+ MULTIPLE_NAMES,+ CompsResult,+ EVBridgeResult,+ ExcludedMultiple,+ FlowMetricPeriods,+ PeerCompany,+ TargetCompany,+ calendarise_metric,+ enterprise_value,+ equity_value_from_enterprise_value,+ run_comps,+)+from src.quantlib.valuation.contracts import MissingInputError, ValuationError++EXACT = 1e-9+++def _lin_percentile(values: list[float], q: float) -> float:+ """Independent reimplementation of numpy's default ("linear") percentile.++ Textbook formula: sort, take fractional index ``q * (n - 1)``, linearly+ interpolate between its floor and ceiling. Written from scratch (not+ imported from numpy or from the module under test) so the big fixture+ below is checked against ground truth, not against its own algorithm.+ """+ ordered = sorted(values)+ n = len(ordered)+ if n == 1:+ return ordered[0]+ idx = q * (n - 1)+ lo = int(idx)+ hi = min(lo + 1, n - 1)+ frac = idx - lo+ return ordered[lo] + frac * (ordered[hi] - ordered[lo])+++def _flow(+ last_full: float,+ *,+ ytd: float | None = None,+ prior_ytd: float | None = None,+ next_fy: float | None = None,+ month: int = 12,+) -> FlowMetricPeriods:+ """Small constructor to keep the isolated unit tests below readable."""+ return FlowMetricPeriods(+ fiscal_year_end_month=month,+ last_full_fiscal_year=last_full,+ current_year_to_date=ytd,+ prior_year_to_date=prior_ytd,+ next_full_fiscal_year=next_fy,+ )+++def _baseline_peer(name: str = "PEER", **overrides: object) -> PeerCompany:+ """A self-consistent, LTM-ready peer for tests that are not about the+ big hand-computed fixture (EV bridge signs, exclusion, warnings, ...).+ """+ fields: dict[str, object] = dict(+ name=name,+ market_cap=1000.0,+ total_debt=200.0,+ cash_and_equivalents=100.0,+ ebitda=_flow(150.0, ytd=80.0, prior_ytd=70.0), # LTM = 160+ ebit=_flow(100.0, ytd=55.0, prior_ytd=50.0), # LTM = 105+ revenue=_flow(900.0, ytd=480.0, prior_ytd=420.0), # LTM = 960+ diluted_eps=_flow(5.0, ytd=2.6, prior_ytd=2.2), # LTM = 5.4+ price_per_share=54.0,+ book_value_of_equity=500.0,+ eps_basis="gaap",+ )+ fields.update(overrides)+ return PeerCompany(**fields) # type: ignore[arg-type]+++def _baseline_target(name: str = "TARGET", **overrides: object) -> TargetCompany:+ fields: dict[str, object] = dict(+ name=name,+ total_debt=150.0,+ cash_and_equivalents=60.0,+ ebitda=_flow(140.0, ytd=75.0, prior_ytd=65.0), # LTM = 150+ ebit=_flow(95.0, ytd=52.0, prior_ytd=45.0), # LTM = 102+ revenue=_flow(850.0, ytd=460.0, prior_ytd=400.0), # LTM = 910+ diluted_eps=_flow(4.5, ytd=2.4, prior_ytd=2.0), # LTM = 4.9+ diluted_shares_outstanding=100.0,+ book_value_of_equity=420.0,+ eps_basis="gaap",+ )+ fields.update(overrides)+ return TargetCompany(**fields) # type: ignore[arg-type]+++# ---------------------------------------------------------------------------+# EV bridge: one test per sign.+# ---------------------------------------------------------------------------+++def test_total_debt_increases_enterprise_value():+ """Debt is assumed by an acquirer of the whole enterprise -- EV rises."""+ base = enterprise_value(market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0)+ higher_debt = enterprise_value(market_cap=1000.0, total_debt=250.0, cash_and_equivalents=100.0)+ assert higher_debt.enterprise_value == pytest.approx(base.enterprise_value + 50.0, abs=EXACT)+++def test_cash_decreases_enterprise_value():+ """Cash funds part of the purchase price -- EV falls as cash rises."""+ base = enterprise_value(market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0)+ more_cash = enterprise_value(market_cap=1000.0, total_debt=200.0, cash_and_equivalents=150.0)+ assert more_cash.enterprise_value == pytest.approx(base.enterprise_value - 50.0, abs=EXACT)+++def test_minority_interest_increases_enterprise_value():+ """Consolidated subsidiaries carry 100% of EBITDA into the parent's+ figures -- the minority holders' claim on that 100% must be in EV too."""+ base = enterprise_value(market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0)+ with_mi = enterprise_value(+ market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0, minority_interest=50.0+ )+ assert with_mi.enterprise_value == pytest.approx(base.enterprise_value + 50.0, abs=EXACT)+ assert "minority_interest" in base.omitted_components+ assert "minority_interest" not in with_mi.omitted_components+++def test_preferred_stock_increases_enterprise_value():+ """Preferred ranks senior to common -- market cap alone underprices the+ whole enterprise by the preferred claim."""+ base = enterprise_value(market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0)+ with_pref = enterprise_value(+ market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0, preferred_stock=30.0+ )+ assert with_pref.enterprise_value == pytest.approx(base.enterprise_value + 30.0, abs=EXACT)+++def test_investments_in_associates_decreases_enterprise_value():+ """An equity-method stake's revenue/EBITDA never entered the consolidated+ operating metrics -- its value must come back out of EV."""+ base = enterprise_value(market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0)+ with_assoc = enterprise_value(+ market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0, investments_in_associates=40.0+ )+ assert with_assoc.enterprise_value == pytest.approx(base.enterprise_value - 40.0, abs=EXACT)+++def test_omitted_components_are_not_silently_zeroed():+ """An unsupplied optional item is flagged by name, distinct from an+ explicit confirmed zero."""+ omitted = enterprise_value(market_cap=1000.0, total_debt=200.0, cash_and_equivalents=100.0)+ assert set(omitted.omitted_components) == {+ "minority_interest",+ "preferred_stock",+ "investments_in_associates",+ }++ explicit_zero = enterprise_value(+ market_cap=1000.0,+ total_debt=200.0,+ cash_and_equivalents=100.0,+ minority_interest=0.0,+ preferred_stock=0.0,+ investments_in_associates=0.0,+ )+ assert explicit_zero.omitted_components == ()+ # Numerically identical to the fully-omitted case (0 contributes nothing+ # either way) -- the DIFFERENCE this module guarantees is in the report,+ # not in a different number.+ assert explicit_zero.enterprise_value == pytest.approx(omitted.enterprise_value, abs=EXACT)+++def test_enterprise_value_round_trips_through_equity_value_and_back():+ """`equity_value_from_enterprise_value` is the exact inverse bridge."""+ forward = enterprise_value(+ market_cap=1000.0,+ total_debt=200.0,+ cash_and_equivalents=100.0,+ minority_interest=50.0,+ preferred_stock=30.0,+ investments_in_associates=40.0,+ )+ backward = equity_value_from_enterprise_value(+ enterprise_value=forward.enterprise_value,+ total_debt=200.0,+ cash_and_equivalents=100.0,+ minority_interest=50.0,+ preferred_stock=30.0,+ investments_in_associates=40.0,+ )+ assert backward.equity_value == pytest.approx(1000.0, abs=EXACT)+ assert backward.direction == "ev_to_equity"+ assert forward.direction == "equity_to_ev"+ assert isinstance(forward, EVBridgeResult)+ assert isinstance(backward, EVBridgeResult)+++def test_enterprise_value_missing_required_input_raises():+ with pytest.raises(MissingInputError) as excinfo:+ enterprise_value(market_cap=1000.0, total_debt=200.0, cash_and_equivalents=None) # type: ignore[arg-type]+ assert "cash_and_equivalents" in excinfo.value.missing+++# ---------------------------------------------------------------------------+# Calendarisation: LTM vs calendar-year, and why alignment matters.+# ---------------------------------------------------------------------------+++def test_ltm_formula_is_last_full_fy_plus_current_ytd_minus_prior_ytd():+ periods = _flow(150.0, ytd=80.0, prior_ytd=70.0)+ result = calendarise_metric(periods, "ltm", metric_name="ebitda", company_name="X")+ assert result.value == pytest.approx(150.0 + 80.0 - 70.0, abs=EXACT)+ assert result.weights is None+++def test_ltm_policy_is_invariant_to_fiscal_year_end_month():+ """LTM needs no month-weighting: it always trails 12 months from the+ 'as of' date the YTD figures were cut at, whatever the fiscal calendar."""+ june_fye = _flow(150.0, ytd=80.0, prior_ytd=70.0, month=6)+ march_fye = _flow(150.0, ytd=80.0, prior_ytd=70.0, month=3)+ a = calendarise_metric(june_fye, "ltm", metric_name="ebitda", company_name="X")+ b = calendarise_metric(march_fye, "ltm", metric_name="ebitda", company_name="Y")+ assert a.value == pytest.approx(b.value, abs=EXACT)+++def test_calendar_year_december_fye_uses_full_weight_on_last_full_year():+ periods = _flow(1200.0, month=12)+ result = calendarise_metric(periods, "calendar_year", metric_name="revenue", company_name="X")+ assert result.value == pytest.approx(1200.0, abs=EXACT)+ assert result.weights == pytest.approx((1.0, 0.0), abs=EXACT)+++def test_fiscal_calendar_alignment_changes_the_comparison():+ """Requirement 4: a June-FYE company and a December-FYE company give a+ materially different conclusion unaligned vs aligned to calendar year.++ Company X: December FYE, last full fiscal year (= calendar year) revenue+ 1200.+ Company Y: June FYE. Fiscal year ending June (the 'early' half of the+ blend) = 900; fiscal year ending the following June (the 'late' half) =+ 1100. Calendar year revenue, assuming even monthly spread within each+ fiscal year (this module's documented convention): the first six months+ of the calendar year come from the FY ending in June of that year, the+ last six months from the FY ending the following June:++ calendar_year(Y) = 0.5 * 900 + 0.5 * 1100 = 1000+ """+ x = _flow(1200.0, month=12)+ y = _flow(900.0, next_fy=1100.0, month=6)++ x_aligned = calendarise_metric(x, "calendar_year", metric_name="revenue", company_name="X")+ y_aligned = calendarise_metric(y, "calendar_year", metric_name="revenue", company_name="Y")++ assert y_aligned.value == pytest.approx(0.5 * 900.0 + 0.5 * 1100.0, abs=EXACT)+ assert y_aligned.weights == pytest.approx((0.5, 0.5), abs=EXACT)++ # Unaligned (naive) comparison: Y's raw 'last full fiscal year' (a period+ # that ended six months before X's) against X's calendar-year figure.+ naive_ratio = y.last_full_fiscal_year / x.last_full_fiscal_year # 900 / 1200 = 0.75+ aligned_ratio = y_aligned.value / x_aligned.value # 1000 / 1200 = 0.8333...++ assert naive_ratio == pytest.approx(0.75, abs=EXACT)+ assert aligned_ratio == pytest.approx(1000.0 / 1200.0, abs=EXACT)+ # The two conclusions are materially different -- alignment is not a+ # rounding nicety here, it changes which company looks bigger relative+ # to the other by several points.+ assert abs(aligned_ratio - naive_ratio) > 0.05+++def test_calendar_year_policy_missing_next_fiscal_year_raises():+ """A non-December FYE company that only supplied LTM-shaped fields+ (no `next_full_fiscal_year`) cannot be calendar-year aligned -- this is+ the 'do not mix conventions' rule enforced as MissingInputError rather+ than a silently partial calendarisation."""+ ltm_only = _flow(900.0, ytd=500.0, prior_ytd=430.0, month=6)+ with pytest.raises(MissingInputError) as excinfo:+ calendarise_metric(ltm_only, "calendar_year", metric_name="revenue", company_name="Y")+ assert "next_full_fiscal_year" in excinfo.value.missing+++def test_ltm_policy_missing_ytd_fields_raises():+ calendar_year_only = _flow(900.0, next_fy=1100.0, month=6)+ with pytest.raises(MissingInputError) as excinfo:+ calendarise_metric(calendar_year_only, "ltm", metric_name="revenue", company_name="Y")+ assert "current_year_to_date" in excinfo.value.missing+ assert "prior_year_to_date" in excinfo.value.missing+++def test_unknown_calendarisation_policy_raises():+ with pytest.raises(ValuationError):+ calendarise_metric(_flow(100.0), "quarterly", metric_name="revenue", company_name="X")+++def test_fiscal_year_end_month_out_of_range_raises():+ with pytest.raises(ValuationError):+ FlowMetricPeriods(fiscal_year_end_month=13, last_full_fiscal_year=100.0)+++# ---------------------------------------------------------------------------+# Multiple exclusion: negative/zero denominators are dropped, not computed.+# ---------------------------------------------------------------------------+++def test_negative_ebitda_peer_is_excluded_from_ev_ebitda_and_reported():+ negative_ebitda_peer = _baseline_peer(+ name="LOSSCO", ebitda=_flow(-30.0, ytd=-10.0, prior_ytd=5.0) # LTM = -45+ )+ healthy_peer = _baseline_peer(name="HEALTHY")+ target = _baseline_target()++ result = run_comps(target, [negative_ebitda_peer, healthy_peer], calendarisation_policy="ltm")++ ev_ebitda_dist = result.distributions["ev_ebitda"]+ assert "LOSSCO" not in ev_ebitda_dist.included+ assert "HEALTHY" in ev_ebitda_dist.included+ assert len(ev_ebitda_dist.excluded) == 1+ excluded = ev_ebitda_dist.excluded[0]+ assert isinstance(excluded, ExcludedMultiple)+ assert excluded.peer_name == "LOSSCO"+ assert excluded.multiple_name == "ev_ebitda"+ assert excluded.denominator_value == pytest.approx(-45.0, abs=EXACT)++ # The excluded peer's own multiple is None, not a negative number.+ peer_multiples_by_name = {pm.name: pm for pm in result.peer_multiples}+ assert peer_multiples_by_name["LOSSCO"].ev_ebitda is None++ # With only one included peer, the median IS that peer's own multiple --+ # LOSSCO's -45x never entered the calculation.+ assert ev_ebitda_dist.median == pytest.approx(+ peer_multiples_by_name["HEALTHY"].ev_ebitda, abs=EXACT+ )+++def test_zero_ebitda_denominator_is_also_excluded():+ zero_ebitda_peer = _baseline_peer(name="FLAT", ebitda=_flow(0.0, ytd=0.0, prior_ytd=0.0))+ healthy_peer = _baseline_peer(name="HEALTHY")+ result = run_comps(_baseline_target(), [zero_ebitda_peer, healthy_peer], calendarisation_policy="ltm")+ assert "FLAT" not in result.distributions["ev_ebitda"].included+++def test_all_peers_excluded_from_a_multiple_yields_no_statistics_and_a_warning():+ """Boundary: every peer excluded from one multiple. The run still+ succeeds; that multiple's distribution and implied valuation are simply+ empty/None, with a warning explaining why."""+ peer_1 = _baseline_peer(name="A", ebitda=_flow(-10.0, ytd=-5.0, prior_ytd=2.0))+ peer_2 = _baseline_peer(name="B", ebitda=_flow(-20.0, ytd=-8.0, prior_ytd=1.0))+ result = run_comps(_baseline_target(), [peer_1, peer_2], calendarisation_policy="ltm")++ dist = result.distributions["ev_ebitda"]+ assert dist.included == {}+ assert len(dist.excluded) == 2+ assert dist.minimum is None+ assert dist.median is None+ assert dist.warning is not None and "excluded" in dist.warning++ implied = result.implied_valuations["ev_ebitda"]+ assert implied.implied_ev_by_quantile is None+ assert implied.implied_equity_value_by_quantile is None+ assert implied.warning == dist.warning+ assert dist.warning in result.warnings+++# ---------------------------------------------------------------------------+# Small-sample warning.+# ---------------------------------------------------------------------------+++def test_fewer_than_min_robust_comps_peers_triggers_warning():+ peers = [_baseline_peer(name="A"), _baseline_peer(name="B")]+ assert len(peers) < MIN_ROBUST_COMPS+ result = run_comps(_baseline_target(), peers, calendarisation_policy="ltm")+ assert any("only 2 peer(s) supplied" in w for w in result.warnings)+ for name in MULTIPLE_NAMES:+ assert result.distributions[name].warning is not None+++def test_three_or_more_peers_does_not_trigger_the_sample_size_warning():+ peers = [_baseline_peer(name=n) for n in ("A", "B", "C")]+ result = run_comps(_baseline_target(), peers, calendarisation_policy="ltm")+ assert not any("peer(s) supplied" in w for w in result.warnings)+++# ---------------------------------------------------------------------------+# Structural validation.+# ---------------------------------------------------------------------------+++def test_empty_peer_list_raises_missing_input_error():+ with pytest.raises(MissingInputError) as excinfo:+ run_comps(_baseline_target(), [], calendarisation_policy="ltm")+ assert "peers" in excinfo.value.missing+++def test_duplicate_peer_names_raise():+ peers = [_baseline_peer(name="DUP"), _baseline_peer(name="DUP")]+ with pytest.raises(ValuationError):+ run_comps(_baseline_target(), peers, calendarisation_policy="ltm")+++def test_mixed_eps_basis_across_peers_raises():+ peers = [_baseline_peer(name="A", eps_basis="gaap"), _baseline_peer(name="B", eps_basis="adjusted")]+ with pytest.raises(ValuationError):+ run_comps(_baseline_target(), peers, calendarisation_policy="ltm")+++def test_target_eps_basis_must_match_peers():+ peers = [_baseline_peer(name="A", eps_basis="gaap"), _baseline_peer(name="B", eps_basis="gaap")]+ target = _baseline_target(eps_basis="adjusted")+ with pytest.raises(ValuationError):+ run_comps(target, peers, calendarisation_policy="ltm")+++def test_unknown_eps_basis_rejected_at_construction():+ with pytest.raises(ValuationError):+ _baseline_peer(name="A", eps_basis="non_gaap")+++def test_unknown_calendarisation_policy_in_run_comps_raises():+ peers = [_baseline_peer(name="A"), _baseline_peer(name="B"), _baseline_peer(name="C")]+ with pytest.raises(ValuationError):+ run_comps(_baseline_target(), peers, calendarisation_policy="quarterly")+++def test_blank_company_name_rejected():+ with pytest.raises(ValuationError):+ _baseline_peer(name=" ")+++def test_non_positive_diluted_shares_outstanding_rejected():+ with pytest.raises(ValuationError):+ _baseline_target(diluted_shares_outstanding=0.0)+ with pytest.raises(ValuationError):+ _baseline_target(diluted_shares_outstanding=-10.0)+++def test_result_records_which_calendarisation_policy_and_eps_basis_were_used():+ peers = [_baseline_peer(name="A"), _baseline_peer(name="B"), _baseline_peer(name="C")]+ result = run_comps(_baseline_target(), peers, calendarisation_policy="calendar_year")+ assert result.calendarisation_policy == "calendar_year"+ assert result.eps_basis == "gaap"+ assert result.calendarisation_policy in CALENDARISATION_POLICIES+ assert result.eps_basis in EPS_BASES+ assert isinstance(result, CompsResult)+++# ---------------------------------------------------------------------------+# Boundary cases named explicitly in the spec.+# ---------------------------------------------------------------------------+++def test_zero_market_cap_peer_is_excluded_and_reported():+ """A zero market cap is not a cheap company, it is missing data.++ Under the two-sided rule (2026-08-06) a non-positive NUMERATOR is excluded+ just like a non-positive denominator: a 0.0x P/B dragged into a median+ distorts it exactly as much as a negative multiple would. The exclusion is+ reported with reason='non_positive_numerator' rather than silently dropped.+ """+ zero_cap_peer = _baseline_peer(name="ZERO", market_cap=0.0)+ result = run_comps(+ _baseline_target(), [zero_cap_peer, _baseline_peer(name="B"), _baseline_peer(name="C")],+ calendarisation_policy="ltm",+ )+ peer_multiples_by_name = {pm.name: pm for pm in result.peer_multiples}+ assert peer_multiples_by_name["ZERO"].pb is None+ assert "ZERO" not in result.distributions["pb"].included++ reasons = {+ (e.peer_name, e.multiple_name): e.reason+ for e in peer_multiples_by_name["ZERO"].exclusions+ }+ assert reasons[("ZERO", "pb")] == "non_positive_numerator"+++def test_a_net_cash_peer_with_negative_ev_is_excluded_not_averaged_in():+ """The gap the old one-sided rule left open.++ A net-cash-rich peer can carry a negative enterprise value with perfectly+ healthy EBITDA. EV/EBITDA = -3.2x is not a valuation multiple, and letting+ it into the median pulls the whole comparable range toward a number no peer+ trades at.+ """+ # Cash far exceeding market cap plus debt drives EV negative.+ net_cash_peer = _baseline_peer(name="NETCASH", market_cap=100.0, cash_and_equivalents=10_000.0)+ result = run_comps(+ _baseline_target(),+ [net_cash_peer, _baseline_peer(name="B"), _baseline_peer(name="C")],+ calendarisation_policy="ltm",+ )+ by_name = {pm.name: pm for pm in result.peer_multiples}+ assert by_name["NETCASH"].ev_bridge.enterprise_value < 0++ assert by_name["NETCASH"].ev_ebitda is None+ assert "NETCASH" not in result.distributions["ev_ebitda"].included+ assert result.distributions["ev_ebitda"].median > 0+++def test_target_negative_metric_produces_negative_implied_value_without_raising():+ """A target with negative LTM EPS produces a negative implied equity+ value via P/E -- economically odd, but the module does not fabricate an+ exclusion rule the spec does not state; it reports what falls out."""+ peers = [_baseline_peer(name="A"), _baseline_peer(name="B"), _baseline_peer(name="C")]+ losing_target = _baseline_target(diluted_eps=_flow(-2.0, ytd=-1.0, prior_ytd=0.5)) # LTM = -3.5+ result = run_comps(losing_target, peers, calendarisation_policy="ltm")++ implied = result.implied_valuations["pe"]+ assert implied.target_metric_value == pytest.approx(-3.5 * 100.0, abs=EXACT)+ assert implied.implied_equity_value_by_quantile["median"] == pytest.approx(+ result.distributions["pe"].median * implied.target_metric_value, abs=EXACT+ )+ assert implied.implied_equity_value_by_quantile["median"] < 0.0+++# ---------------------------------------------------------------------------+# The full hand-computed example.+# ---------------------------------------------------------------------------+++def test_full_hand_computed_example():+ """Four peers, one target, LTM policy. Every EV, every calendarised+ metric, every multiple, every distribution quantile and every implied+ valuation is asserted against a literal arithmetic expression built from+ the formulas stated in the module docstring -- never a value read back+ from the module under test.+ """+ # --- Peer AAA -----------------------------------------------------+ ev_a = 1000.0 + 200.0 - 100.0 + 50.0 + 0.0 - 20.0 # market_cap + debt - cash + MI + pref - assoc+ ebitda_a = 150.0 + 80.0 - 70.0+ ebit_a = 100.0 + 55.0 - 50.0+ revenue_a = 900.0 + 480.0 - 420.0+ eps_a = 5.0 + 2.6 - 2.2+ peer_a = PeerCompany(+ name="AAA",+ market_cap=1000.0,+ total_debt=200.0,+ cash_and_equivalents=100.0,+ minority_interest=50.0,+ preferred_stock=0.0,+ investments_in_associates=20.0,+ ebitda=_flow(150.0, ytd=80.0, prior_ytd=70.0),+ ebit=_flow(100.0, ytd=55.0, prior_ytd=50.0),+ revenue=_flow(900.0, ytd=480.0, prior_ytd=420.0),+ diluted_eps=_flow(5.0, ytd=2.6, prior_ytd=2.2),+ price_per_share=55.0,+ book_value_of_equity=520.0,+ eps_basis="gaap",+ )++ # --- Peer BBB -----------------------------------------------------+ ev_b = 1500.0 + 300.0 - 150.0 + 0.0 + 0.0 - 0.0+ ebitda_b = 200.0 + 110.0 - 90.0+ ebit_b = 140.0 + 75.0 - 65.0+ revenue_b = 1200.0 + 650.0 - 560.0+ eps_b = 6.0 + 3.2 - 2.8+ peer_b = PeerCompany(+ name="BBB",+ market_cap=1500.0,+ total_debt=300.0,+ cash_and_equivalents=150.0,+ minority_interest=0.0,+ preferred_stock=0.0,+ investments_in_associates=0.0,+ ebitda=_flow(200.0, ytd=110.0, prior_ytd=90.0),+ ebit=_flow(140.0, ytd=75.0, prior_ytd=65.0),+ revenue=_flow(1200.0, ytd=650.0, prior_ytd=560.0),+ diluted_eps=_flow(6.0, ytd=3.2, prior_ytd=2.8),+ price_per_share=67.0,+ book_value_of_equity=740.0,+ eps_basis="gaap",+ )++ # --- Peer CCC (negative LTM EBITDA -> excluded from ev_ebitda only) -+ ev_c = 800.0 + 250.0 - 50.0+ ebitda_c = -30.0 + (-10.0) - 5.0 # = -45, negative+ ebit_c = 90.0 + 48.0 - 40.0+ revenue_c = 700.0 + 380.0 - 320.0+ eps_c = 4.0 + 2.0 - 1.6+ peer_c = PeerCompany(+ name="CCC",+ market_cap=800.0,+ total_debt=250.0,+ cash_and_equivalents=50.0,+ minority_interest=0.0,+ preferred_stock=0.0,+ investments_in_associates=0.0,+ ebitda=_flow(-30.0, ytd=-10.0, prior_ytd=5.0),+ ebit=_flow(90.0, ytd=48.0, prior_ytd=40.0),+ revenue=_flow(700.0, ytd=380.0, prior_ytd=320.0),+ diluted_eps=_flow(4.0, ytd=2.0, prior_ytd=1.6),+ price_per_share=42.0,+ book_value_of_equity=410.0,+ eps_basis="gaap",+ )+ assert ebitda_c < 0.0++ # --- Peer DDD -------------------------------------------------------+ ev_d = 1200.0 + 180.0 - 80.0+ ebitda_d = 170.0 + 90.0 - 75.0+ ebit_d = 120.0 + 65.0 - 55.0+ revenue_d = 1000.0 + 540.0 - 460.0+ eps_d = 5.5 + 2.9 - 2.4+ peer_d = PeerCompany(+ name="DDD",+ market_cap=1200.0,+ total_debt=180.0,+ cash_and_equivalents=80.0,+ minority_interest=0.0,+ preferred_stock=0.0,+ investments_in_associates=0.0,+ ebitda=_flow(170.0, ytd=90.0, prior_ytd=75.0),+ ebit=_flow(120.0, ytd=65.0, prior_ytd=55.0),+ revenue=_flow(1000.0, ytd=540.0, prior_ytd=460.0),+ diluted_eps=_flow(5.5, ytd=2.9, prior_ytd=2.4),+ price_per_share=58.0,+ book_value_of_equity=590.0,+ eps_basis="gaap",+ )++ # --- Target TGT -------------------------------------------------------+ ebitda_t = 140.0 + 75.0 - 65.0+ ebit_t = 95.0 + 52.0 - 45.0+ revenue_t = 850.0 + 460.0 - 400.0+ eps_t = 4.5 + 2.4 - 2.0+ shares_t = 100.0+ net_income_t = eps_t * shares_t+ bridge_delta_t = 150.0 - 60.0 + 10.0 + 0.0 - 5.0 # debt - cash + MI + pref - assoc+ target = TargetCompany(+ name="TGT",+ total_debt=150.0,+ cash_and_equivalents=60.0,+ minority_interest=10.0,+ preferred_stock=0.0,+ investments_in_associates=5.0,+ ebitda=_flow(140.0, ytd=75.0, prior_ytd=65.0),+ ebit=_flow(95.0, ytd=52.0, prior_ytd=45.0),+ revenue=_flow(850.0, ytd=460.0, prior_ytd=400.0),+ diluted_eps=_flow(4.5, ytd=2.4, prior_ytd=2.0),+ diluted_shares_outstanding=shares_t,+ book_value_of_equity=420.0,+ eps_basis="gaap",+ )++ result = run_comps(target, [peer_a, peer_b, peer_c, peer_d], calendarisation_policy="ltm")+ assert result.calendarisation_policy == "ltm"+ assert len(result.peer_multiples) == 4++ # --- Per-peer EV bridge and calendarised metrics --------------------+ by_name = {pm.name: pm for pm in result.peer_multiples}+ assert by_name["AAA"].ev_bridge.enterprise_value == pytest.approx(ev_a, abs=EXACT)+ assert by_name["BBB"].ev_bridge.enterprise_value == pytest.approx(ev_b, abs=EXACT)+ assert by_name["CCC"].ev_bridge.enterprise_value == pytest.approx(ev_c, abs=EXACT)+ assert by_name["DDD"].ev_bridge.enterprise_value == pytest.approx(ev_d, abs=EXACT)++ assert by_name["AAA"].calendarised_ebitda.value == pytest.approx(ebitda_a, abs=EXACT)+ assert by_name["AAA"].calendarised_ebit.value == pytest.approx(ebit_a, abs=EXACT)+ assert by_name["AAA"].calendarised_revenue.value == pytest.approx(revenue_a, abs=EXACT)+ assert by_name["AAA"].calendarised_diluted_eps.value == pytest.approx(eps_a, abs=EXACT)++ # --- Per-peer multiples ------------------------------------------------+ assert by_name["AAA"].ev_ebitda == pytest.approx(ev_a / ebitda_a, abs=EXACT)+ assert by_name["AAA"].ev_ebit == pytest.approx(ev_a / ebit_a, abs=EXACT)+ assert by_name["AAA"].ev_sales == pytest.approx(ev_a / revenue_a, abs=EXACT)+ assert by_name["AAA"].pe == pytest.approx(55.0 / eps_a, abs=EXACT)+ assert by_name["AAA"].pb == pytest.approx(1000.0 / 520.0, abs=EXACT)++ assert by_name["BBB"].ev_ebitda == pytest.approx(ev_b / ebitda_b, abs=EXACT)+ assert by_name["BBB"].ev_ebit == pytest.approx(ev_b / ebit_b, abs=EXACT)+ assert by_name["BBB"].ev_sales == pytest.approx(ev_b / revenue_b, abs=EXACT)+ assert by_name["BBB"].pe == pytest.approx(67.0 / eps_b, abs=EXACT)+ assert by_name["BBB"].pb == pytest.approx(1500.0 / 740.0, abs=EXACT)++ # CCC: EBITDA negative -> ev_ebitda excluded (None); everything else computed.+ assert by_name["CCC"].ev_ebitda is None+ assert len(by_name["CCC"].exclusions) == 1+ assert by_name["CCC"].exclusions[0].multiple_name == "ev_ebitda"+ assert by_name["CCC"].exclusions[0].denominator_value == pytest.approx(ebitda_c, abs=EXACT)+ assert by_name["CCC"].ev_ebit == pytest.approx(ev_c / ebit_c, abs=EXACT)+ assert by_name["CCC"].ev_sales == pytest.approx(ev_c / revenue_c, abs=EXACT)+ assert by_name["CCC"].pe == pytest.approx(42.0 / eps_c, abs=EXACT)+ assert by_name["CCC"].pb == pytest.approx(800.0 / 410.0, abs=EXACT)++ assert by_name["DDD"].ev_ebitda == pytest.approx(ev_d / ebitda_d, abs=EXACT)+ assert by_name["DDD"].ev_ebit == pytest.approx(ev_d / ebit_d, abs=EXACT)+ assert by_name["DDD"].ev_sales == pytest.approx(ev_d / revenue_d, abs=EXACT)+ assert by_name["DDD"].pe == pytest.approx(58.0 / eps_d, abs=EXACT)+ assert by_name["DDD"].pb == pytest.approx(1200.0 / 590.0, abs=EXACT)++ # --- Distributions -------------------------------------------------+ ev_ebitda_values = [ev_a / ebitda_a, ev_b / ebitda_b, ev_d / ebitda_d] # CCC excluded+ ev_ebit_values = [ev_a / ebit_a, ev_b / ebit_b, ev_c / ebit_c, ev_d / ebit_d]+ ev_sales_values = [ev_a / revenue_a, ev_b / revenue_b, ev_c / revenue_c, ev_d / revenue_d]+ pe_values = [55.0 / eps_a, 67.0 / eps_b, 42.0 / eps_c, 58.0 / eps_d]+ pb_values = [1000.0 / 520.0, 1500.0 / 740.0, 800.0 / 410.0, 1200.0 / 590.0]++ expected_by_multiple = {+ "ev_ebitda": ev_ebitda_values,+ "ev_ebit": ev_ebit_values,+ "ev_sales": ev_sales_values,+ "pe": pe_values,+ "pb": pb_values,+ }++ for name, expected_values in expected_by_multiple.items():+ dist = result.distributions[name]+ assert len(dist.included) == len(expected_values)+ assert dist.minimum == pytest.approx(min(expected_values), abs=EXACT)+ assert dist.maximum == pytest.approx(max(expected_values), abs=EXACT)+ assert dist.p25 == pytest.approx(_lin_percentile(expected_values, 0.25), abs=EXACT)+ assert dist.median == pytest.approx(_lin_percentile(expected_values, 0.50), abs=EXACT)+ assert dist.p75 == pytest.approx(_lin_percentile(expected_values, 0.75), abs=EXACT)++ assert result.distributions["ev_ebitda"].median == pytest.approx(ev_a / ebitda_a, abs=EXACT)+ assert len(result.distributions["ev_ebitda"].excluded) == 1+ assert result.distributions["ev_ebitda"].warning is None # 3 included, >= MIN_ROBUST_COMPS++ # --- Implied valuations ---------------------------------------------+ for name in ("ev_ebitda", "ev_ebit", "ev_sales"):+ target_metric = {"ev_ebitda": ebitda_t, "ev_ebit": ebit_t, "ev_sales": revenue_t}[name]+ expected_values = expected_by_multiple[name]+ implied = result.implied_valuations[name]+ assert implied.target_metric_value == pytest.approx(target_metric, abs=EXACT)+ assert implied.is_ev_multiple is True++ for label, q in (("minimum", 0.0), ("p25", 0.25), ("median", 0.5), ("p75", 0.75), ("maximum", 1.0)):+ multiple = (+ min(expected_values)+ if label == "minimum"+ else max(expected_values)+ if label == "maximum"+ else _lin_percentile(expected_values, q)+ )+ expected_ev = multiple * target_metric+ assert implied.implied_ev_by_quantile[label] == pytest.approx(expected_ev, abs=EXACT)+ expected_equity = expected_ev - bridge_delta_t+ assert implied.implied_equity_value_by_quantile[label] == pytest.approx(+ expected_equity, abs=EXACT+ )++ # pe: target metric is calendarised diluted EPS * diluted shares outstanding.+ pe_implied = result.implied_valuations["pe"]+ assert pe_implied.is_ev_multiple is False+ assert pe_implied.target_metric_value == pytest.approx(net_income_t, abs=EXACT)+ assert pe_implied.implied_ev_by_quantile is None+ expected_pe_median = _lin_percentile(pe_values, 0.5) * net_income_t+ assert pe_implied.implied_equity_value_by_quantile["median"] == pytest.approx(+ expected_pe_median, abs=EXACT+ )++ # pb: target metric is book value of equity directly.+ pb_implied = result.implied_valuations["pb"]+ assert pb_implied.is_ev_multiple is False+ assert pb_implied.target_metric_value == pytest.approx(420.0, abs=EXACT)+ expected_pb_median = _lin_percentile(pb_values, 0.5) * 420.0+ assert pb_implied.implied_equity_value_by_quantile["median"] == pytest.approx(+ expected_pb_median, abs=EXACT+ )++ # No small-sample warning: 4 peers >= MIN_ROBUST_COMPS, and CCC's single+ # exclusion still leaves 3 included for ev_ebitda.+ assert result.warnings == ()diff --git a/agent/tests/quantlib/valuation/test_dcf.py b/agent/tests/quantlib/valuation/test_dcf.pynew file mode 100644index 000000000..31597cbf3--- /dev/null+++ b/agent/tests/quantlib/valuation/test_dcf.py@@ -0,0 +1,998 @@+"""Tests for src.quantlib.valuation.dcf.++Two rules the assertions here follow, matching the rest of ``tests/quantlib``.++*The main worked example is computed by hand, not by calling the module.*+:func:`test_full_worked_example_matches_hand_calculation` builds one clean+input set, and every expected intermediate (WACC, each year's NOPAT/FCFF,+both terminal values, both discount conventions, enterprise value, equity+value, value per share) is written out as a plain arithmetic expression in+this file using the same numbers -- not derived by calling ``dcf.py``. A wrong+implementation therefore cannot make the test agree with itself.++*Every input this package refuses to default is tested for refusal.* The+missing-input tests are parametrized over every key :data:`DCF_BASE_REQUIRED_FIELDS`+and the structure-basis fields name, not just the four the task called out by+name, and a second block of tests calls the lower-level builders directly with+a required keyword omitted to show that no alternate entry point can slip a+number out when an input is missing.+"""++import math++import numpy as np+import pandas as pd+import pytest++from src.quantlib.valuation.contracts import Assumption, MissingInputError, ValuationError+from src.quantlib.valuation.dcf import (+ DCF_BASE_REQUIRED_FIELDS,+ DCF_CURRENT_STRUCTURE_FIELDS,+ DCF_TARGET_STRUCTURE_FIELDS,+ DEFAULT_LONG_RUN_GDP_GROWTH_CEILING,+ DCFResult,+ DiscountedCashFlow,+ FCFFYear,+ NetDebtBridgeResult,+ TerminalValueResult,+ WACCResult,+ discount_fcff,+ equity_bridge,+ fcff_bridge,+ run_dcf,+ sensitivity_grid,+ terminal_value,+ wacc,+)++# ---------------------------------------------------------------------------+# The worked example+# ---------------------------------------------------------------------------+#+# WACC:+# cost_of_equity = 0.04 + 1.2*0.05 + 0.01 + 0.00 = 0.11+# cost_of_debt_after_tax = 0.06*(1-0.25) = 0.045+# WACC = 0.7*0.11 + 0.3*0.045 = 0.0905+#+# FCFF bridge (tax_rate=0.25 every year):+# Y1: NOPAT=100*0.75=75.00 FCFF=75.00+20-30-5 = 60.00+# Y2: NOPAT=105*0.75=78.75 FCFF=78.75+21-28-4 = 67.75+# Y3: NOPAT=110*0.75=82.50 FCFF=82.50+22-26-3 = 75.50+#+# Terminal year EBITDA = EBIT_3 + D&A_3 = 110 + 22 = 132.0+#+# Terminal value (g=0.03, exit_multiple=8.0x):+# FCFF_4 = 75.50*1.03 = 77.765+# perpetuity_TV = 77.765/(0.0905-0.03) = 1285.3719008264463+# exit_TV = 132.0*8.0 = 1056.0+# implied_multiple= 1285.3719.../132 = 9.737665915351867+# implied_growth = (1056*0.0905-75.5)/(1056+75.5) = 0.017735749005744584+#+# Mid-year discounting (t = 0.5, 1.5, 2.5):+# pv_explicit = 177.7471630647021+# terminal_discount_factor = (1.0905)**-2.5 = 0.805259440904553+# pv_of_terminal_value (perpetuity) = 1035.0578582139267+# enterprise_value = 1212.8050212786288+#+# Year-end discounting (t = 1, 2, 3):+# pv_explicit = 170.2118699631167+# terminal_discount_factor = (1.0905)**-3 = 0.7711218163967243+# pv_of_terminal_value (perpetuity) = 991.1783149105994+# enterprise_value = 1161.3901848737162+#+# Equity bridge (mid-year, perpetuity method):+# equity_value = 1212.8050212786288 - 200 + 50 - 10 - 15 + 5 = 1042.8050212786288+# value_per_share = 1042.8050212786288 / 100 = 10.428050212786289+++def base_inputs(*, structure: str = "target") -> dict:+ """Fresh copy of the worked example's ``run_dcf`` inputs mapping.++ Args:+ structure: ``"target"`` supplies ``target_equity_weight``/+ ``target_debt_weight`` (0.7/0.3); ``"current"`` supplies market+ values (700/300) that resolve to the identical weights.+ """+ inputs = {+ "risk_free_rate": 0.04,+ "beta": 1.2,+ "equity_risk_premium": 0.05,+ "size_premium": 0.01,+ "country_risk_premium": 0.0,+ "pretax_cost_of_debt": 0.06,+ "tax_rate": 0.25,+ "ebit": [100.0, 105.0, 110.0],+ "depreciation_amortization": [20.0, 21.0, 22.0],+ "capex": [30.0, 28.0, 26.0],+ "delta_nwc": [5.0, 4.0, 3.0],+ "terminal_growth": Assumption(+ name="terminal_growth",+ value=0.03,+ basis="Long-run nominal GDP proxy for a mature-market perpetuity",+ ),+ "exit_multiple": Assumption(+ name="exit_multiple",+ value=8.0,+ basis="Median EV/EBITDA of the comparable peer set",+ ),+ "total_debt": 200.0,+ "cash_and_equivalents": 50.0,+ "minority_interest": 10.0,+ "preferred_equity": 15.0,+ "associate_investments": 5.0,+ "diluted_shares": 100.0,+ }+ if structure == "target":+ inputs["target_equity_weight"] = 0.7+ inputs["target_debt_weight"] = 0.3+ else:+ inputs["market_value_of_equity"] = 700.0+ inputs["market_value_of_debt"] = 300.0+ return inputs+++# ---------------------------------------------------------------------------+# 1. The full worked example, asserted to 1e-9+# ---------------------------------------------------------------------------+++def test_full_worked_example_matches_hand_calculation():+ result = run_dcf(+ base_inputs(),+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )++ assert isinstance(result, DCFResult)++ # WACC+ assert result.wacc_build.cost_of_equity == pytest.approx(0.11, abs=1e-9)+ assert result.wacc_build.cost_of_debt_after_tax == pytest.approx(0.045, abs=1e-9)+ assert result.wacc_build.wacc == pytest.approx(0.0905, abs=1e-9)++ # FCFF bridge+ expected_nopat = [75.0, 78.75, 82.5]+ expected_fcff = [60.0, 67.75, 75.5]+ for i, year in enumerate(result.fcff_bridge):+ assert year.year == i + 1+ assert year.nopat == pytest.approx(expected_nopat[i], abs=1e-9)+ assert year.fcff == pytest.approx(expected_fcff[i], abs=1e-9)++ # Terminal value+ tv = result.terminal_value+ assert tv.terminal_year_ebitda == pytest.approx(132.0, abs=1e-9)+ assert tv.perpetuity_terminal_value == pytest.approx(1285.3719008264463, abs=1e-6)+ assert tv.exit_terminal_value == pytest.approx(1056.0, abs=1e-9)+ assert tv.implied_ev_ebitda_multiple == pytest.approx(9.737665915351867, abs=1e-6)+ assert tv.implied_perpetuity_growth == pytest.approx(0.017735749005744584, abs=1e-9)++ # Discounting + enterprise value (mid-year)+ assert result.pv_of_explicit_fcff == pytest.approx(177.7471630647021, abs=1e-6)+ assert result.terminal_discount_factor == pytest.approx(0.805259440904553, abs=1e-9)+ assert result.pv_of_terminal_value == pytest.approx(1035.0578582139267, abs=1e-6)+ assert result.enterprise_value == pytest.approx(1212.8050212786288, abs=1e-6)++ # Equity bridge + per share+ assert result.equity_value == pytest.approx(1042.8050212786288, abs=1e-6)+ assert result.value_per_share == pytest.approx(10.428050212786289, abs=1e-6)+ assert result.net_debt_bridge.diluted_shares == 100.0+++def test_worked_example_current_basis_matches_target_basis():+ """700/300 market values resolve to the same 0.7/0.3 weights as target."""+ target = run_dcf(+ base_inputs(structure="target"),+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ current = run_dcf(+ base_inputs(structure="current"),+ capital_structure_basis="current",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ assert current.wacc_build.wacc == pytest.approx(target.wacc_build.wacc, abs=1e-12)+ assert current.value_per_share == pytest.approx(target.value_per_share, abs=1e-9)+++def test_terminal_value_method_switch_changes_enterprise_value():+ perpetuity = run_dcf(+ base_inputs(),+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ exit_method = run_dcf(+ base_inputs(),+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="exit_multiple",+ )+ # Both terminal values are always computed regardless of which drives EV.+ assert perpetuity.terminal_value.exit_terminal_value == pytest.approx(1056.0, abs=1e-9)+ assert exit_method.terminal_value.perpetuity_terminal_value == pytest.approx(+ 1285.3719008264463, abs=1e-6+ )+ assert perpetuity.enterprise_value != pytest.approx(exit_method.enterprise_value)+++# ---------------------------------------------------------------------------+# 2. Missing inputs are not runnable+# ---------------------------------------------------------------------------++[email protected]("missing_key", DCF_BASE_REQUIRED_FIELDS)+def test_run_dcf_refuses_each_missing_base_field(missing_key):+ inputs = base_inputs()+ del inputs[missing_key]+ with pytest.raises(MissingInputError) as excinfo:+ run_dcf(+ inputs,+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ assert missing_key in excinfo.value.missing+ assert excinfo.value.model == "run_dcf"++[email protected]("missing_key", DCF_TARGET_STRUCTURE_FIELDS)+def test_run_dcf_refuses_each_missing_target_structure_field(missing_key):+ inputs = base_inputs(structure="target")+ del inputs[missing_key]+ with pytest.raises(MissingInputError) as excinfo:+ run_dcf(+ inputs,+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ assert missing_key in excinfo.value.missing++[email protected]("missing_key", DCF_CURRENT_STRUCTURE_FIELDS)+def test_run_dcf_refuses_each_missing_current_structure_field(missing_key):+ inputs = base_inputs(structure="current")+ del inputs[missing_key]+ with pytest.raises(MissingInputError) as excinfo:+ run_dcf(+ inputs,+ capital_structure_basis="current",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ assert missing_key in excinfo.value.missing+++ "missing_key", ["tax_rate", "beta", "equity_risk_premium", "diluted_shares"]+)+def test_run_dcf_names_the_four_headline_fields_explicitly(missing_key):+ """The task's own four examples, kept as a standalone named check."""+ inputs = base_inputs()+ del inputs[missing_key]+ with pytest.raises(MissingInputError) as excinfo:+ run_dcf(+ inputs,+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ assert excinfo.value.missing == (missing_key,)+++def test_no_path_returns_a_number_when_a_required_field_is_missing():+ """Neither the flat-mapping entry point nor any lower-level builder can+ silently substitute a value for a missing required field."""+ # run_dcf: MissingInputError, never a DCFResult.+ inputs = base_inputs()+ del inputs["tax_rate"]+ with pytest.raises(MissingInputError):+ run_dcf(+ inputs,+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )++ # wacc(): a required keyword-only argument with no default cannot be+ # omitted -- Python itself refuses the call before any arithmetic runs.+ with pytest.raises(TypeError):+ wacc( # missing tax_rate+ risk_free_rate=0.04,+ beta=1.2,+ equity_risk_premium=0.05,+ pretax_cost_of_debt=0.06,+ capital_structure_basis="target",+ target_equity_weight=0.7,+ target_debt_weight=0.3,+ )++ # wacc()'s conditional structure inputs: present basis, absent pair.+ with pytest.raises(MissingInputError) as excinfo:+ wacc(+ risk_free_rate=0.04,+ beta=1.2,+ equity_risk_premium=0.05,+ pretax_cost_of_debt=0.06,+ tax_rate=0.25,+ capital_structure_basis="current",+ )+ assert set(excinfo.value.missing) == {"market_value_of_equity", "market_value_of_debt"}++ # fcff_bridge(): missing capex.+ with pytest.raises(TypeError):+ fcff_bridge(+ ebit=[100.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0],+ delta_nwc=[5.0],+ )++ # terminal_value(): missing exit_multiple.+ with pytest.raises(TypeError):+ terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.03, "test"),+ )++ # discount_fcff(): missing wacc_rate.+ bridge = fcff_bridge(+ ebit=[100.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0],+ capex=[30.0],+ delta_nwc=[5.0],+ )+ with pytest.raises(TypeError):+ discount_fcff(bridge, discounting_convention="mid_year")++ # equity_bridge(): missing diluted_shares.+ with pytest.raises(TypeError):+ equity_bridge(+ enterprise_value=1000.0,+ total_debt=200.0,+ cash_and_equivalents=50.0,+ minority_interest=10.0,+ preferred_equity=15.0,+ associate_investments=5.0,+ )+++def test_run_dcf_refuses_bare_float_terminal_growth():+ inputs = base_inputs()+ inputs["terminal_growth"] = 0.03 # bare float, not an Assumption+ with pytest.raises(ValuationError):+ run_dcf(+ inputs,+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+++def test_run_dcf_refuses_bare_float_exit_multiple():+ inputs = base_inputs()+ inputs["exit_multiple"] = 8.0+ with pytest.raises(ValuationError):+ run_dcf(+ inputs,+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+++def test_run_dcf_refuses_assumption_with_wrong_name():+ inputs = base_inputs()+ inputs["terminal_growth"] = Assumption(name="exit_multiple", value=0.03, basis="mislabelled")+ with pytest.raises(ValuationError):+ run_dcf(+ inputs,+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+++# ---------------------------------------------------------------------------+# 3. Dual terminal value + cross-validation+# ---------------------------------------------------------------------------+++def test_implied_ev_ebitda_multiple_flags_an_unrealistic_growth_assumption():+ """g pushed close to WACC implies an absurd EV/EBITDA multiple, even+ though the Gordon-growth arithmetic itself is perfectly correct."""+ result = terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.089, "deliberately aggressive"),+ exit_multiple=Assumption("exit_multiple", 8.0, "median comp"),+ )+ assert result.implied_ev_ebitda_multiple == pytest.approx(415.25, abs=0.01)+ assert result.implied_ev_ebitda_multiple > 50.0 # an unmistakably absurd multiple+++def test_implied_perpetuity_growth_flags_an_unrealistic_exit_multiple():+ """A rich exit multiple implies a perpetuity growth rate far above the+ stated 3% growth assumption, surfacing the disagreement between methods."""+ result = terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.03, "base case"),+ exit_multiple=Assumption("exit_multiple", 40.0, "deliberately rich"),+ )+ assert result.implied_perpetuity_growth == pytest.approx(0.0751265054616749, abs=1e-9)+ assert result.implied_perpetuity_growth > 0.06 # far above the stated 3% base case+++def test_implied_perpetuity_growth_is_not_blocked_by_the_g_vs_wacc_guard():+ """The g>=WACC guard applies to the caller's stated terminal_growth+ Assumption, not to the reverse-engineered implied growth -- an implied+ growth is a diagnostic, and blocking it would hide exactly the+ unrealistic assumption the cross-check exists to surface."""+ result = terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.03, "base case"),+ exit_multiple=Assumption("exit_multiple", 60.0, "extreme"),+ )+ # No exception raised even though the implied growth sits close to WACC.+ assert result.implied_perpetuity_growth == pytest.approx(0.08020261397035833, abs=1e-9)+++def test_terminal_growth_at_or_above_wacc_raises():+ with pytest.raises(ValuationError):+ terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.0905, "equal to WACC"),+ exit_multiple=Assumption("exit_multiple", 8.0, "median comp"),+ )+ with pytest.raises(ValuationError):+ terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.10, "above WACC"),+ exit_multiple=Assumption("exit_multiple", 8.0, "median comp"),+ )+++def test_terminal_value_blows_up_near_wacc_without_silent_truncation():+ """As g approaches WACC the terminal value must explode, not be capped+ or silently truncated to a merely-large number."""+ near_far = terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.03, "base case"),+ exit_multiple=Assumption("exit_multiple", 8.0, "median comp"),+ )+ near_close = terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.0905 - 1e-6, "pathologically close to WACC"),+ exit_multiple=Assumption("exit_multiple", 8.0, "median comp"),+ )+ assert near_close.perpetuity_terminal_value > 1_000_000+ assert near_close.perpetuity_terminal_value > 100 * near_far.perpetuity_terminal_value+++def test_growth_exceeds_gdp_ceiling_is_a_flag_not_an_error():+ below = terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.03, "below the 4% ceiling"),+ exit_multiple=Assumption("exit_multiple", 8.0, "median comp"),+ )+ assert below.growth_exceeds_gdp_ceiling is False+ assert below.gdp_growth_ceiling == DEFAULT_LONG_RUN_GDP_GROWTH_CEILING++ above = terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.05, "above the 4% ceiling"),+ exit_multiple=Assumption("exit_multiple", 8.0, "median comp"),+ )+ # No error raised despite exceeding the ceiling -- a judgment call, not a refusal.+ assert above.growth_exceeds_gdp_ceiling is True+ assert above.perpetuity_terminal_value > 0.0++ custom_ceiling = terminal_value(+ final_year_fcff=75.5,+ terminal_year_ebitda=132.0,+ wacc_rate=0.0905,+ terminal_growth=Assumption("terminal_growth", 0.03, "below default ceiling"),+ exit_multiple=Assumption("exit_multiple", 8.0, "median comp"),+ gdp_growth_ceiling=0.02,+ )+ assert custom_ceiling.growth_exceeds_gdp_ceiling is True # 0.03 > custom 0.02 ceiling+++# ---------------------------------------------------------------------------+# 4. Mid-year vs year-end discounting+# ---------------------------------------------------------------------------+++def test_mid_year_discounting_is_higher_by_exactly_sqrt_1_plus_wacc():+ bridge = fcff_bridge(+ ebit=[100.0, 105.0, 110.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0, 21.0, 22.0],+ capex=[30.0, 28.0, 26.0],+ delta_nwc=[5.0, 4.0, 3.0],+ )+ wacc_rate = 0.0905+ growth = Assumption("terminal_growth", 0.03, "base case")+ multiple = Assumption("exit_multiple", 8.0, "median comp")+ tv = terminal_value(+ final_year_fcff=bridge[-1].fcff,+ terminal_year_ebitda=bridge[-1].ebit + bridge[-1].depreciation_amortization,+ wacc_rate=wacc_rate,+ terminal_growth=growth,+ exit_multiple=multiple,+ )++ def enterprise_value(convention: str) -> float:+ discounted = discount_fcff(bridge, wacc_rate=wacc_rate, discounting_convention=convention)+ pv_explicit = sum(entry.present_value for entry in discounted)+ pv_terminal = tv.perpetuity_terminal_value * discounted[-1].discount_factor+ return pv_explicit + pv_terminal++ ev_mid_year = enterprise_value("mid_year")+ ev_year_end = enterprise_value("year_end")++ assert ev_mid_year > ev_year_end+ ratio = ev_mid_year / ev_year_end+ assert ratio == pytest.approx(math.sqrt(1.0 + wacc_rate), rel=1e-9)+++def test_discount_fcff_requires_a_recognised_convention():+ bridge = fcff_bridge(+ ebit=[100.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0],+ capex=[30.0],+ delta_nwc=[5.0],+ )+ with pytest.raises(ValuationError):+ discount_fcff(bridge, wacc_rate=0.09, discounting_convention="quarterly")+++# ---------------------------------------------------------------------------+# 5. Sensitivity grid+# ---------------------------------------------------------------------------+++def test_sensitivity_grid_nan_where_growth_at_or_above_wacc():+ bridge = fcff_bridge(+ ebit=[100.0, 105.0, 110.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0, 21.0, 22.0],+ capex=[30.0, 28.0, 26.0],+ delta_nwc=[5.0, 4.0, 3.0],+ )+ grid = sensitivity_grid(+ bridge,+ wacc_values=[0.07, 0.08, 0.09, 0.10, 0.11],+ growth_values=[0.00, 0.02, 0.04, 0.08, 0.095],+ discounting_convention="mid_year",+ total_debt=200.0,+ cash_and_equivalents=50.0,+ minority_interest=10.0,+ preferred_equity=15.0,+ associate_investments=5.0,+ diluted_shares=100.0,+ )+ assert isinstance(grid, pd.DataFrame)+ assert grid.index.name == "wacc"+ assert grid.columns.name == "terminal_growth"++ # g=0.095 >= every wacc value except 0.10 and 0.11 -> NaN there.+ assert math.isnan(grid.loc[0.07, 0.095])+ assert math.isnan(grid.loc[0.08, 0.095])+ assert math.isnan(grid.loc[0.09, 0.095])+ assert not math.isnan(grid.loc[0.10, 0.095])+ assert not math.isnan(grid.loc[0.11, 0.095])++ # g=0.08 == wacc=0.08 -> NaN at the boundary too.+ assert math.isnan(grid.loc[0.08, 0.08])+ assert math.isnan(grid.loc[0.07, 0.08]) # 0.08 > 0.07+ assert not math.isnan(grid.loc[0.09, 0.08])+++def test_sensitivity_grid_matches_hand_calculation_at_one_cell():+ bridge = fcff_bridge(+ ebit=[100.0, 105.0, 110.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0, 21.0, 22.0],+ capex=[30.0, 28.0, 26.0],+ delta_nwc=[5.0, 4.0, 3.0],+ )+ grid = sensitivity_grid(+ bridge,+ wacc_values=[0.10],+ growth_values=[0.03],+ discounting_convention="mid_year",+ total_debt=200.0,+ cash_and_equivalents=50.0,+ minority_interest=10.0,+ preferred_equity=15.0,+ associate_investments=5.0,+ diluted_shares=100.0,+ )+ # Hand-computed via the same formula, independently of sensitivity_grid:+ # pv_explicit=175.42529663702476, tv=1110.9285714285713,+ # ev=1050.8210257123903, equity=880.8210257123903, vps=8.808210257123903+ assert grid.loc[0.10, 0.03] == pytest.approx(8.808210257123903, abs=1e-6)+++def test_sensitivity_grid_monotonic_decreasing_in_wacc_increasing_in_growth():+ bridge = fcff_bridge(+ ebit=[100.0, 105.0, 110.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0, 21.0, 22.0],+ capex=[30.0, 28.0, 26.0],+ delta_nwc=[5.0, 4.0, 3.0],+ )+ wacc_values = [0.07, 0.08, 0.09, 0.10, 0.11]+ growth_values = [0.00, 0.01, 0.02, 0.03, 0.04]+ grid = sensitivity_grid(+ bridge,+ wacc_values=wacc_values,+ growth_values=growth_values,+ discounting_convention="mid_year",+ total_debt=200.0,+ cash_and_equivalents=50.0,+ minority_interest=10.0,+ preferred_equity=15.0,+ associate_investments=5.0,+ diluted_shares=100.0,+ )+ values = grid.to_numpy()+ assert not np.isnan(values).any() # every g here is below every wacc++ # Strictly decreasing down each column (increasing WACC).+ for col in range(values.shape[1]):+ column = values[:, col]+ assert np.all(np.diff(column) < 0.0)++ # Strictly increasing across each row (increasing growth).+ for row in range(values.shape[0]):+ line = values[row, :]+ assert np.all(np.diff(line) > 0.0)+++def test_sensitivity_grid_requires_nonempty_axes_and_positive_shares():+ bridge = fcff_bridge(+ ebit=[100.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0],+ capex=[30.0],+ delta_nwc=[5.0],+ )+ with pytest.raises(ValuationError):+ sensitivity_grid(+ bridge,+ wacc_values=[],+ growth_values=[0.03],+ discounting_convention="mid_year",+ total_debt=0.0,+ cash_and_equivalents=0.0,+ minority_interest=0.0,+ preferred_equity=0.0,+ associate_investments=0.0,+ diluted_shares=100.0,+ )+ with pytest.raises(ValuationError):+ sensitivity_grid(+ bridge,+ wacc_values=[0.09],+ growth_values=[0.03],+ discounting_convention="mid_year",+ total_debt=0.0,+ cash_and_equivalents=0.0,+ minority_interest=0.0,+ preferred_equity=0.0,+ associate_investments=0.0,+ diluted_shares=0.0, # not positive+ )+++# ---------------------------------------------------------------------------+# 6. Net-debt bridge: one sign-direction test per line item+# ---------------------------------------------------------------------------+++def _bridge(**overrides) -> NetDebtBridgeResult:+ base = dict(+ enterprise_value=1000.0,+ total_debt=0.0,+ cash_and_equivalents=0.0,+ minority_interest=0.0,+ preferred_equity=0.0,+ associate_investments=0.0,+ diluted_shares=100.0,+ )+ base.update(overrides)+ return equity_bridge(**base)+++def test_total_debt_reduces_equity_value():+ baseline = _bridge()+ with_debt = _bridge(total_debt=120.0)+ assert with_debt.equity_value == pytest.approx(baseline.equity_value - 120.0, abs=1e-9)+++def test_cash_and_equivalents_increases_equity_value():+ baseline = _bridge()+ with_cash = _bridge(cash_and_equivalents=80.0)+ assert with_cash.equity_value == pytest.approx(baseline.equity_value + 80.0, abs=1e-9)+++def test_minority_interest_reduces_equity_value():+ baseline = _bridge()+ with_minority = _bridge(minority_interest=40.0)+ assert with_minority.equity_value == pytest.approx(baseline.equity_value - 40.0, abs=1e-9)+++def test_preferred_equity_reduces_equity_value():+ baseline = _bridge()+ with_preferred = _bridge(preferred_equity=25.0)+ assert with_preferred.equity_value == pytest.approx(baseline.equity_value - 25.0, abs=1e-9)+++def test_associate_investments_increases_equity_value():+ baseline = _bridge()+ with_associates = _bridge(associate_investments=15.0)+ assert with_associates.equity_value == pytest.approx(+ baseline.equity_value + 15.0, abs=1e-9+ )+++def test_equity_bridge_refuses_negative_magnitudes():+ for field in (+ "total_debt",+ "cash_and_equivalents",+ "minority_interest",+ "preferred_equity",+ "associate_investments",+ ):+ with pytest.raises(ValuationError):+ _bridge(**{field: -1.0})+++def test_equity_bridge_requires_positive_diluted_shares():+ with pytest.raises(ValuationError):+ _bridge(diluted_shares=0.0)+ with pytest.raises(ValuationError):+ _bridge(diluted_shares=-50.0)+++# ---------------------------------------------------------------------------+# 7. WACC guards+# ---------------------------------------------------------------------------+++def test_wacc_current_basis_zero_market_value_raises():+ with pytest.raises(ValuationError):+ wacc(+ risk_free_rate=0.04,+ beta=1.2,+ equity_risk_premium=0.05,+ pretax_cost_of_debt=0.06,+ tax_rate=0.25,+ capital_structure_basis="current",+ market_value_of_equity=0.0,+ market_value_of_debt=0.0,+ )+++def test_wacc_target_weights_must_sum_to_one():+ with pytest.raises(ValuationError):+ wacc(+ risk_free_rate=0.04,+ beta=1.2,+ equity_risk_premium=0.05,+ pretax_cost_of_debt=0.06,+ tax_rate=0.25,+ capital_structure_basis="target",+ target_equity_weight=0.7,+ target_debt_weight=0.4, # sums to 1.1+ )+++def test_wacc_target_weights_must_be_nonnegative():+ with pytest.raises(ValuationError):+ wacc(+ risk_free_rate=0.04,+ beta=1.2,+ equity_risk_premium=0.05,+ pretax_cost_of_debt=0.06,+ tax_rate=0.25,+ capital_structure_basis="target",+ target_equity_weight=1.1,+ target_debt_weight=-0.1,+ )+++def test_wacc_rejects_unknown_capital_structure_basis():+ with pytest.raises(ValuationError):+ wacc(+ risk_free_rate=0.04,+ beta=1.2,+ equity_risk_premium=0.05,+ pretax_cost_of_debt=0.06,+ tax_rate=0.25,+ capital_structure_basis="hybrid",+ )+++def test_wacc_rejects_tax_rate_outside_unit_interval():+ with pytest.raises(ValuationError):+ wacc(+ risk_free_rate=0.04,+ beta=1.2,+ equity_risk_premium=0.05,+ pretax_cost_of_debt=0.06,+ tax_rate=1.25,+ capital_structure_basis="target",+ target_equity_weight=0.7,+ target_debt_weight=0.3,+ )+++def test_wacc_optional_premiums_default_to_zero_when_absent():+ result = wacc(+ risk_free_rate=0.04,+ beta=1.2,+ equity_risk_premium=0.05,+ pretax_cost_of_debt=0.06,+ tax_rate=0.25,+ capital_structure_basis="target",+ target_equity_weight=0.7,+ target_debt_weight=0.3,+ )+ assert result.size_premium == 0.0+ assert result.country_risk_premium == 0.0+ assert result.cost_of_equity == pytest.approx(0.04 + 1.2 * 0.05, abs=1e-9)+++# ---------------------------------------------------------------------------+# 8. FCFF bridge: delta_nwc sign convention + shape guards+# ---------------------------------------------------------------------------+++def test_delta_nwc_increase_is_a_cash_outflow():+ baseline = fcff_bridge(+ ebit=[100.0], tax_rate=0.25, depreciation_amortization=[20.0], capex=[30.0],+ delta_nwc=[0.0],+ )[0]+ nwc_increase = fcff_bridge(+ ebit=[100.0], tax_rate=0.25, depreciation_amortization=[20.0], capex=[30.0],+ delta_nwc=[5.0],+ )[0]+ nwc_release = fcff_bridge(+ ebit=[100.0], tax_rate=0.25, depreciation_amortization=[20.0], capex=[30.0],+ delta_nwc=[-5.0],+ )[0]+ assert nwc_increase.fcff == pytest.approx(baseline.fcff - 5.0, abs=1e-9)+ assert nwc_release.fcff == pytest.approx(baseline.fcff + 5.0, abs=1e-9)+++def test_fcff_bridge_rejects_empty_forecast():+ with pytest.raises(ValuationError):+ fcff_bridge(+ ebit=[], tax_rate=0.25, depreciation_amortization=[], capex=[], delta_nwc=[]+ )+++def test_fcff_bridge_rejects_mismatched_lengths():+ with pytest.raises(ValuationError):+ fcff_bridge(+ ebit=[100.0, 105.0],+ tax_rate=0.25,+ depreciation_amortization=[20.0], # wrong length+ capex=[30.0, 28.0],+ delta_nwc=[5.0, 4.0],+ )+++def test_fcff_bridge_rejects_tax_rate_outside_unit_interval():+ with pytest.raises(ValuationError):+ fcff_bridge(+ ebit=[100.0], tax_rate=-0.1, depreciation_amortization=[20.0], capex=[30.0],+ delta_nwc=[5.0],+ )+++# ---------------------------------------------------------------------------+# 9. run_dcf: methodology switches are required and validated+# ---------------------------------------------------------------------------+++def test_run_dcf_rejects_unknown_capital_structure_basis():+ with pytest.raises(ValuationError):+ run_dcf(+ base_inputs(),+ capital_structure_basis="hybrid",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+++def test_run_dcf_rejects_unknown_discounting_convention():+ with pytest.raises(ValuationError):+ run_dcf(+ base_inputs(),+ capital_structure_basis="target",+ discounting_convention="quarterly",+ terminal_value_method="perpetuity_growth",+ )+++def test_run_dcf_rejects_unknown_terminal_value_method():+ with pytest.raises(ValuationError):+ run_dcf(+ base_inputs(),+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="dividend_discount",+ )+++def test_run_dcf_requires_explicit_methodology_arguments():+ """capital_structure_basis, discounting_convention and terminal_value_method+ have no defaults -- omitting any of them is a TypeError, not a silently+ chosen convention."""+ with pytest.raises(TypeError):+ run_dcf(+ base_inputs(),+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ with pytest.raises(TypeError):+ run_dcf(+ base_inputs(),+ capital_structure_basis="target",+ terminal_value_method="perpetuity_growth",+ )+ with pytest.raises(TypeError):+ run_dcf(+ base_inputs(),+ capital_structure_basis="target",+ discounting_convention="mid_year",+ )+++# ---------------------------------------------------------------------------+# 10. Dataclass repr sanity (result shape stays visible, not collapsed)+# ---------------------------------------------------------------------------+++def test_dcf_result_exposes_every_intermediate_object():+ result = run_dcf(+ base_inputs(),+ capital_structure_basis="target",+ discounting_convention="mid_year",+ terminal_value_method="perpetuity_growth",+ )+ assert isinstance(result.wacc_build, WACCResult)+ assert all(isinstance(year, FCFFYear) for year in result.fcff_bridge)+ assert all(isinstance(entry, DiscountedCashFlow) for entry in result.discounted_fcff)+ assert isinstance(result.terminal_value, TerminalValueResult)+ assert isinstance(result.net_debt_bridge, NetDebtBridgeResult)+ assert len(result.fcff_bridge) == 3+ assert len(result.discounted_fcff) == 3diff --git a/agent/tests/quantlib/valuation/test_threestatement.py b/agent/tests/quantlib/valuation/test_threestatement.pynew file mode 100644index 000000000..0de532e08--- /dev/null+++ b/agent/tests/quantlib/valuation/test_threestatement.py@@ -0,0 +1,600 @@+"""Tests for the linked three-statement projection.++The flagship test (`test_three_period_projection_matches_hand_computation`) is+the important one: it builds a three-period scenario where the revolver never+moves (`minimum_cash` is set, period by period, to exactly the cash the model+would land on with no draw or repayment), which removes the interest/revolver+circularity from the arithmetic entirely and leaves every income-statement,+cash-flow-statement and balance-sheet line as closed-form arithmetic on the+driver inputs. Every expected number below is that closed-form arithmetic,+written out the same way the model itself derives it (revenue -> gross profit+-> EBITDA -> D&A -> EBIT -> interest -> pretax -> tax -> net income, then the+cash bridge, then the balance-sheet rollforwards) -- not copied from a prior+run of the implementation. A regression in the linkage cannot be absorbed by+reusing the implementation's own reasoning.++The remaining tests each isolate one requirement that the flagship test does+not (and structurally cannot, since it is built to avoid the circularity)+exercise: the hard balance check actually raising on a genuinely unbalanced+input (not just staying quiet on a balanced one), multi-iteration convergence,+genuine divergence, the explicit revolver plug, missing-input refusal, and the+three named boundary conditions.+"""++from __future__ import annotations++import pytest++from src.quantlib.valuation.contracts import MissingInputError+from src.quantlib.valuation.threestatement import (+ MAX_CIRCULARITY_ITERATIONS,+ BalanceSheet,+ BalanceSheetError,+ ConvergenceError,+ check_balance_sheet,+ project_three_statement,+)++TOL = 1e-9+++def _assert_balances(bs: BalanceSheet) -> None:+ """Independently recompute assets vs. liabilities + equity and assert equality.++ Args:+ bs: The balance sheet to check.+ """+ assets = bs.cash + bs.net_working_capital + bs.ppe+ liab_plus_equity = bs.revolver_balance + bs.paid_in_capital + bs.retained_earnings+ assert assets == pytest.approx(liab_plus_equity, abs=TOL)+++# --------------------------------------------------------------------------+# Flagship: three-period hand-computed projection, flat (non-circular) debt.+# --------------------------------------------------------------------------++# Opening balance sheet. Assets = 200,000 + 150,000 + 800,000 = 1,150,000.+# Liabilities = 300,000. Equity must then be 850,000 = paid_in + RE, so+# RE_0 = 850,000 - 500,000 = 350,000.+CASH_0 = 200_000.0+NWC_0 = 150_000.0+PPE_0 = 800_000.0+DEBT_0 = 300_000.0+PAID_IN = 500_000.0+RE_0 = 350_000.0+REVENUE_0 = 1_000_000.0+assert CASH_0 + NWC_0 + PPE_0 == pytest.approx(DEBT_0 + PAID_IN + RE_0)++OPENING = {+ "revenue": REVENUE_0,+ "cash": CASH_0,+ "net_working_capital": NWC_0,+ "ppe": PPE_0,+ "revolver_balance": DEBT_0,+ "paid_in_capital": PAID_IN,+ "retained_earnings": RE_0,+}++# Drivers, period by period. interest_rate is 6% flat and the revolver never+# draws or repays (minimum_cash is set below to the exact break-even cash), so+# interest_1 = interest_2 = interest_3 = 0.06 * 300,000 = 18,000 throughout.+REVENUE_GROWTH = [0.10, 0.08, 0.05]+GROSS_MARGIN = [0.40, 0.42, 0.42]+OPEX_PCT = [0.20, 0.19, 0.18]+CAPEX_PCT = [0.05, 0.05, 0.04]+NWC_PCT = [0.15, 0.15, 0.14]+TAX_RATE = [0.25, 0.25, 0.25]+PAYOUT = [0.30, 0.30, 0.30]+DA = [60_000.0, 65_000.0, 68_000.0]+INTEREST_RATE = [0.06, 0.06, 0.06]++# --- Period 1 ---+REVENUE_1 = REVENUE_0 * (1.0 + REVENUE_GROWTH[0]) # 1,100,000+GROSS_PROFIT_1 = REVENUE_1 * GROSS_MARGIN[0] # 440,000+OPEX_1 = REVENUE_1 * OPEX_PCT[0] # 220,000+EBITDA_1 = GROSS_PROFIT_1 - OPEX_1 # 220,000+EBIT_1 = EBITDA_1 - DA[0] # 160,000+INTEREST_1 = INTEREST_RATE[0] * DEBT_0 # flat debt -> avg == 300,000; 18,000+PRETAX_1 = EBIT_1 - INTEREST_1 # 142,000+TAX_1 = PRETAX_1 * TAX_RATE[0] # 35,500+NI_1 = PRETAX_1 - TAX_1 # 106,500+CAPEX_1 = REVENUE_1 * CAPEX_PCT[0] # 55,000+NWC_END_1 = REVENUE_1 * NWC_PCT[0] # 165,000+D_NWC_1 = NWC_END_1 - NWC_0 # 15,000+DIV_1 = max(NI_1, 0.0) * PAYOUT[0] # 31,950+CFBF_1 = NI_1 + DA[0] - D_NWC_1 - CAPEX_1 - DIV_1 # 64,550+CASH_1 = CASH_0 + CFBF_1 # 264,550 -- also this period's minimum_cash (no draw/repay)+PPE_1 = PPE_0 + CAPEX_1 - DA[0] # 795,000+RE_1 = RE_0 + NI_1 - DIV_1 # 424,550++# --- Period 2 ---+REVENUE_2 = REVENUE_1 * (1.0 + REVENUE_GROWTH[1]) # 1,188,000+GROSS_PROFIT_2 = REVENUE_2 * GROSS_MARGIN[1] # 498,960+OPEX_2 = REVENUE_2 * OPEX_PCT[1] # 225,720+EBITDA_2 = GROSS_PROFIT_2 - OPEX_2 # 273,240+EBIT_2 = EBITDA_2 - DA[1] # 208,240+INTEREST_2 = INTEREST_RATE[1] * DEBT_0 # 18,000+PRETAX_2 = EBIT_2 - INTEREST_2 # 190,240+TAX_2 = PRETAX_2 * TAX_RATE[1] # 47,560+NI_2 = PRETAX_2 - TAX_2 # 142,680+CAPEX_2 = REVENUE_2 * CAPEX_PCT[1] # 59,400+NWC_END_2 = REVENUE_2 * NWC_PCT[1] # 178,200+D_NWC_2 = NWC_END_2 - NWC_END_1 # 13,200+DIV_2 = max(NI_2, 0.0) * PAYOUT[1] # 42,804+CFBF_2 = NI_2 + DA[1] - D_NWC_2 - CAPEX_2 - DIV_2 # 92,276+CASH_2 = CASH_1 + CFBF_2 # 356,826+PPE_2 = PPE_1 + CAPEX_2 - DA[1] # 789,400+RE_2 = RE_1 + NI_2 - DIV_2 # 524,426++# --- Period 3 ---+REVENUE_3 = REVENUE_2 * (1.0 + REVENUE_GROWTH[2]) # 1,247,400+GROSS_PROFIT_3 = REVENUE_3 * GROSS_MARGIN[2] # 523,908+OPEX_3 = REVENUE_3 * OPEX_PCT[2] # 224,532+EBITDA_3 = GROSS_PROFIT_3 - OPEX_3 # 299,376+EBIT_3 = EBITDA_3 - DA[2] # 231,376+INTEREST_3 = INTEREST_RATE[2] * DEBT_0 # 18,000+PRETAX_3 = EBIT_3 - INTEREST_3 # 213,376+TAX_3 = PRETAX_3 * TAX_RATE[2] # 53,344+NI_3 = PRETAX_3 - TAX_3 # 160,032+CAPEX_3 = REVENUE_3 * CAPEX_PCT[2] # 49,896+NWC_END_3 = REVENUE_3 * NWC_PCT[2] # 174,636+D_NWC_3 = NWC_END_3 - NWC_END_2 # -3,564 (NWC shrinks -- a source of cash)+DIV_3 = max(NI_3, 0.0) * PAYOUT[2] # 48,009.6+CFBF_3 = NI_3 + DA[2] - D_NWC_3 - CAPEX_3 - DIV_3 # 133,690.4+CASH_3 = CASH_2 + CFBF_3 # 490,516.4+PPE_3 = PPE_2 + CAPEX_3 - DA[2] # 771,296+RE_3 = RE_2 + NI_3 - DIV_3 # 636,448.4++DRIVERS = {+ "revenue_growth": REVENUE_GROWTH,+ "gross_margin": GROSS_MARGIN,+ "opex_pct_revenue": OPEX_PCT,+ "capex_pct_revenue": CAPEX_PCT,+ "nwc_pct_revenue": NWC_PCT,+ "tax_rate": TAX_RATE,+ "dividend_payout_ratio": PAYOUT,+ "depreciation_amortization": DA,+ "interest_rate": INTEREST_RATE,+ # Set to the exact break-even cash each period, so the revolver never+ # draws or repays and debt stays flat at 300,000 -- see module docstring.+ "minimum_cash": [CASH_1, CASH_2, CASH_3],+}+++def test_three_period_projection_matches_hand_computation():+ """Every IS/CF/BS line, all three periods, matches the arithmetic above exactly."""+ result = project_three_statement(OPENING, DRIVERS)+ assert len(result.periods) == 3++ p1, p2, p3 = result.periods++ # --- Period 1 income statement ---+ assert p1.income_statement.revenue == pytest.approx(REVENUE_1, abs=TOL)+ assert p1.income_statement.gross_profit == pytest.approx(GROSS_PROFIT_1, abs=TOL)+ assert p1.income_statement.opex == pytest.approx(OPEX_1, abs=TOL)+ assert p1.income_statement.ebitda == pytest.approx(EBITDA_1, abs=TOL)+ assert p1.income_statement.depreciation_amortization == pytest.approx(DA[0], abs=TOL)+ assert p1.income_statement.ebit == pytest.approx(EBIT_1, abs=TOL)+ assert p1.income_statement.interest_expense == pytest.approx(INTEREST_1, abs=TOL)+ assert p1.income_statement.pretax_income == pytest.approx(PRETAX_1, abs=TOL)+ assert p1.income_statement.tax_expense == pytest.approx(TAX_1, abs=TOL)+ assert p1.income_statement.net_income == pytest.approx(NI_1, abs=TOL)+ assert p1.income_statement.cogs == pytest.approx(REVENUE_1 - GROSS_PROFIT_1, abs=TOL)++ # --- Period 1 cash flow statement ---+ assert p1.cash_flow_statement.net_income == pytest.approx(NI_1, abs=TOL)+ assert p1.cash_flow_statement.depreciation_amortization == pytest.approx(DA[0], abs=TOL)+ assert p1.cash_flow_statement.change_in_net_working_capital == pytest.approx(D_NWC_1, abs=TOL)+ assert p1.cash_flow_statement.capex == pytest.approx(CAPEX_1, abs=TOL)+ assert p1.cash_flow_statement.dividends_paid == pytest.approx(DIV_1, abs=TOL)+ assert p1.cash_flow_statement.revolver_draw == pytest.approx(0.0, abs=TOL)+ assert p1.cash_flow_statement.revolver_repayment == pytest.approx(0.0, abs=TOL)+ assert p1.cash_flow_statement.financing_activities == pytest.approx(-DIV_1, abs=TOL)+ assert p1.cash_flow_statement.net_change_in_cash == pytest.approx(CFBF_1, abs=TOL)++ # --- Period 1 balance sheet ---+ assert p1.balance_sheet.cash == pytest.approx(CASH_1, abs=TOL)+ assert p1.balance_sheet.net_working_capital == pytest.approx(NWC_END_1, abs=TOL)+ assert p1.balance_sheet.ppe == pytest.approx(PPE_1, abs=TOL)+ assert p1.balance_sheet.revolver_balance == pytest.approx(DEBT_0, abs=TOL)+ assert p1.balance_sheet.paid_in_capital == pytest.approx(PAID_IN, abs=TOL)+ assert p1.balance_sheet.retained_earnings == pytest.approx(RE_1, abs=TOL)+ assert p1.converged is True+ _assert_balances(p1.balance_sheet)++ # --- Period 2 income statement ---+ assert p2.income_statement.revenue == pytest.approx(REVENUE_2, abs=TOL)+ assert p2.income_statement.gross_profit == pytest.approx(GROSS_PROFIT_2, abs=TOL)+ assert p2.income_statement.opex == pytest.approx(OPEX_2, abs=TOL)+ assert p2.income_statement.ebitda == pytest.approx(EBITDA_2, abs=TOL)+ assert p2.income_statement.depreciation_amortization == pytest.approx(DA[1], abs=TOL)+ assert p2.income_statement.ebit == pytest.approx(EBIT_2, abs=TOL)+ assert p2.income_statement.interest_expense == pytest.approx(INTEREST_2, abs=TOL)+ assert p2.income_statement.pretax_income == pytest.approx(PRETAX_2, abs=TOL)+ assert p2.income_statement.tax_expense == pytest.approx(TAX_2, abs=TOL)+ assert p2.income_statement.net_income == pytest.approx(NI_2, abs=TOL)++ # --- Period 2 cash flow statement ---+ assert p2.cash_flow_statement.change_in_net_working_capital == pytest.approx(D_NWC_2, abs=TOL)+ assert p2.cash_flow_statement.capex == pytest.approx(CAPEX_2, abs=TOL)+ assert p2.cash_flow_statement.dividends_paid == pytest.approx(DIV_2, abs=TOL)+ assert p2.cash_flow_statement.revolver_draw == pytest.approx(0.0, abs=TOL)+ assert p2.cash_flow_statement.revolver_repayment == pytest.approx(0.0, abs=TOL)+ assert p2.cash_flow_statement.financing_activities == pytest.approx(-DIV_2, abs=TOL)+ assert p2.cash_flow_statement.net_change_in_cash == pytest.approx(CFBF_2, abs=TOL)++ # --- Period 2 balance sheet ---+ assert p2.balance_sheet.cash == pytest.approx(CASH_2, abs=TOL)+ assert p2.balance_sheet.net_working_capital == pytest.approx(NWC_END_2, abs=TOL)+ assert p2.balance_sheet.ppe == pytest.approx(PPE_2, abs=TOL)+ assert p2.balance_sheet.revolver_balance == pytest.approx(DEBT_0, abs=TOL)+ assert p2.balance_sheet.retained_earnings == pytest.approx(RE_2, abs=TOL)+ assert p2.converged is True+ _assert_balances(p2.balance_sheet)++ # --- Period 3 income statement ---+ assert p3.income_statement.revenue == pytest.approx(REVENUE_3, abs=TOL)+ assert p3.income_statement.gross_profit == pytest.approx(GROSS_PROFIT_3, abs=TOL)+ assert p3.income_statement.opex == pytest.approx(OPEX_3, abs=TOL)+ assert p3.income_statement.ebitda == pytest.approx(EBITDA_3, abs=TOL)+ assert p3.income_statement.depreciation_amortization == pytest.approx(DA[2], abs=TOL)+ assert p3.income_statement.ebit == pytest.approx(EBIT_3, abs=TOL)+ assert p3.income_statement.interest_expense == pytest.approx(INTEREST_3, abs=TOL)+ assert p3.income_statement.pretax_income == pytest.approx(PRETAX_3, abs=TOL)+ assert p3.income_statement.tax_expense == pytest.approx(TAX_3, abs=TOL)+ assert p3.income_statement.net_income == pytest.approx(NI_3, abs=TOL)++ # --- Period 3 cash flow statement (note the NWC *source* of cash) ---+ assert p3.cash_flow_statement.change_in_net_working_capital == pytest.approx(D_NWC_3, abs=TOL)+ assert D_NWC_3 < 0.0+ assert p3.cash_flow_statement.capex == pytest.approx(CAPEX_3, abs=TOL)+ assert p3.cash_flow_statement.dividends_paid == pytest.approx(DIV_3, abs=TOL)+ assert p3.cash_flow_statement.revolver_draw == pytest.approx(0.0, abs=TOL)+ assert p3.cash_flow_statement.revolver_repayment == pytest.approx(0.0, abs=TOL)+ assert p3.cash_flow_statement.financing_activities == pytest.approx(-DIV_3, abs=TOL)+ assert p3.cash_flow_statement.net_change_in_cash == pytest.approx(CFBF_3, abs=TOL)++ # --- Period 3 balance sheet ---+ assert p3.balance_sheet.cash == pytest.approx(CASH_3, abs=TOL)+ assert p3.balance_sheet.net_working_capital == pytest.approx(NWC_END_3, abs=TOL)+ assert p3.balance_sheet.ppe == pytest.approx(PPE_3, abs=TOL)+ assert p3.balance_sheet.revolver_balance == pytest.approx(DEBT_0, abs=TOL)+ assert p3.balance_sheet.paid_in_capital == pytest.approx(PAID_IN, abs=TOL)+ assert p3.balance_sheet.retained_earnings == pytest.approx(RE_3, abs=TOL)+ assert p3.converged is True+ _assert_balances(p3.balance_sheet)++ # All three periods balance -- assets == liabilities + equity, exactly.+ for period_result in result.periods:+ bs = period_result.balance_sheet+ assert bs.total_assets == pytest.approx(bs.total_liabilities + bs.total_equity, abs=TOL)+++# --------------------------------------------------------------------------+# Hard balance check: must raise on a genuinely unbalanced input, not just+# stay quiet on a balanced one.+# --------------------------------------------------------------------------+++def test_check_balance_sheet_raises_on_broken_retained_earnings():+ """A balance sheet whose retained-earnings rollforward was hand-broken must raise.++ Assets = 1,000 + 200 + 3,000 = 4,200. Liabilities + equity =+ 1,000 + 2,000 + 1,000 = 4,000. The 200 gap is a deliberately wrong+ retained_earnings (it should have been 1,200 to balance).+ """+ broken = BalanceSheet(+ period=1,+ cash=1_000.0,+ net_working_capital=200.0,+ ppe=3_000.0,+ revolver_balance=1_000.0,+ paid_in_capital=2_000.0,+ retained_earnings=1_000.0, # should be 1,200.0 to balance+ )+ with pytest.raises(BalanceSheetError) as excinfo:+ check_balance_sheet(broken)+ assert excinfo.value.residual == pytest.approx(200.0, abs=TOL)+ assert "200" in str(excinfo.value)+ assert excinfo.value.period == 1+++def test_check_balance_sheet_does_not_raise_when_balanced():+ """The same construction, with the correct retained earnings, must not raise."""+ balanced = BalanceSheet(+ period=1,+ cash=1_000.0,+ net_working_capital=200.0,+ ppe=3_000.0,+ revolver_balance=1_000.0,+ paid_in_capital=2_000.0,+ retained_earnings=1_200.0,+ )+ check_balance_sheet(balanced) # must not raise+++def test_project_three_statement_raises_on_broken_opening_balance_sheet():+ """An opening balance sheet that does not balance must refuse to project at all.++ Reuses the flagship OPENING dict but bumps retained_earnings by 1.0, which+ breaks the identity by exactly 1.0 (residual = -1.0, since equity is now+ 1.0 too large).+ """+ broken_opening = dict(OPENING)+ broken_opening["retained_earnings"] = OPENING["retained_earnings"] + 1.0+ with pytest.raises(BalanceSheetError) as excinfo:+ project_three_statement(broken_opening, DRIVERS)+ assert excinfo.value.period == 0+ assert excinfo.value.residual == pytest.approx(-1.0, abs=TOL)+++# --------------------------------------------------------------------------+# Interest/revolver circularity: convergent (multi-iteration) and divergent.+# --------------------------------------------------------------------------++_CIRC_OPENING = {+ "revenue": 1_000_000.0,+ "cash": 50_000.0,+ "net_working_capital": 100_000.0,+ "ppe": 500_000.0,+ "revolver_balance": 200_000.0,+ "paid_in_capital": 300_000.0,+ "retained_earnings": 150_000.0,+}+_CIRC_DRIVERS = {+ "revenue_growth": [0.05],+ "gross_margin": [0.35],+ "opex_pct_revenue": [0.20],+ "capex_pct_revenue": [0.06],+ "nwc_pct_revenue": [0.12],+ "tax_rate": [0.25],+ "dividend_payout_ratio": [0.20],+ "depreciation_amortization": [40_000.0],+ "interest_rate": [0.20], # 20% -- forces a real draw, hence real circularity+ "minimum_cash": [300_000.0], # well above the natural cash balance -> shortfall+}+++def test_circularity_converges_in_more_than_one_iteration():+ """A real cash shortfall forces the interest/revolver fixed point to iterate.++ The initial guess (no revolver movement) is not the fixed point here --+ minimum_cash is set far above the cash the company would otherwise land+ on, so the first pass computes a large draw, which changes the average+ debt balance, which changes interest, which changes net income and hence+ the draw again. The solve must still converge and say so.+ """+ result = project_three_statement(_CIRC_OPENING, _CIRC_DRIVERS)+ period = result.periods[0]+ assert period.converged is True+ assert period.iterations > 1+ assert period.cash_flow_statement.revolver_draw > 0.0+ _assert_balances(period.balance_sheet)+++def test_divergent_circularity_raises_convergence_error():+ """A loop gain above 1 makes the fixed point explode; the model must refuse to answer.++ With dividend_payout_ratio=0 and tax_rate=0, the fixed-point gain on the+ ending debt balance is ``interest_rate / 2`` (see the module docstring's+ derivation). At interest_rate=5.0 (500%) that gain is 2.5, comfortably+ above 1: each iteration's debt guess moves *further* from the last, not+ closer, so no finite iteration budget converges it.+ """+ diverging_opening = dict(_CIRC_OPENING)+ diverging_drivers = dict(_CIRC_DRIVERS)+ diverging_drivers["interest_rate"] = [5.0]+ diverging_drivers["dividend_payout_ratio"] = [0.0]+ diverging_drivers["tax_rate"] = [0.0]+ diverging_drivers["minimum_cash"] = [10_000_000.0] # stays in the shortfall regime throughout++ with pytest.raises(ConvergenceError) as excinfo:+ project_three_statement(diverging_opening, diverging_drivers)+ assert excinfo.value.iterations == MAX_CIRCULARITY_ITERATIONS+ assert excinfo.value.period == 1+ # A genuinely diverging (not just slowly converging) loop leaves the last+ # step's change many orders of magnitude larger than the tolerance.+ assert excinfo.value.last_delta > 1e30+++# --------------------------------------------------------------------------+# Explicit plug: the revolver balance is a visible, reported field, and the+# balance sheet still balances exactly once it has been applied.+# --------------------------------------------------------------------------+++def test_revolver_plug_is_explicit_and_balance_sheet_still_balances():+ """The revolver draw and the resulting balance are visible result fields."""+ result = project_three_statement(_CIRC_OPENING, _CIRC_DRIVERS)+ period = result.periods[0]++ # The plug is not hidden inside a residual -- it is a named field on both+ # the cash flow statement (the movement) and the balance sheet (the level).+ assert period.cash_flow_statement.revolver_draw > 0.0+ assert period.cash_flow_statement.revolver_repayment == 0.0+ expected_balance = _CIRC_OPENING["revolver_balance"] + period.cash_flow_statement.revolver_draw+ assert period.balance_sheet.revolver_balance == pytest.approx(expected_balance, abs=TOL)++ # Cash was brought exactly up to the minimum_cash floor by the draw.+ assert period.balance_sheet.cash == pytest.approx(_CIRC_DRIVERS["minimum_cash"][0], abs=TOL)++ _assert_balances(period.balance_sheet)+++# --------------------------------------------------------------------------+# Missing inputs: no defaults, ever.+# --------------------------------------------------------------------------+++def test_missing_opening_field_raises_missing_input_error():+ """Dropping a required opening-balance field refuses to run, naming the field."""+ incomplete_opening = dict(OPENING)+ del incomplete_opening["retained_earnings"]+ with pytest.raises(MissingInputError) as excinfo:+ project_three_statement(incomplete_opening, DRIVERS)+ assert excinfo.value.missing == ("retained_earnings",)+++def test_missing_driver_field_raises_missing_input_error():+ """Dropping a required driver sequence refuses to run, naming the field.++ ``tax_rate`` is deliberately chosen: it is downstream of every other line+ in the income statement, so if the model silently defaulted it, the+ resulting net income would look plausible rather than obviously wrong.+ """+ incomplete_drivers = dict(DRIVERS)+ del incomplete_drivers["tax_rate"]+ with pytest.raises(MissingInputError) as excinfo:+ project_three_statement(OPENING, incomplete_drivers)+ assert excinfo.value.missing == ("tax_rate",)+++def test_missing_multiple_fields_are_all_named_at_once():+ """MissingInputError reports every missing field in one pass, not just the first."""+ incomplete_drivers = dict(DRIVERS)+ del incomplete_drivers["tax_rate"]+ del incomplete_drivers["interest_rate"]+ with pytest.raises(MissingInputError) as excinfo:+ project_three_statement(OPENING, incomplete_drivers)+ assert set(excinfo.value.missing) == {"tax_rate", "interest_rate"}+++# --------------------------------------------------------------------------+# Structural validation beyond missingness: mismatched / empty driver lengths.+# --------------------------------------------------------------------------+++def test_mismatched_driver_lengths_raise():+ """Driver sequences of different lengths cannot be zipped into periods safely."""+ mismatched = dict(DRIVERS)+ mismatched["tax_rate"] = [0.25, 0.25] # length 2 vs. 3 everywhere else+ with pytest.raises(Exception, match=r"(?i)length"):+ project_three_statement(OPENING, mismatched)+++def test_empty_driver_sequences_raise():+ """Zero-length driver sequences mean zero periods, which is not a projection."""+ empty_drivers = {field: [] for field in DRIVERS}+ with pytest.raises(Exception, match=r"(?i)period"):+ project_three_statement(OPENING, empty_drivers)+++# --------------------------------------------------------------------------+# Boundary conditions.+# --------------------------------------------------------------------------+++def test_zero_revenue_boundary():+ """A pre-revenue company still produces a linked, balanced projection.++ With revenue pinned at zero, every revenue-scaled line (gross profit,+ opex, capex, NWC) is zero too, but D&A is a direct dollar input and keeps+ accruing, so EBIT, pretax income and net income are all driven purely+ negative by D&A -- and the model must not divide by revenue anywhere to+ get there.+ """+ opening = {+ "revenue": 0.0,+ "cash": 100_000.0,+ "net_working_capital": 0.0,+ "ppe": 200_000.0,+ "revolver_balance": 0.0,+ "paid_in_capital": 250_000.0,+ "retained_earnings": 50_000.0,+ }+ drivers = {+ "revenue_growth": [0.0, 0.0],+ "gross_margin": [0.40, 0.40],+ "opex_pct_revenue": [0.20, 0.20],+ "capex_pct_revenue": [0.0, 0.0],+ "nwc_pct_revenue": [0.10, 0.10],+ "tax_rate": [0.25, 0.25],+ "dividend_payout_ratio": [0.5, 0.5],+ "depreciation_amortization": [10_000.0, 10_000.0],+ "interest_rate": [0.05, 0.05],+ "minimum_cash": [0.0, 0.0],+ }+ result = project_three_statement(opening, drivers)+ for period in result.periods:+ assert period.income_statement.revenue == 0.0+ assert period.income_statement.gross_profit == 0.0+ assert period.income_statement.opex == 0.0+ assert period.income_statement.ebitda == 0.0+ assert period.income_statement.ebit == pytest.approx(-10_000.0, abs=TOL)+ assert period.income_statement.net_income == pytest.approx(-7_500.0, abs=TOL)+ assert period.cash_flow_statement.capex == 0.0+ assert period.balance_sheet.net_working_capital == 0.0+ _assert_balances(period.balance_sheet)+++def test_negative_net_income_drives_retained_earnings_negative():+ """A sustained loss must be allowed to push retained earnings below zero.++ Opex is set to 50% of revenue against a 10% gross margin, guaranteeing a+ large operating loss; the payout clamp means loss periods pay no dividend+ (max(net_income, 0) * payout == 0), so the loss flows straight through to+ retained earnings.+ """+ opening = {+ "revenue": 100_000.0,+ "cash": 50_000.0,+ "net_working_capital": 10_000.0,+ "ppe": 100_000.0,+ "revolver_balance": 0.0,+ "paid_in_capital": 155_000.0,+ "retained_earnings": 5_000.0,+ }+ drivers = {+ "revenue_growth": [0.0, 0.0],+ "gross_margin": [0.10, 0.10],+ "opex_pct_revenue": [0.50, 0.50],+ "capex_pct_revenue": [0.0, 0.0],+ "nwc_pct_revenue": [0.10, 0.10],+ "tax_rate": [0.25, 0.25],+ "dividend_payout_ratio": [0.3, 0.3],+ "depreciation_amortization": [5_000.0, 5_000.0],+ "interest_rate": [0.05, 0.05],+ "minimum_cash": [0.0, 0.0],+ }+ result = project_three_statement(opening, drivers)+ period1 = result.periods[0]+ assert period1.income_statement.net_income < 0.0+ assert period1.cash_flow_statement.dividends_paid == 0.0+ assert period1.balance_sheet.retained_earnings < 0.0+ _assert_balances(period1.balance_sheet)++ period2 = result.periods[1]+ assert period2.balance_sheet.retained_earnings < period1.balance_sheet.retained_earnings+ _assert_balances(period2.balance_sheet)+++def test_capex_exceeding_depreciation_grows_ppe():+ """When capex outpaces D&A, net PP&E must increase by exactly the difference."""+ opening = {+ "revenue": 100_000.0,+ "cash": 100_000.0,+ "net_working_capital": 10_000.0,+ "ppe": 50_000.0,+ "revolver_balance": 0.0,+ "paid_in_capital": 100_000.0,+ "retained_earnings": 60_000.0,+ }+ drivers = {+ "revenue_growth": [0.0],+ "gross_margin": [0.40],+ "opex_pct_revenue": [0.20],+ "capex_pct_revenue": [0.10], # capex = 10,000+ "nwc_pct_revenue": [0.10],+ "tax_rate": [0.25],+ "dividend_payout_ratio": [0.0],+ "depreciation_amortization": [2_000.0], # da = 2,000 << capex+ "interest_rate": [0.0],+ "minimum_cash": [0.0],+ }+ result = project_three_statement(opening, drivers)+ period = result.periods[0]+ assert period.cash_flow_statement.capex == pytest.approx(10_000.0, abs=TOL)+ assert period.income_statement.depreciation_amortization == pytest.approx(2_000.0, abs=TOL)+ assert period.balance_sheet.ppe == pytest.approx(opening["ppe"] + 10_000.0 - 2_000.0, abs=TOL)+ assert period.balance_sheet.ppe > opening["ppe"]+ _assert_balances(period.balance_sheet)diff --git a/agent/tests/test_entities_spine.py b/agent/tests/test_entities_spine.pyindex 46e291bea..27e26fc2e 100644--- a/agent/tests/test_entities_spine.py+++ b/agent/tests/test_entities_spine.py@@ -14,6 +14,8 @@ from src.entities.cashflow import (normalize_kind,)from src.entities.ingest import CashFlowIngestError, load_cashflows+from src.entities.cashflow import FxRate, FxRateTable, MissingExchangeRateError, translate_cashflows+from src.entities.ingest import EntityPanel, PanelIngestError, PanelObservation, load_panelfrom src.entities.models import (Bond,Entity,@@ -671,3 +673,382 @@ def test_series_is_not_a_dataframe_and_exposes_no_bar_fields():series = CashFlowSeries(flows=(_flow(1, 100.0, kind="nav"),))assert not hasattr(series, "close")assert not hasattr(series[0], "close")+++# ---------------------------------------------------------------------------+# FX translation+# ---------------------------------------------------------------------------+++def test_translate_cashflows_hand_calculated_multi_currency():+ """Two flows, different currency and date, checked against a hand calc."""+ flow_eur = CashFlow(+ date=date(2024, 1, 10), amount=1000.0, kind="distribution", currency="EUR"+ )+ flow_jpy = CashFlow(+ date=date(2024, 2, 15), amount=-2000.0, kind="capital_call", currency="JPY"+ )+ table = FxRateTable.from_rates(+ [+ FxRate(base_currency="EUR", quote_currency="USD", date=date(2024, 1, 10), rate=1.10),+ FxRate(base_currency="JPY", quote_currency="USD", date=date(2024, 2, 15), rate=0.0067),+ ],+ quote_currency="USD",+ )+ series = translate_cashflows([flow_eur, flow_jpy], table)+ assert series.currency == "USD"+ assert series.pre_translated is True+ # Hand calc: 1000 EUR * 1.10 = 1100.0 USD; -2000 JPY * 0.0067 = -13.4 USD+ amounts = {f.metadata["fx_original_currency"]: f.amount for f in series}+ assert amounts["EUR"] == pytest.approx(1100.0, abs=1e-9)+ assert amounts["JPY"] == pytest.approx(-13.4, abs=1e-9)+ assert series.total() == pytest.approx(1100.0 - 13.4, abs=1e-9)+++def test_translate_cashflows_uses_each_flows_own_settlement_date_rate_not_period_end():+ """A period-end rate would silently give 200.0 instead of the correct 100.0."""+ table = FxRateTable.from_rates(+ [+ FxRate(base_currency="EUR", quote_currency="USD", date=date(2024, 1, 1), rate=1.0),+ FxRate(base_currency="EUR", quote_currency="USD", date=date(2024, 1, 10), rate=2.0),+ ],+ quote_currency="USD",+ )+ early_flow = CashFlow(date=date(2024, 1, 1), amount=100.0, kind="coupon", currency="EUR")+ series = translate_cashflows([early_flow], table)+ assert series[0].amount == pytest.approx(100.0, abs=1e-9)+ assert series[0].amount != pytest.approx(200.0, abs=1e-9)+ assert series[0].metadata["fx_rate_date"] == date(2024, 1, 1)+++def test_fx_rate_table_rejects_entry_quoted_against_the_wrong_currency():+ """A reversed-direction quote (base/quote swapped) cannot enter a table+ declared for the other currency -- caught at construction, not silently+ used in the wrong direction.+ """+ reversed_quote = FxRate(+ base_currency="USD", quote_currency="EUR", date=date(2024, 1, 10), rate=0.91+ )+ with pytest.raises(ValueError, match="does not quote against"):+ FxRateTable(quote_currency="USD", rates={("EUR", date(2024, 1, 10)): reversed_quote})+++def test_translate_cashflows_reversed_rate_produces_a_grossly_wrong_number():+ """A confused caller who uses the reciprocal (150) instead of the correct+ quote-per-base rate (1/150) does not get a subtly-off number -- they get+ one nobody could mistake for correct.+ """+ flow = CashFlow(date=date(2024, 1, 1), amount=1_000_000.0, kind="distribution", currency="JPY")++ correct_rate = 1 / 150 # 1 JPY = 1/150 USD+ correct_table = FxRateTable.from_rates(+ [FxRate(base_currency="JPY", quote_currency="USD", date=date(2024, 1, 1), rate=correct_rate)],+ quote_currency="USD",+ )+ correct_amount = translate_cashflows([flow], correct_table)[0].amount+ assert correct_amount == pytest.approx(1_000_000.0 / 150, abs=1e-6)++ reversed_table = FxRateTable.from_rates(+ [FxRate(base_currency="JPY", quote_currency="USD", date=date(2024, 1, 1), rate=150.0)],+ quote_currency="USD",+ )+ reversed_amount = translate_cashflows([flow], reversed_table)[0].amount+ assert reversed_amount == pytest.approx(1_000_000.0 * 150, abs=1e-6)+ assert reversed_amount / correct_amount > 20_000 # off by 22,500x+++def test_translate_cashflows_missing_rate_raises_explicit_error():+ flow = CashFlow(date=date(2024, 1, 10), amount=1000.0, kind="distribution", currency="EUR")+ table = FxRateTable(quote_currency="USD")+ with pytest.raises(MissingExchangeRateError, match="no EUR/USD rate"):+ translate_cashflows([flow], table)+++def test_translate_cashflows_allow_stale_rates_flags_the_reused_quote():+ table = FxRateTable.from_rates(+ [FxRate(base_currency="EUR", quote_currency="USD", date=date(2024, 1, 1), rate=1.1)],+ quote_currency="USD",+ )+ flow = CashFlow(date=date(2024, 1, 20), amount=100.0, kind="coupon", currency="EUR")+ with pytest.raises(MissingExchangeRateError):+ translate_cashflows([flow], table) # off by default++ series = translate_cashflows([flow], table, allow_stale_rates=True)+ result = series[0]+ assert result.amount == pytest.approx(110.0, abs=1e-9)+ assert result.metadata["fx_rate_is_stale"] is True+ assert result.metadata["fx_rate_date"] == date(2024, 1, 1)+++def test_translate_cashflows_max_staleness_days_bounds_the_stale_search():+ table = FxRateTable.from_rates(+ [FxRate(base_currency="EUR", quote_currency="USD", date=date(2024, 1, 1), rate=1.1)],+ quote_currency="USD",+ )+ flow = CashFlow(date=date(2024, 1, 20), amount=100.0, kind="coupon", currency="EUR")+ with pytest.raises(MissingExchangeRateError, match="within 5 days"):+ translate_cashflows([flow], table, allow_stale_rates=True, max_staleness_days=5)++ series = translate_cashflows([flow], table, allow_stale_rates=True, max_staleness_days=30)+ assert series[0].metadata["fx_rate_is_stale"] is True+++def test_fx_rate_rejects_non_positive_rate():+ with pytest.raises(ValueError, match="strictly positive"):+ FxRate(base_currency="EUR", quote_currency="USD", date=date(2024, 1, 1), rate=0.0)+ with pytest.raises(ValueError, match="strictly positive"):+ FxRate(base_currency="EUR", quote_currency="USD", date=date(2024, 1, 1), rate=-1.5)+++def test_fx_rate_table_from_mapping_builds_a_table():+ table = FxRateTable.from_mapping(+ {("EUR", date(2024, 1, 1)): 1.1, ("JPY", date(2024, 1, 1)): 0.0067},+ quote_currency="USD",+ )+ rate, is_stale = table.get_rate("eur", date(2024, 1, 1))+ assert rate.rate == pytest.approx(1.1)+ assert is_stale is False+++def test_translate_cashflows_preserves_original_amount_currency_rate_and_date():+ flow = CashFlow(+ date=date(2024, 1, 10),+ amount=1000.0,+ kind="distribution",+ currency="EUR",+ metadata={"note": "Q1 distribution"},+ )+ table = FxRateTable.from_rates(+ [FxRate(base_currency="EUR", quote_currency="USD", date=date(2024, 1, 10), rate=1.1)],+ quote_currency="USD",+ )+ translated = translate_cashflows([flow], table)[0]+ assert translated.metadata["fx_original_amount"] == 1000.0+ assert translated.metadata["fx_original_currency"] == "EUR"+ assert translated.metadata["fx_rate"] == pytest.approx(1.1)+ assert translated.metadata["fx_rate_date"] == date(2024, 1, 10)+ assert translated.metadata["fx_rate_is_stale"] is False+ assert translated.metadata["note"] == "Q1 distribution" # original metadata kept too+++def test_translate_cashflows_same_currency_flow_passes_through_unchanged():+ flow = CashFlow(date=date(2024, 1, 10), amount=250.0, kind="coupon", currency="USD")+ table = FxRateTable(quote_currency="USD")+ translated = translate_cashflows([flow], table)[0]+ assert translated.amount == pytest.approx(250.0)+ assert translated.metadata["fx_rate"] == 1.0+ assert translated.metadata["fx_rate_is_stale"] is False+++# ---------------------------------------------------------------------------+# Panel ingestion (load_panel)+# ---------------------------------------------------------------------------+++def test_load_panel_long_layout_reads_a_fixture_csv(tmp_path):+ path = _write_csv(+ tmp_path,+ "panel.csv",+ "entity,date,metric,value,currency,unit\n"+ "FUNDA,2024-01-01,nav,100.5,USD,USD\n"+ "FUNDA,2024-02-01,nav,101.2,USD,USD\n"+ "FUNDB,2024-01-01,nav,50.0,EUR,EUR\n",+ )+ panel = load_panel(path)+ assert len(panel) == 3+ assert panel.entities() == ("FUNDA", "FUNDB")+ assert panel.metrics() == ("nav",)+ observations = list(panel)+ assert observations[0].entity_id == "FUNDA"+ assert observations[0].date == date(2024, 1, 1)+ assert observations[0].value == pytest.approx(100.5)+ assert observations[0].currency == "USD"+ assert observations[0].unit == "USD"+++def test_load_panel_infers_wide_dates_rows_layout_and_skips_holes(tmp_path):+ path = _write_csv(+ tmp_path,+ "wide.csv",+ "date,FUNDA,FUNDB\n2024-01-01,100.5,50.0\n2024-02-01,101.2,\n",+ )+ panel = load_panel(path, metric="nav", currency="USD", unit="USD")+ assert len(panel) == 3 # the blank FUNDB@2024-02-01 cell produced no observation+ assert panel.entities() == ("FUNDA", "FUNDB")+ values = {(o.entity_id, o.date): o.value for o in panel}+ assert values[("FUNDA", date(2024, 1, 1))] == pytest.approx(100.5)+ assert ("FUNDB", date(2024, 2, 1)) not in values+++def test_load_panel_infers_wide_entities_rows_layout(tmp_path):+ path = _write_csv(+ tmp_path,+ "wide.csv",+ "entity,2024-01-01,2024-02-01\nFUNDA,100.5,101.2\nFUNDB,50.0,\n",+ )+ panel = load_panel(path, metric="nav", currency="USD", unit="USD")+ assert len(panel) == 3+ values = {(o.entity_id, o.date): o.value for o in panel}+ assert values[("FUNDA", date(2024, 2, 1))] == pytest.approx(101.2)+ assert ("FUNDB", date(2024, 2, 1)) not in values+++def test_load_panel_missing_value_column_raises_not_none(tmp_path):+ path = _write_csv(+ tmp_path, "panel.csv", "entity,date,metric,currency,unit\nFUNDA,2024-01-01,nav,USD,USD\n"+ )+ with pytest.raises(PanelIngestError, match="value"):+ load_panel(path)+++def test_load_panel_missing_currency_is_an_error_not_a_default(tmp_path):+ path = _write_csv(+ tmp_path, "panel.csv", "entity,date,metric,value,unit\nFUNDA,2024-01-01,nav,100,USD\n"+ )+ with pytest.raises(PanelIngestError, match="currency"):+ load_panel(path)+++def test_load_panel_missing_unit_is_an_error_not_a_default(tmp_path):+ path = _write_csv(+ tmp_path, "panel.csv", "entity,date,metric,value,currency\nFUNDA,2024-01-01,nav,100,USD\n"+ )+ with pytest.raises(PanelIngestError, match="unit"):+ load_panel(path)+++def test_load_panel_ambiguous_header_raises_and_explicit_layout_resolves_it(tmp_path):+ """A header that matches no recognised shape must not be silently guessed."""+ path = _write_csv(tmp_path, "panel.csv", "foo,bar,baz\nFUNDA,2024-01-01,100\n")+ with pytest.raises(PanelIngestError, match="could not infer a panel layout"):+ load_panel(path)++ panel = load_panel(+ path,+ layout="long",+ columns={"entity": "foo", "date": "bar", "value": "baz"},+ metric="nav",+ currency="USD",+ unit="USD",+ )+ assert len(panel) == 1+ obs = list(panel)[0]+ assert obs.entity_id == "FUNDA"+ assert obs.value == pytest.approx(100.0)+++def test_load_panel_empty_file_raises_not_none(tmp_path):+ path = _write_csv(tmp_path, "empty.csv", "")+ with pytest.raises(PanelIngestError, match="no header row"):+ load_panel(path)+++def test_load_panel_header_only_long_file_yields_an_empty_panel(tmp_path):+ path = _write_csv(tmp_path, "panel.csv", "entity,date,metric,value,currency,unit\n")+ panel = load_panel(path)+ assert panel.is_empty+++def test_load_panel_wide_layout_requires_metric_currency_and_unit(tmp_path):+ path = _write_csv(tmp_path, "wide.csv", "date,FUNDA,FUNDB\n2024-01-01,100.5,50.0\n")+ with pytest.raises(PanelIngestError, match="metric"):+ load_panel(path, currency="USD", unit="USD")+ with pytest.raises(PanelIngestError, match="currency"):+ load_panel(path, metric="nav", unit="USD")+ with pytest.raises(PanelIngestError, match="unit"):+ load_panel(path, metric="nav", currency="USD")+++def test_load_panel_wide_entities_rows_bad_date_header_raises(tmp_path):+ path = _write_csv(+ tmp_path, "wide.csv", "entity,2024-01-01,not-a-date\nFUNDA,100.5,101.2\n"+ )+ with pytest.raises(PanelIngestError, match="not a usable date"):+ load_panel(path, layout="wide_entities_rows", metric="nav", currency="USD", unit="USD")+++def test_load_panel_explicit_column_mapping(tmp_path):+ path = _write_csv(+ tmp_path,+ "panel.csv",+ "Fund,AsOf,Field,Net,CCY,UOM\nFUNDA,2024-01-01,nav,100.5,USD,USD\n",+ )+ panel = load_panel(+ path,+ layout="long",+ columns={+ "entity": "Fund",+ "date": "AsOf",+ "metric": "Field",+ "value": "Net",+ "currency": "CCY",+ "unit": "UOM",+ },+ )+ assert len(panel) == 1+ assert list(panel)[0].value == pytest.approx(100.5)+++def test_load_panel_metric_is_normalized(tmp_path):+ path = _write_csv(+ tmp_path,+ "panel.csv",+ "entity,date,metric,value,currency,unit\nFUNDA,2024-01-01,NAV,100,USD,USD\n",+ )+ panel = load_panel(path)+ assert list(panel)[0].metric == "nav"+++def test_entity_panel_is_immutable_and_ordered(tmp_path):+ path = _write_csv(+ tmp_path,+ "panel.csv",+ "entity,date,metric,value,currency,unit\n"+ "FUNDB,2024-02-01,nav,1,USD,USD\n"+ "FUNDA,2024-01-01,nav,2,USD,USD\n",+ )+ panel = load_panel(path)+ entities_in_order = [o.entity_id for o in panel]+ assert entities_in_order == ["FUNDA", "FUNDB"]+ with pytest.raises(dataclasses.FrozenInstanceError):+ panel.observations = ()+++def test_load_panel_rejects_an_invalid_decimal_separator(tmp_path):+ path = _write_csv(+ tmp_path,+ "panel.csv",+ "entity,date,metric,value,currency,unit\nFUNDA,2024-01-01,nav,100,USD,USD\n",+ )+ with pytest.raises(ValueError, match="decimal_separator must be"):+ load_panel(path, decimal_separator=";")+++def test_load_panel_rejects_an_invalid_layout_value(tmp_path):+ path = _write_csv(+ tmp_path,+ "panel.csv",+ "entity,date,metric,value,currency,unit\nFUNDA,2024-01-01,nav,100,USD,USD\n",+ )+ with pytest.raises(PanelIngestError, match="layout must be one of"):+ load_panel(path, layout="sideways")+++def test_panel_observation_is_not_a_bar_and_exposes_no_ohlc_fields():+ obs = PanelObservation(+ entity_id="FUNDA", date=date(2024, 1, 1), metric="nav", value=100.0,+ currency="USD", unit="USD",+ )+ assert not hasattr(obs, "close")+ assert not hasattr(obs, "open")+++def test_panel_path_does_not_touch_the_bar_price_panel_gate():+ """Same architectural guarantee as CashFlowSeries: the panel ingest path+ must never widen what a bar engine will accept as a price column.+ """+ from backtest.runner import _PRICE_PANEL_COLUMNS, _VALID_INTERVALS++ assert _PRICE_PANEL_COLUMNS == ("open", "high", "low", "close", "volume", "vwap", "amount")+ assert "nav" not in _PRICE_PANEL_COLUMNS+ assert _VALID_INTERVALS == {"1m", "5m", "15m", "30m", "1H", "4H", "1D"}diff --git a/agent/tests/test_factor_costs.py b/agent/tests/test_factor_costs.pynew file mode 100644index 000000000..651a2e020--- /dev/null+++ b/agent/tests/test_factor_costs.py@@ -0,0 +1,303 @@+"""Tests for backtest.factor_costs.++The load-bearing test is the one showing a high-turnover factor is eroded and a+low-turnover one is not. A cost model that charges everyone equally, or charges+nobody, would pass a suite that only checked "cost >= 0".+"""++import numpy as np+import pandas as pd+import pytest++from backtest.factor_costs import (+ DEFAULT_MAX_PARTICIPATION,+ MARKET_BORROW_RATES,+ apply_adv_capacity,+ borrow_cost,+ rebalance_cost,+)+++def _w(**kwargs):+ return pd.Series(kwargs, dtype=float)+++# --- ADV capacity ---+++def test_a_trade_within_capacity_fills_completely():+ target = _w(A=0.10, B=-0.10)+ current = _w(A=0.0, B=0.0)+ adv = _w(A=1e9, B=1e9)+ result = apply_adv_capacity(target, current, adv, capital=1e6)++ assert result.achieved_weights["A"] == pytest.approx(0.10)+ assert result.achieved_weights["B"] == pytest.approx(-0.10)+ assert result.unfilled_weights.abs().sum() == pytest.approx(0.0)+ assert result.capped_symbols == ()+++def test_an_oversized_trade_moves_part_way_and_reports_the_shortfall():+ # ADV 1,000,000 at 10% participation = 100,000 tradeable; capital 1,000,000+ # so the largest weight change is 0.10. Asking for 0.30 gets 0.10.+ target = _w(A=0.30)+ current = _w(A=0.0)+ adv = _w(A=1_000_000.0)+ result = apply_adv_capacity(target, current, adv, capital=1_000_000.0)++ assert result.achieved_weights["A"] == pytest.approx(0.10)+ assert result.unfilled_weights["A"] == pytest.approx(0.20)+ assert result.capped_symbols == ("A",)+ assert result.participation["A"] == pytest.approx(DEFAULT_MAX_PARTICIPATION)+++def test_the_shortfall_is_neither_silently_filled_nor_silently_dropped():+ target = _w(A=0.30)+ current = _w(A=0.0)+ adv = _w(A=1_000_000.0)+ result = apply_adv_capacity(target, current, adv, capital=1_000_000.0)++ # Not filled: achieved is short of target.+ assert result.achieved_weights["A"] < result.requested_weights["A"]+ # Not dropped: the difference is reported and reconciles exactly.+ assert (+ result.achieved_weights["A"] + result.unfilled_weights["A"]+ == pytest.approx(result.requested_weights["A"])+ )+++def test_a_name_with_unknown_volume_is_untradeable_not_infinitely_liquid():+ target = _w(A=0.20, B=0.20)+ current = _w(A=0.0, B=0.0)+ adv = _w(A=1e12) # B has no ADV at all+ result = apply_adv_capacity(target, current, adv, capital=1e6)++ assert result.achieved_weights["A"] == pytest.approx(0.20)+ assert result.achieved_weights["B"] == pytest.approx(0.0)+ assert result.unfilled_weights["B"] == pytest.approx(0.20)+++def test_zero_and_negative_adv_are_treated_as_untradeable():+ for bad in (0.0, -5.0):+ result = apply_adv_capacity(_w(A=0.1), _w(A=0.0), _w(A=bad), capital=1e6)+ assert result.achieved_weights["A"] == pytest.approx(0.0)+++def test_capacity_caps_exits_as_well_as_entries():+ # Getting out is a trade too, and an illiquid name traps you.+ target = _w(A=0.0)+ current = _w(A=0.30)+ adv = _w(A=1_000_000.0)+ result = apply_adv_capacity(target, current, adv, capital=1_000_000.0)++ assert result.achieved_weights["A"] == pytest.approx(0.20)+ assert result.capped_symbols == ("A",)+++def test_names_only_in_one_vector_are_still_trades():+ result = apply_adv_capacity(+ _w(NEW=0.1), _w(OLD=0.1), _w(NEW=1e12, OLD=1e12), capital=1e6+ )+ assert result.achieved_weights["NEW"] == pytest.approx(0.1)+ assert result.achieved_weights["OLD"] == pytest.approx(0.0)+++def test_higher_participation_allows_more_to_trade():+ args = (_w(A=0.30), _w(A=0.0), _w(A=1_000_000.0))+ tight = apply_adv_capacity(*args, capital=1_000_000.0, max_participation=0.05)+ loose = apply_adv_capacity(*args, capital=1_000_000.0, max_participation=0.20)+ assert loose.achieved_weights["A"] > tight.achieved_weights["A"]++[email protected]("participation", [0.0, -0.1, 1.5])+def test_bad_participation_rejected(participation):+ with pytest.raises(ValueError, match="max_participation"):+ apply_adv_capacity(+ _w(A=0.1), _w(A=0.0), _w(A=1e9), capital=1e6, max_participation=participation+ )+++def test_non_positive_capital_rejected():+ with pytest.raises(ValueError, match="capital"):+ apply_adv_capacity(_w(A=0.1), _w(A=0.0), _w(A=1e9), capital=0.0)+++# --- borrow ---+++def test_only_the_short_leg_is_charged():+ longs_only = borrow_cost(_w(A=0.5, B=0.5), periods_per_year=252, annual_rate=0.03)+ assert longs_only == 0.0++ with_short = borrow_cost(_w(A=0.5, B=-0.5), periods_per_year=252, annual_rate=0.03)+ assert with_short == pytest.approx(0.5 * 0.03 / 252)+++def test_borrow_scales_with_short_exposure():+ small = borrow_cost(_w(A=-0.1), periods_per_year=252, annual_rate=0.05)+ large = borrow_cost(_w(A=-0.4), periods_per_year=252, annual_rate=0.05)+ assert large == pytest.approx(4 * small)+++def test_periods_per_year_has_no_default_and_changes_the_charge():+ daily = borrow_cost(_w(A=-1.0), periods_per_year=252, annual_rate=0.05)+ monthly = borrow_cost(_w(A=-1.0), periods_per_year=12, annual_rate=0.05)+ assert monthly == pytest.approx(21 * daily)+ with pytest.raises(TypeError):+ borrow_cost(_w(A=-1.0), annual_rate=0.05) # type: ignore[call-arg]+++def test_per_symbol_rates_are_honoured():+ cost = borrow_cost(+ _w(EASY=-0.5, HARD=-0.5),+ periods_per_year=252,+ annual_rate=pd.Series({"EASY": 0.003, "HARD": 0.20}),+ )+ assert cost == pytest.approx((0.5 * 0.003 + 0.5 * 0.20) / 252)+++def test_a_shorted_symbol_with_no_rate_is_an_error_not_a_free_borrow():+ with pytest.raises(ValueError, match="missing a rate"):+ borrow_cost(+ _w(A=-0.5, B=-0.5),+ periods_per_year=252,+ annual_rate=pd.Series({"A": 0.01}),+ )+++def test_market_fallback_uses_the_indicative_table():+ cost = borrow_cost(_w(A=-1.0), periods_per_year=252, market="CN")+ assert cost == pytest.approx(MARKET_BORROW_RATES["CN"] / 252)+++def test_a_shorting_book_with_no_rate_source_at_all_is_an_error():+ with pytest.raises(ValueError, match="supply annual_rate"):+ borrow_cost(_w(A=-0.5), periods_per_year=252)+++def test_unknown_market_rejected():+ with pytest.raises(ValueError, match="unknown market"):+ borrow_cost(_w(A=-0.5), periods_per_year=252, market="MARS")+++def test_negative_borrow_rate_rejected():+ with pytest.raises(ValueError, match="non-negative"):+ borrow_cost(_w(A=-0.5), periods_per_year=252, annual_rate=-0.01)+++# --- the whole point: turnover has to hurt ---+++def test_a_high_turnover_factor_is_eroded_far_more_than_a_low_turnover_one():+ universe = [f"S{i:02d}" for i in range(20)]+ adv = pd.Series(1e12, index=universe) # capacity is not the binding constraint+ flat = pd.Series(0.0, index=universe)++ # Low turnover: the book barely moves.+ low_target = flat.copy()+ low_target.iloc[:10] = 0.10+ low_cost, _ = rebalance_cost(+ low_target, low_target * 0.98, capital=1e8, periods_per_year=252,+ adv_value=adv, impact_model="fixed",+ )++ # High turnover: the book flips entirely.+ high_prev = flat.copy()+ high_prev.iloc[:10] = 0.10+ high_target = flat.copy()+ high_target.iloc[10:] = 0.10+ high_cost, _ = rebalance_cost(+ high_target, high_prev, capital=1e8, periods_per_year=252,+ adv_value=adv, impact_model="fixed",+ )++ assert high_cost.turnover > 20 * low_cost.turnover+ assert high_cost.total_cost > 20 * low_cost.total_cost+++def test_cost_is_a_positive_drag_never_a_signed_adjustment():+ universe = ["A", "B"]+ result, _ = rebalance_cost(+ pd.Series([0.5, -0.5], index=universe),+ pd.Series([0.0, 0.0], index=universe),+ capital=1e8,+ periods_per_year=252,+ adv_value=pd.Series(1e12, index=universe),+ impact_model="fixed",+ borrow_annual_rate=0.03,+ )+ assert result.impact_cost > 0+ assert result.borrow_cost > 0+ assert result.total_cost == pytest.approx(result.impact_cost + result.borrow_cost)+++def test_capacity_limits_show_up_as_unfilled_turnover():+ result, capacity = rebalance_cost(+ _w(A=0.50),+ _w(A=0.0),+ capital=1_000_000.0,+ periods_per_year=252,+ adv_value=_w(A=1_000_000.0),+ impact_model="fixed",+ )+ assert result.turnover == pytest.approx(0.10)+ assert result.unfilled_turnover == pytest.approx(0.40)+ assert result.capped_symbols == ("A",)+ assert capacity is not None+++def test_no_adv_means_no_cap_and_that_is_an_assumption_of_infinite_liquidity():+ result, capacity = rebalance_cost(+ _w(A=0.50), _w(A=0.0), capital=1_000.0, periods_per_year=252,+ impact_model="fixed",+ )+ assert capacity is None+ assert result.unfilled_turnover == 0.0+ assert result.capped_symbols == ()+++def test_sqrt_model_needs_a_volatility():+ with pytest.raises(ValueError, match="needs a volatility"):+ rebalance_cost(+ _w(A=0.1), _w(A=0.0), capital=1e6, periods_per_year=252,+ adv_value=_w(A=1e9), impact_model="sqrt",+ )+++def test_sqrt_impact_grows_with_participation():+ args = dict(capital=1e8, periods_per_year=252, impact_model="sqrt", volatility=0.02)+ thin, _ = rebalance_cost(_w(A=0.05), _w(A=0.0), adv_value=_w(A=1e8), **args)+ thick, _ = rebalance_cost(_w(A=0.05), _w(A=0.0), adv_value=_w(A=1e12), **args)+ # The same trade against a thinner book is a larger share of volume, so it+ # costs more.+ assert thin.impact_cost > thick.impact_cost+++def test_unknown_impact_model_rejected():+ with pytest.raises(ValueError, match="impact_model"):+ rebalance_cost(+ _w(A=0.1), _w(A=0.0), capital=1e6, periods_per_year=252,+ impact_model="magic",+ )+++def test_zero_turnover_costs_nothing_but_borrow():+ held = _w(A=0.5, B=-0.5)+ result, _ = rebalance_cost(+ held, held, capital=1e8, periods_per_year=252,+ adv_value=_w(A=1e12, B=1e12), impact_model="fixed",+ borrow_annual_rate=0.03,+ )+ assert result.turnover == pytest.approx(0.0)+ assert result.impact_cost == pytest.approx(0.0)+ assert result.borrow_cost > 0+++def test_borrow_is_charged_on_the_achieved_book_not_the_requested_one():+ # The cap stops the short from being fully established, so the borrow charge+ # must be on what was actually shorted.+ result, _ = rebalance_cost(+ _w(A=-0.50), _w(A=0.0), capital=1_000_000.0, periods_per_year=252,+ adv_value=_w(A=1_000_000.0), impact_model="fixed", borrow_annual_rate=0.10,+ )+ assert result.borrow_cost == pytest.approx(0.10 * 0.10 / 252)diff --git a/agent/tests/test_governance.py b/agent/tests/test_governance.pynew file mode 100644index 000000000..1474705b6--- /dev/null+++ b/agent/tests/test_governance.py@@ -0,0 +1,774 @@+"""Tests for src/governance/ (run manifest + hash-chained ledger).++Focus: manifest hashing is deterministic over composition and sensitive to+every composition dimension (system prompt / skills / tools / package+versions / extra) while being INSENSITIVE to run_id/timestamp; the ledger's+tamper detection is proven with negative (tampered/deleted) fixtures, not+just a happy-path pass; fsync is actually invoked on the write path; and the+pre-existing src/live/audit.py public contract keeps working unchanged.+"""++from __future__ import annotations++import ast+import inspect+import json+from pathlib import Path++import pytest++from src.governance import ledger as ledger_mod+from src.governance import manifest as manifest_mod+from src.governance.ledger import (+ ChainVerificationResult,+ LedgerCorruptionError,+ append_record,+ build_export,+ verify_chain,+ verify_export,+)+from src.governance.manifest import (+ RunManifest,+ build_run_manifest,+ collect_key_package_versions,+ diff_manifests,+)+from src.live import audit+from src.live import paths as live_paths+from src.live.audit import LiveActionEvent, write_live_action+++# ---------------------------------------------------------------------------+# No hidden clock (source-level assertion, both new modules).+# ---------------------------------------------------------------------------++[email protected]("module", [manifest_mod, ledger_mod])+def test_no_hidden_clock_in_source(module) -> None:+ """Neither governance module may call datetime.now()/time.time() itself.++ Timestamps must always be caller-supplied (manifest) or simply absent+ (ledger has no timestamp concept at all). A source-level AST walk is+ used rather than a substring grep so a comment/docstring mentioning+ "time.time()" cannot cause a false failure and, more importantly, an+ actual call cannot hide behind reformatting.+ """+ source = inspect.getsource(module)+ tree = ast.parse(source)+ offending: list[str] = []+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call):+ continue+ func = node.func+ dotted = None+ if isinstance(func, ast.Attribute):+ if isinstance(func.value, ast.Name):+ dotted = f"{func.value.id}.{func.attr}"+ elif isinstance(func, ast.Name):+ dotted = func.id+ if dotted in {"datetime.now", "time.time", "now"}:+ offending.append(dotted)+ assert offending == [], f"{module.__name__} calls a hidden clock: {offending}"+++# ---------------------------------------------------------------------------+# manifest.py+# ---------------------------------------------------------------------------+++def _base_manifest_kwargs() -> dict:+ return dict(+ run_id="run-1",+ timestamp="2026-08-06T00:00:00.000+00:00",+ system_prompt="You are a trading research agent.",+ skills={+ "tushare": "tushare skill body v1",+ "risk-committee": "risk committee lens body v1",+ },+ tool_names=["get_market_data", "backtest", "cashflow_performance"],+ package_versions={"numpy": "2.4.4", "pandas": "2.3.3"},+ extra={"provider": "openrouter", "model": "deepseek/deepseek-v3.2"},+ )+++def test_manifest_hash_deterministic_for_same_composition() -> None:+ """Building twice from identical composition yields the identical hash."""+ m1 = build_run_manifest(**_base_manifest_kwargs())+ m2 = build_run_manifest(**_base_manifest_kwargs())+ assert m1.manifest_hash == m2.manifest_hash+ assert m1.manifest_hash.startswith("sha256:")+++def test_manifest_hash_ignores_run_id_and_timestamp() -> None:+ """Same composition, different run_id/timestamp -> SAME manifest_hash.++ This locks in the documented design choice: manifest_hash fingerprints+ the METHODOLOGY, not the particular execution instance, so re-running+ identical methodology on a different day is recognizable as "unchanged".+ """+ kwargs_a = _base_manifest_kwargs()+ kwargs_b = {**_base_manifest_kwargs(), "run_id": "run-2", "timestamp": "2099-01-01T00:00:00.000+00:00"}+ m1 = build_run_manifest(**kwargs_a)+ m2 = build_run_manifest(**kwargs_b)+ assert m1.manifest_hash == m2.manifest_hash+ assert m1.run_id != m2.run_id+ assert m1.timestamp != m2.timestamp+++def test_manifest_hash_changes_when_a_skill_content_changes() -> None:+ """Editing one skill's body changes manifest_hash and is named by diff."""+ baseline = build_run_manifest(**_base_manifest_kwargs())++ kwargs = _base_manifest_kwargs()+ kwargs["skills"] = {**kwargs["skills"], "tushare": "tushare skill body v2 (edited)"}+ changed = build_run_manifest(**kwargs)++ assert changed.manifest_hash != baseline.manifest_hash+ diff = diff_manifests(baseline, changed)+ assert diff.skills_changed == ("tushare",)+ assert diff.skills_added == ()+ assert diff.skills_removed == ()+ assert diff.manifest_hash_changed is True+ assert diff.unchanged is False+++def test_manifest_hash_changes_when_system_prompt_changes() -> None:+ baseline = build_run_manifest(**_base_manifest_kwargs())+ kwargs = _base_manifest_kwargs()+ kwargs["system_prompt"] = "You are a trading research agent. (v2)"+ changed = build_run_manifest(**kwargs)++ assert changed.manifest_hash != baseline.manifest_hash+ assert changed.system_prompt_hash != baseline.system_prompt_hash+ diff = diff_manifests(baseline, changed)+ assert diff.system_prompt_changed is True+++def test_manifest_hash_changes_when_tool_registry_changes() -> None:+ baseline = build_run_manifest(**_base_manifest_kwargs())+ kwargs = _base_manifest_kwargs()+ kwargs["tool_names"] = [*kwargs["tool_names"], "options_payoff"]+ changed = build_run_manifest(**kwargs)++ assert changed.manifest_hash != baseline.manifest_hash+ diff = diff_manifests(baseline, changed)+ assert diff.tools_added == ("options_payoff",)+ assert diff.tools_removed == ()+++def test_manifest_hash_changes_when_package_version_changes() -> None:+ baseline = build_run_manifest(**_base_manifest_kwargs())+ kwargs = _base_manifest_kwargs()+ kwargs["package_versions"] = {**kwargs["package_versions"], "numpy": "2.5.0"}+ changed = build_run_manifest(**kwargs)++ assert changed.manifest_hash != baseline.manifest_hash+ diff = diff_manifests(baseline, changed)+ assert diff.package_version_changes == (("numpy", "2.4.4", "2.5.0"),)+++def test_manifest_hash_changes_when_extra_changes() -> None:+ baseline = build_run_manifest(**_base_manifest_kwargs())+ kwargs = _base_manifest_kwargs()+ kwargs["extra"] = {**kwargs["extra"], "model": "deepseek/deepseek-v3.3"}+ changed = build_run_manifest(**kwargs)++ assert changed.manifest_hash != baseline.manifest_hash+ diff = diff_manifests(baseline, changed)+ assert diff.extra_changes == (("model", "deepseek/deepseek-v3.2", "deepseek/deepseek-v3.3"),)+++def test_manifest_diff_reports_no_changes_for_identical_composition() -> None:+ a = build_run_manifest(**_base_manifest_kwargs())+ b = build_run_manifest(**{**_base_manifest_kwargs(), "run_id": "other-run"})+ diff = diff_manifests(a, b)+ assert diff.unchanged is True+ assert diff.manifest_hash_changed is False+++def test_manifest_serialization_round_trip() -> None:+ original = build_run_manifest(**_base_manifest_kwargs())++ via_dict = RunManifest.from_dict(original.to_dict())+ assert via_dict == original+ assert via_dict.verify_hash() is True++ via_json = RunManifest.from_json(original.to_json())+ assert via_json == original+ assert via_json.verify_hash() is True+++def test_manifest_verify_hash_detects_tampering_after_deserialize() -> None:+ original = build_run_manifest(**_base_manifest_kwargs())+ data = original.to_dict()+ # Tamper: swap in a different skill hash without recomputing manifest_hash.+ data["skills"][0]["content_hash"] = "sha256:" + "0" * 64+ tampered = RunManifest.from_dict(data)+ assert tampered.verify_hash() is False+++def test_manifest_rejects_duplicate_skill_names_in_sequence_form() -> None:+ from src.governance.manifest import SkillRecord++ with pytest.raises(ValueError):+ build_run_manifest(+ run_id="r1",+ timestamp="t1",+ system_prompt="p",+ skills=[+ SkillRecord.from_content("dup", "a"),+ SkillRecord.from_content("dup", "b"),+ ],+ )+++def test_manifest_rejects_empty_run_id_or_timestamp() -> None:+ kwargs = _base_manifest_kwargs()+ with pytest.raises(ValueError):+ build_run_manifest(**{**kwargs, "run_id": ""})+ with pytest.raises(ValueError):+ build_run_manifest(**{**kwargs, "timestamp": " "})+++def test_collect_key_package_versions_reflects_real_environment() -> None:+ """Sanity check against the actual installed environment (no mocking).++ vibe-trading-ai is installed editable in this checkout (pyproject.toml+ pins 0.1.13 at the time this test was written); numpy is a hard+ dependency so it must resolve; arch is an optional 'stats' extra that is+ NOT installed in this environment, proving the None-when-absent path is+ real, not merely a documented intent.+ """+ versions = collect_key_package_versions()+ assert versions["numpy"] is not None+ assert versions["vibe-trading-ai"] is not None+ assert "python" in versions and versions["python"]+ # Not asserting a specific arch install state (that is an environment+ # fact, not a manifest.py contract) -- but the key must be present.+ assert "arch" in versions+++# ---------------------------------------------------------------------------+# ledger.py — happy path+# ---------------------------------------------------------------------------+++def test_append_record_chains_sequential_records(tmp_path: Path) -> None:+ path = tmp_path / "chain.jsonl"+ records = [append_record(path, {"n": i}) for i in range(5)]++ assert [r["seq"] for r in records] == [1, 2, 3, 4, 5]+ assert records[0]["prev_record_hash"] == ledger_mod.GENESIS_PREV_HASH+ for earlier, later in zip(records, records[1:]):+ assert later["prev_record_hash"] == earlier["record_hash"]++ result = verify_chain(path)+ assert result.ok is True+ assert result.record_count == 5+ assert result.first_break is None+++def test_append_record_rejects_reserved_payload_keys(tmp_path: Path) -> None:+ path = tmp_path / "chain.jsonl"+ with pytest.raises(ValueError):+ append_record(path, {"seq": 99, "note": "hijack"})+++def test_verify_chain_on_missing_file_is_trivially_ok(tmp_path: Path) -> None:+ result = verify_chain(tmp_path / "does_not_exist.jsonl")+ assert result == ChainVerificationResult(ok=True, record_count=0, first_break=None)+++# ---------------------------------------------------------------------------+# ledger.py — tamper detection (negative-case driven, per task requirement)+# ---------------------------------------------------------------------------+++def _write_five_records(path: Path) -> list[dict]:+ return [append_record(path, {"label": f"record-{i}", "amount": i * 10}) for i in range(5)]+++def test_tamper_editing_one_record_content_is_pinpointed(tmp_path: Path) -> None:+ """The core negative case: hand-edit ONE record's payload, leave its+ stored seq/prev_record_hash/record_hash untouched, and assert+ verify_chain names exactly that record -- not merely "broken somewhere".+ """+ path = tmp_path / "chain.jsonl"+ _write_five_records(path)++ lines = path.read_text(encoding="utf-8").splitlines()+ assert len(lines) == 5+ tampered_index = 2 # the 3rd record (seq=3), 0-based line index 2+ record = json.loads(lines[tampered_index])+ assert record["seq"] == 3+ original_amount = record["amount"]+ record["amount"] = original_amount + 999 # tamper the payload only+ lines[tampered_index] = json.dumps(record, ensure_ascii=False)+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")++ result = verify_chain(path)+ assert result.ok is False+ assert result.first_break is not None+ assert result.first_break.index == tampered_index+ assert result.first_break.seq == 3+ assert result.first_break.reason == "record_hash_mismatch"+ # Records before the tamper are still counted as verified.+ assert result.record_count == 2+++def test_tamper_deleting_a_middle_record_is_detected(tmp_path: Path) -> None:+ """Removing a whole line (not just editing content) must also be caught."""+ path = tmp_path / "chain.jsonl"+ _write_five_records(path)++ lines = path.read_text(encoding="utf-8").splitlines()+ assert len(lines) == 5+ deleted_index = 1 # remove the 2nd record (seq=2)+ del lines[deleted_index]+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")++ result = verify_chain(path)+ assert result.ok is False+ assert result.first_break is not None+ # After deleting seq=2, the next physical line is the original seq=3+ # record, which the walk encounters while still expecting seq=2.+ assert result.first_break.index == deleted_index+ assert result.first_break.seq == 3+ assert result.first_break.reason == "seq_gap"+ assert result.record_count == 1+++def test_tamper_that_also_fixes_its_own_hash_is_still_caught_downstream(tmp_path: Path) -> None:+ """A more sophisticated tamper: edit a record's payload AND recompute+ that record's own record_hash so it is internally self-consistent. The+ chain must still catch this -- not at the tampered record (which now+ looks locally valid) but at the very next record, whose stored+ prev_record_hash still points at the ORIGINAL (pre-tamper) hash.+ """+ path = tmp_path / "chain.jsonl"+ _write_five_records(path)++ lines = path.read_text(encoding="utf-8").splitlines()+ tampered_index = 2 # seq=3+ record = json.loads(lines[tampered_index])+ record["amount"] = -1+ payload = {k: v for k, v in record.items() if k not in {"seq", "prev_record_hash", "record_hash"}}+ record["record_hash"] = ledger_mod.compute_record_hash(+ record["seq"], record["prev_record_hash"], payload+ )+ lines[tampered_index] = json.dumps(record, ensure_ascii=False)+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")++ result = verify_chain(path)+ assert result.ok is False+ assert result.first_break is not None+ assert result.first_break.index == tampered_index + 1 # the NEXT record, seq=4+ assert result.first_break.seq == 4+ assert result.first_break.reason == "prev_hash_mismatch"+ # The tampered record itself (seq=3) still counts as "verified" in+ # isolation -- proving the propagation, not a local check, is what+ # catches this class of tamper.+ assert result.record_count == 3+++def test_only_asserting_untampered_pass_would_be_insufficient_so_also_assert_ok_baseline(+ tmp_path: Path,+) -> None:+ """Companion positive control for the negative tests above: confirms the+ SAME 5-record fixture verifies clean before any tampering, so the+ negative tests above are proven to detect the tamper itself and not+ some unrelated fixture bug.+ """+ path = tmp_path / "chain.jsonl"+ _write_five_records(path)+ assert verify_chain(path) == ChainVerificationResult(ok=True, record_count=5, first_break=None)+++def test_append_record_refuses_to_extend_an_already_broken_chain(tmp_path: Path) -> None:+ path = tmp_path / "chain.jsonl"+ _write_five_records(path)+ lines = path.read_text(encoding="utf-8").splitlines()+ record = json.loads(lines[2])+ record["amount"] = 999999+ lines[2] = json.dumps(record, ensure_ascii=False)+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")++ with pytest.raises(LedgerCorruptionError) as excinfo:+ append_record(path, {"label": "record-5-attempt"})+ assert excinfo.value.chain_break.index == 2+ assert excinfo.value.chain_break.reason == "record_hash_mismatch"++ # And the file was NOT extended with a 6th record.+ assert len(path.read_text(encoding="utf-8").splitlines()) == 5+++# ---------------------------------------------------------------------------+# ledger.py — fsync+# ---------------------------------------------------------------------------+++def test_append_record_calls_os_fsync(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ import os as os_mod++ calls: list[int] = []+ real_fsync = os_mod.fsync++ def counting_fsync(fd: int) -> None:+ calls.append(fd)+ real_fsync(fd)++ monkeypatch.setattr(os_mod, "fsync", counting_fsync)++ path = tmp_path / "chain.jsonl"+ append_record(path, {"n": 1})+ # At least one fsync for the record write itself (plus one for the+ # parent directory entry, since this is the first write to a new file).+ assert len(calls) >= 1+++def test_append_record_skips_fsync_when_disabled(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ import os as os_mod++ calls: list[int] = []+ monkeypatch.setattr(os_mod, "fsync", lambda fd: calls.append(fd))++ path = tmp_path / "chain.jsonl"+ append_record(path, {"n": 1}, fsync=False)+ assert calls == []+++# ---------------------------------------------------------------------------+# ledger.py — export / offline verification+# ---------------------------------------------------------------------------+++def test_export_is_self_contained_and_offline_verifiable(tmp_path: Path) -> None:+ path = tmp_path / "chain.jsonl"+ _write_five_records(path)++ export = build_export(path)+ assert export["record_count"] == 5+ assert export["verification"]["ok"] is True++ # Delete the SOURCE ledger entirely -- verify_export must not need it.+ path.unlink()+ result = verify_export(export)+ assert result.ok is True+ assert result.record_count == 5+++def test_export_to_file_round_trips(tmp_path: Path) -> None:+ from src.governance.ledger import export_chain_to_file++ path = tmp_path / "chain.jsonl"+ _write_five_records(path)+ dest = tmp_path / "export.json"+ export_chain_to_file(path, dest)++ loaded = json.loads(dest.read_text(encoding="utf-8"))+ result = verify_export(loaded)+ assert result.ok is True+ result_from_path = verify_export(dest)+ assert result_from_path.ok is True+++def test_verify_export_detects_tampered_embedded_record(tmp_path: Path) -> None:+ path = tmp_path / "chain.jsonl"+ _write_five_records(path)+ export = build_export(path)++ export["records"][2]["amount"] = -1 # tamper without fixing export_hash+ result = verify_export(export)+ assert result.ok is False+ assert result.first_break.reason == "export_hash_mismatch"+++def test_verify_export_detects_tampered_envelope_hash_directly(tmp_path: Path) -> None:+ path = tmp_path / "chain.jsonl"+ _write_five_records(path)+ export = build_export(path)++ export["export_hash"] = "sha256:" + "f" * 64+ result = verify_export(export)+ assert result.ok is False+ assert result.first_break.reason == "export_hash_mismatch"+ assert result.first_break.index == -1+++# ---------------------------------------------------------------------------+# src/live/audit.py — backward compatibility + new capabilities+# ---------------------------------------------------------------------------+++def live_runtime(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ """Point the live runtime root at an isolated tmp dir (mirrors test_audit_redact.py)."""+ monkeypatch.setattr(live_paths, "get_runtime_root", lambda: tmp_path)+ return tmp_path+++def _read_jsonl(path: Path) -> list[dict]:+ if not path.exists():+ return []+ return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]+++def test_default_write_live_action_shape_is_unchanged(live_runtime: Path) -> None:+ """Backward compat under the 2026-08-06 default flip.++ The chain is now written on every call, but the classic ledger line and the+ RETURN VALUE must stay byte-identical to what callers already depend on --+ the three chain fields belong to the chain file alone.+ """+ rec = write_live_action(+ LiveActionEvent(kind="order_placed", session_id="s1", outcome="accepted", server="robinhood")+ )+ assert "seq" not in rec+ assert "prev_record_hash" not in rec+ assert "record_hash" not in rec++ written = _read_jsonl(audit.audit_ledger_path())+ assert len(written) == 1+ assert written[0] == rec+ assert "seq" not in written[0]++ # And the chained copy exists alongside it, carrying the same payload.+ chained = _read_jsonl(audit.audit_chain_ledger_path())+ assert len(chained) == 1+ assert chained[0]["seq"] == 1+ assert {k: v for k, v in chained[0].items()+ if k not in ("seq", "prev_record_hash", "record_hash")} == rec+++def test_chain_false_writes_only_the_classic_ledger(live_runtime: Path) -> None:+ """The opt-out still exists and still means what it says."""+ write_live_action(+ LiveActionEvent(kind="order_placed", session_id="s1", outcome="accepted", server="robinhood"),+ chain=False,+ )+ assert len(_read_jsonl(audit.audit_ledger_path())) == 1+ assert not audit.audit_chain_ledger_path().exists()+++def test_default_write_live_action_now_fsyncs(live_runtime: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """The durability fix: even the CLASSIC (chain=False) path must fsync now,+ closing the gap with src.agent.trace.TraceWriter noted in the audit.py+ docstring update."""+ import os as os_mod++ calls: list[int] = []+ real_fsync = os_mod.fsync++ def counting_fsync(fd: int) -> None:+ calls.append(fd)+ real_fsync(fd)++ monkeypatch.setattr(os_mod, "fsync", counting_fsync)++ write_live_action(+ LiveActionEvent(kind="order_placed", session_id="s1", outcome="accepted", server="robinhood")+ )+ assert len(calls) >= 1+++def test_chain_true_writes_to_dedicated_chain_ledger(live_runtime: Path) -> None:+ for i in range(3):+ write_live_action(+ LiveActionEvent(+ kind="order_placed",+ session_id="s1",+ outcome="accepted",+ server="robinhood",+ intent_normalized=f"order {i}",+ ),+ chain=True,+ )++ # Both ledgers are written: the classic one keeps every existing reader+ # working, the chained one adds tamper-evidence.+ assert len(_read_jsonl(audit.audit_ledger_path())) == 3++ chained = _read_jsonl(audit.audit_chain_ledger_path())+ assert len(chained) == 3+ assert [r["seq"] for r in chained] == [1, 2, 3]+ result = verify_chain(audit.audit_chain_ledger_path())+ assert result.ok is True+ assert result.record_count == 3+++def test_chain_true_fans_the_same_augmented_record_to_all_sinks(live_runtime: Path) -> None:+ trace_entries: list[dict] = []+ captured: list[tuple] = []++ rec = write_live_action(+ LiveActionEvent(+ kind="order_placed",+ session_id="s1",+ outcome="accepted",+ server="robinhood",+ broker_request={"symbol": "NVDA", "token": "leak-me"},+ ),+ chain=True,+ trace_writer=type("T", (), {"write": lambda self, e: trace_entries.append(e)})(),+ event_callback=lambda name, payload: captured.append((name, payload)),+ )++ # The chain fields live in the chain FILE only. The return value, the+ # trace entry and the surface payload stay the classic record, so nothing+ # that already parses those three breaks.+ assert "seq" not in rec+ assert rec["broker_request"]["token"] == "[redacted]"++ ledger_rec = _read_jsonl(audit.audit_chain_ledger_path())[0]+ assert ledger_rec["seq"] == 1+ assert {k: v for k, v in ledger_rec.items()+ if k not in ("seq", "prev_record_hash", "record_hash")} == rec++ assert trace_entries[0]["type"] == "live_action"+ assert "seq" not in trace_entries[0]+ # Redaction still happens BEFORE any sink, including the chained one.+ assert trace_entries[0]["broker_request"]["token"] == "[redacted]"+ assert ledger_rec["broker_request"]["token"] == "[redacted]"++ assert captured[0] == ("live.action", rec)+++def test_chain_true_refuses_to_extend_a_tampered_chain_ledger(live_runtime: Path) -> None:+ for i in range(3):+ write_live_action(+ LiveActionEvent(kind="order_placed", session_id="s1", outcome="accepted", server="robinhood"),+ chain=True,+ )++ chain_path = audit.audit_chain_ledger_path()+ lines = chain_path.read_text(encoding="utf-8").splitlines()+ record = json.loads(lines[1])+ record["session_id"] = "hijacked"+ lines[1] = json.dumps(record, ensure_ascii=False)+ chain_path.write_text("\n".join(lines) + "\n", encoding="utf-8")++ # A corrupt chain must NOT take down the order path. The compliance record+ # still lands in the classic ledger (nothing is lost), the failure is+ # logged, and the break stays detectable -- which is the whole justification+ # for swallowing it rather than raising into an in-flight order.+ before = len(_read_jsonl(audit.audit_ledger_path()))+ returned = write_live_action(+ LiveActionEvent(kind="order_placed", session_id="s1", outcome="accepted", server="robinhood"),+ chain=True,+ )+ after = _read_jsonl(audit.audit_ledger_path())+ assert len(after) == before + 1, "the classic record must survive a chain failure"+ assert after[-1] == returned++ # And the tamper is still reported, at the record that was edited.+ result = verify_chain(chain_path)+ assert result.ok is False+ assert result.first_break.index == 1++ # append_record itself still refuses -- the guard is intact, it is just no+ # longer allowed to propagate into the order path.+ with pytest.raises(LedgerCorruptionError):+ append_record(chain_path, {"action": "direct"})+++# --- retention: rotate, never delete ---+++def test_rotation_seals_a_segment_and_keeps_the_active_file_small(tmp_path):+ from src.governance.ledger import archive_segments, rotate_if_needed++ led = tmp_path / "audit_chain.jsonl"+ for i in range(5):+ append_record(led, {"action": "order", "n": i})++ archive = rotate_if_needed(led, max_bytes=100)++ assert archive is not None+ assert archive_segments(led) == [archive]+ assert not led.exists() # sealed; the next append starts a fresh active file+++def test_rotation_does_not_delete_anything(tmp_path):+ # The whole retention policy in one assertion: history is never destroyed.+ from src.governance.ledger import rotate_if_needed++ led = tmp_path / "audit_chain.jsonl"+ for i in range(5):+ append_record(led, {"action": "order", "n": i})+ before = led.read_text()++ archive = rotate_if_needed(led, max_bytes=100)+ assert archive.read_text() == before+++def test_the_chain_continues_across_a_rotation(tmp_path):+ from src.governance.ledger import rotate_if_needed, verify_chain_with_archives++ led = tmp_path / "audit_chain.jsonl"+ for i in range(5):+ append_record(led, {"action": "order", "n": i})+ rotate_if_needed(led, max_bytes=100)+ for i in range(5, 9):+ append_record(led, {"action": "order", "n": i})++ # Not a fresh chain: the active file picks up at seq 6.+ seqs = [json.loads(line)["seq"] for line in led.read_text().splitlines()]+ assert seqs == [6, 7, 8, 9]++ result = verify_chain_with_archives(led)+ assert result.ok is True+ assert result.record_count == 9+++def test_deleting_a_whole_sealed_segment_is_detected(tmp_path):+ # This is what rotation would have cost us if the chain restarted: a+ # segment could be removed wholesale and each remaining file would still+ # verify on its own.+ from src.governance.ledger import rotate_if_needed, verify_chain_with_archives++ led = tmp_path / "audit_chain.jsonl"+ for i in range(5):+ append_record(led, {"action": "order", "n": i})+ archive = rotate_if_needed(led, max_bytes=100)+ for i in range(5, 9):+ append_record(led, {"action": "order", "n": i})++ archive.unlink()++ result = verify_chain_with_archives(led)+ assert result.ok is False+ assert result.first_break.reason == "seq_gap"+++def test_rotation_refuses_to_seal_a_corrupt_ledger(tmp_path):+ from src.governance.ledger import rotate_if_needed++ led = tmp_path / "audit_chain.jsonl"+ for i in range(5):+ append_record(led, {"action": "order", "n": i})+ lines = led.read_text().splitlines()+ record = json.loads(lines[2])+ record["n"] = 999+ lines[2] = json.dumps(record)+ led.write_text("\n".join(lines) + "\n")++ with pytest.raises(LedgerCorruptionError):+ rotate_if_needed(led, max_bytes=100)+++def test_rotation_is_a_no_op_below_the_threshold(tmp_path):+ from src.governance.ledger import rotate_if_needed++ led = tmp_path / "audit_chain.jsonl"+ append_record(led, {"action": "order"})+ assert rotate_if_needed(led, max_bytes=10_000_000) is None+ assert led.exists()+++def test_rotation_rejects_a_non_positive_threshold(tmp_path):+ from src.governance.ledger import rotate_if_needed++ led = tmp_path / "audit_chain.jsonl"+ append_record(led, {"action": "order"})+ with pytest.raises(ValueError, match="max_bytes"):+ rotate_if_needed(led, max_bytes=0)diff --git a/agent/tests/test_orderbook_depth_tool.py b/agent/tests/test_orderbook_depth_tool.pynew file mode 100644index 000000000..b451d5903--- /dev/null+++ b/agent/tests/test_orderbook_depth_tool.py@@ -0,0 +1,411 @@+"""Tests for orderbook_depth_tool: validation, spread/imbalance/impact math, edge cases.++No test ever reaches a live exchange. The tool isolates the network call in+its own module-level function, ``_fetch_raw_book`` — see the tool's module+docstring — and every test here monkeypatches exactly that name on the+``orderbook_depth_tool`` module, mirroring the pattern already used in+``tests/test_prediction_market_tool.py`` (monkeypatch ``throttled_get_json``+on its own tool module rather than mocking ``requests`` globally).++Fixture books use small integer prices/quantities specifically so the impact+walk's expected outputs can be hand-computed with exact arithmetic (verified+independently with ``decimal.Decimal`` outside the test, then hardcoded as+literals below) and asserted to 1e-9 rather than merely "looks plausible".+"""++from __future__ import annotations++import json+from typing import Any++import pytest++from src.tools import orderbook_depth_tool+from src.tools.orderbook_depth_tool import OrderBookDepthTool+++def _raw_book(+ bids: list[list[float]],+ asks: list[list[float]],+ *,+ timestamp: float | None = None,+) -> dict[str, Any]:+ """Build a ccxt-shaped OrderBook dict, as ``fetch_order_book`` returns it."""+ return {+ "symbol": "BTC/USDT",+ "bids": bids,+ "asks": asks,+ "timestamp": timestamp,+ "datetime": None,+ "nonce": None,+ }+++def _install(monkeypatch: pytest.MonkeyPatch, book: dict[str, Any]) -> list[tuple[str, str, int]]:+ """Monkeypatch ``_fetch_raw_book`` to return ``book`` and record call args."""+ calls: list[tuple[str, str, int]] = []++ def fake_fetch(exchange_id: str, ccxt_symbol: str, limit: int) -> dict[str, Any]:+ calls.append((exchange_id, ccxt_symbol, limit))+ return book++ monkeypatch.setattr(orderbook_depth_tool, "_fetch_raw_book", fake_fetch)+ return calls+++def _run(**kwargs: Any) -> dict[str, Any]:+ return json.loads(OrderBookDepthTool().execute(**kwargs))+++# ---------------------------------------------------------------------------+# The four-level book used for the impact-cost hand-calc tests.+#+# asks (ascending): 100@1, 101@1, 102@1, 103@1 -> total ask depth = 4 base+# bids (descending): 99@1, 98@1, 97@1, 96@1 -> total bid depth = 4 base+# mid = (100 + 99) / 2 = 99.5+#+# Every expected number below was computed independently with+# decimal.Decimal (not by calling the tool) and is asserted to 1e-9:+#+# Case A (notional=199 -> base_qty_target=199/99.5=2.0 exactly, a clean+# 2-level fill on both sides):+# BUY: take 1@100 + 1@101 = 201 quote for 2.0 base -> avg=100.5+# slippage_bps = (100.5-99.5)/99.5*10000 = 100.502512562814070...+# SELL: take 1@99 + 1@98 = 197 quote for 2.0 base -> avg=98.5+# slippage_bps = (99.5-98.5)/99.5*10000 = 100.502512562814070...+#+# Case B (base_qty_target=2.5 -> notional=248.75, a partial 3rd-level fill):+# BUY: 1@100 + 1@101 + 0.5@102 = 100+101+51 = 252 quote for 2.5 base+# avg=100.8, slippage_bps=(100.8-99.5)/99.5*10000=130.653266331658...+#+# Case C (base_qty_target=10, exceeds the entire 4-base ask ladder):+# BUY: all 4 asks = 100+101+102+103=406 quote for 4.0 base, avg=101.5+# fully_filled=False, unfilled_base_qty=6.0+# slippage_bps=(101.5-99.5)/99.5*10000=201.005025125628140...+# ---------------------------------------------------------------------------+_ASKS = [[100, 1], [101, 1], [102, 1], [103, 1]]+_BIDS = [[99, 1], [98, 1], [97, 1], [96, 1]]+++def test_impact_cost_exact_two_level_fill_buy_and_sell(monkeypatch: pytest.MonkeyPatch) -> None:+ """Case A: notional lands exactly on a level boundary on both sides."""+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT", notional_quote=199, levels=4)++ assert result["ok"] is True+ impact = result["data"]["impact_cost"]+ assert impact["base_qty_target"] == pytest.approx(2.0, abs=1e-9)++ buy = impact["buy"]+ assert buy["fully_filled"] is True+ assert buy["filled_base_qty"] == pytest.approx(2.0, abs=1e-9)+ assert buy["filled_notional_quote"] == pytest.approx(201.0, abs=1e-9)+ assert buy["avg_price"] == pytest.approx(100.5, abs=1e-9)+ assert buy["slippage_bps"] == pytest.approx(100.502512562814070, abs=1e-9)+ assert buy["levels_used"] == 2+ assert "note" not in buy++ sell = impact["sell"]+ assert sell["fully_filled"] is True+ assert sell["filled_base_qty"] == pytest.approx(2.0, abs=1e-9)+ assert sell["filled_notional_quote"] == pytest.approx(197.0, abs=1e-9)+ assert sell["avg_price"] == pytest.approx(98.5, abs=1e-9)+ assert sell["slippage_bps"] == pytest.approx(100.502512562814070, abs=1e-9)+ assert sell["levels_used"] == 2+ assert "note" not in sell+++def test_impact_cost_partial_level_fill(monkeypatch: pytest.MonkeyPatch) -> None:+ """Case B: the target lands mid-level, exercising fractional level consumption."""+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT", notional_quote=248.75, levels=4)++ buy = result["data"]["impact_cost"]["buy"]+ assert buy["fully_filled"] is True+ assert buy["filled_base_qty"] == pytest.approx(2.5, abs=1e-9)+ assert buy["filled_notional_quote"] == pytest.approx(252.0, abs=1e-9)+ assert buy["avg_price"] == pytest.approx(100.8, abs=1e-9)+ assert buy["slippage_bps"] == pytest.approx(130.653266331658291, abs=1e-9)+ assert buy["levels_used"] == 3+++def test_impact_cost_exceeds_full_book_depth_reports_partial_fill(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Case C: requested notional cannot be filled by the whole fetched ladder.++ This is the "does not fabricate a full fill" requirement: filled_notional+ must reflect only what the book actually had, fully_filled must be False,+ and a note must explain why.+ """+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ # base_qty_target = notional/mid = 995/99.5 = 10.0, but total ask depth is 4.+ result = _run(symbol="BTC-USDT", notional_quote=995, levels=4)++ impact = result["data"]["impact_cost"]+ assert impact["base_qty_target"] == pytest.approx(10.0, abs=1e-9)++ buy = impact["buy"]+ assert buy["fully_filled"] is False+ assert buy["filled_base_qty"] == pytest.approx(4.0, abs=1e-9)+ assert buy["filled_notional_quote"] == pytest.approx(406.0, abs=1e-9)+ assert buy["avg_price"] == pytest.approx(101.5, abs=1e-9)+ assert buy["unfilled_base_qty"] == pytest.approx(6.0, abs=1e-9)+ assert buy["slippage_bps"] == pytest.approx(201.005025125628140, abs=1e-9)+ assert buy["levels_used"] == 4+ assert "note" in buy+ assert "995" in buy["note"]++ # filled_notional_quote (406) must never be conflated with the requested+ # notional_quote_requested (995) — a caller reading only one field must+ # still be able to tell the order was not fully filled.+ assert buy["notional_quote_requested"] == pytest.approx(995.0, abs=1e-9)+ assert buy["filled_notional_quote"] < buy["notional_quote_requested"]+++def test_spread_and_mid_price(monkeypatch: pytest.MonkeyPatch) -> None:+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT")++ data = result["data"]+ assert data["mid_price"] == pytest.approx(99.5, abs=1e-9)+ assert data["best_bid"] == {"price": 99, "amount_base": 1}+ assert data["best_ask"] == {"price": 100, "amount_base": 1}+ assert data["spread"]["absolute_quote"] == pytest.approx(1.0, abs=1e-9)+ # 1 / 99.5 * 10000+ assert data["spread"]["relative_bps"] == pytest.approx(100.502512562814070, abs=1e-9)+++# ---------------------------------------------------------------------------+# Depth imbalance: double-sided guard (balanced -> ~0, thick one side -> big+# and correctly signed), plus a mutation-style check that swapping which side+# is thick flips the sign.+# ---------------------------------------------------------------------------+++def test_imbalance_balanced_book_is_near_zero(monkeypatch: pytest.MonkeyPatch) -> None:+ """99*101 == 101*99, so bid and ask notional are exactly equal -> imbalance == 0."""+ _install(monkeypatch, _raw_book([[99, 101]], [[101, 99]]))+ result = _run(symbol="BTC-USDT", levels=1)++ imbalance = result["data"]["imbalance"]+ assert imbalance["bid_notional_quote"] == pytest.approx(9999.0, abs=1e-9)+ assert imbalance["ask_notional_quote"] == pytest.approx(9999.0, abs=1e-9)+ assert imbalance["normalized_imbalance"] == pytest.approx(0.0, abs=1e-9)+ assert imbalance["ratio_bid_over_ask"] == pytest.approx(1.0, abs=1e-9)+++def test_imbalance_bid_heavy_book_is_large_and_positive(monkeypatch: pytest.MonkeyPatch) -> None:+ _install(+ monkeypatch,+ _raw_book([[99, 1000], [98, 1000]], [[101, 1], [102, 1]]),+ )+ result = _run(symbol="BTC-USDT", levels=2)++ imbalance = result["data"]["imbalance"]+ # bid_notional = 99*1000+98*1000 = 197000; ask_notional = 101+102 = 203+ assert imbalance["bid_notional_quote"] == pytest.approx(197_000.0, abs=1e-9)+ assert imbalance["ask_notional_quote"] == pytest.approx(203.0, abs=1e-9)+ assert imbalance["normalized_imbalance"] > 0.99+ assert imbalance["normalized_imbalance"] <= 1.0+++def test_imbalance_ask_heavy_book_is_large_and_negative(monkeypatch: pytest.MonkeyPatch) -> None:+ """Mutation of the bid-heavy case: swap which side is thick and the sign must flip."""+ _install(+ monkeypatch,+ _raw_book([[99, 1], [98, 1]], [[101, 1000], [102, 1000]]),+ )+ result = _run(symbol="BTC-USDT", levels=2)++ imbalance = result["data"]["imbalance"]+ assert imbalance["normalized_imbalance"] < -0.99+ assert imbalance["normalized_imbalance"] >= -1.0+++# ---------------------------------------------------------------------------+# Timestamp handling: exchange-supplied vs. local-fallback.+# ---------------------------------------------------------------------------+++def test_timestamp_from_exchange(monkeypatch: pytest.MonkeyPatch) -> None:+ _install(monkeypatch, _raw_book(_BIDS, _ASKS, timestamp=1_700_000_000_000))+ result = _run(symbol="BTC-USDT")++ data = result["data"]+ assert data["timestamp"] == "2023-11-14T22:13:20Z"+ assert data["timestamp_source"] == "exchange"+++def test_timestamp_falls_back_to_local_fetch_time_when_venue_has_none(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Binance spot depth carries no server timestamp field (see tool docstring)."""+ _install(monkeypatch, _raw_book(_BIDS, _ASKS, timestamp=None))+ result = _run(symbol="BTC-USDT")++ data = result["data"]+ assert data["timestamp_source"] == "local_fetch_time"+ assert data["timestamp"].endswith("Z")+++def test_exchange_and_symbol_are_always_present(monkeypatch: pytest.MonkeyPatch) -> None:+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="btc-usdt", exchange="binance")++ data = result["data"]+ assert data["exchange"] == "binance"+ assert data["symbol"] == "BTC-USDT"+ assert data["ccxt_symbol"] == "BTC/USDT"+++# ---------------------------------------------------------------------------+# Boundary / error handling — every case must be an explicit `ok: false`+# error, never a plausible-looking number.+# ---------------------------------------------------------------------------+++def test_empty_book_is_rejected(monkeypatch: pytest.MonkeyPatch) -> None:+ _install(monkeypatch, _raw_book([], []))+ result = _run(symbol="BTC-USDT")++ assert result["ok"] is False+ assert "empty" in result["error"].lower()+++def test_one_sided_book_no_bids_is_rejected(monkeypatch: pytest.MonkeyPatch) -> None:+ _install(monkeypatch, _raw_book([], _ASKS))+ result = _run(symbol="BTC-USDT")++ assert result["ok"] is False+ assert "no bids" in result["error"].lower()+++def test_one_sided_book_no_asks_is_rejected(monkeypatch: pytest.MonkeyPatch) -> None:+ _install(monkeypatch, _raw_book(_BIDS, []))+ result = _run(symbol="BTC-USDT")++ assert result["ok"] is False+ assert "no asks" in result["error"].lower()+++def test_crossed_book_is_rejected_not_computed_as_negative_spread(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """best_bid (101) >= best_ask (100): a data error, must refuse outright."""+ _install(monkeypatch, _raw_book([[101, 1]], [[100, 1]]))+ result = _run(symbol="BTC-USDT")++ assert result["ok"] is False+ assert "crossed" in result["error"].lower()+++def test_crossed_book_equal_prices_is_also_rejected(monkeypatch: pytest.MonkeyPatch) -> None:+ """best_bid == best_ask is degenerate (zero/negative spread), not a valid quote."""+ _install(monkeypatch, _raw_book([[100, 1]], [[100, 1]]))+ result = _run(symbol="BTC-USDT")++ assert result["ok"] is False+ assert "crossed" in result["error"].lower()+++def test_notional_exceeding_full_depth_on_both_sides_reports_partial_both_ways(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Symmetric to the buy-side depth-exceeded case, but exercised on sell too."""+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT", notional_quote=995) # base_qty_target = 10 on both sides++ sell = result["data"]["impact_cost"]["sell"]+ assert sell["fully_filled"] is False+ assert sell["filled_base_qty"] == pytest.approx(4.0, abs=1e-9)+ assert sell["unfilled_base_qty"] == pytest.approx(6.0, abs=1e-9)+ assert "note" in sell++[email protected]("levels", [51, 1000, -1, 0])+def test_levels_out_of_bounds_is_rejected(monkeypatch: pytest.MonkeyPatch, levels: int) -> None:+ """N over the cap (or below 1) must be an explicit error, never a silent clamp."""+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT", levels=levels)++ assert result["ok"] is False+ assert "levels" in result["error"].lower()+++def test_levels_at_the_cap_is_accepted(monkeypatch: pytest.MonkeyPatch) -> None:+ """50 is the documented maximum and must not be rejected."""+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT", levels=50)++ assert result["ok"] is True+ assert result["data"]["depth"]["levels"] == 50+ # Only 4 levels actually exist on each side; the response must not+ # fabricate padding rows to reach the requested count.+ assert len(result["data"]["depth"]["bids"]) == 4+ assert len(result["data"]["depth"]["asks"]) == 4++[email protected]("notional", [0, -100, "not-a-number", None])+def test_invalid_notional_is_rejected(monkeypatch: pytest.MonkeyPatch, notional: Any) -> None:+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT", notional_quote=notional)++ assert result["ok"] is False+ assert "notional" in result["error"].lower()+++def test_invalid_exchange_is_rejected_even_bypassing_the_schema_enum(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The JSON-schema enum constrains a well-behaved LLM caller; execute()+ must not trust that and re-validates at runtime."""+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT", exchange="kraken")++ assert result["ok"] is False+ assert "exchange" in result["error"].lower()++[email protected]("symbol", ["BTCUSDT", "BTC-", "-USDT", "BTC-USDT-PERP", "", None, 123])+def test_malformed_symbol_is_rejected(monkeypatch: pytest.MonkeyPatch, symbol: Any) -> None:+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol=symbol)++ assert result["ok"] is False+ assert "symbol" in result["error"].lower()+++def test_fetch_failure_is_surfaced_as_error_envelope(monkeypatch: pytest.MonkeyPatch) -> None:+ def raising_fetch(exchange_id: str, ccxt_symbol: str, limit: int) -> dict[str, Any]:+ raise RuntimeError("simulated network failure")++ monkeypatch.setattr(orderbook_depth_tool, "_fetch_raw_book", raising_fetch)+ result = _run(symbol="BTC-USDT")++ assert result["ok"] is False+ assert "simulated network failure" in result["error"]+++def test_network_is_never_touched(monkeypatch: pytest.MonkeyPatch) -> None:+ """Guard against a future edit silently reintroducing a real network path."""+ calls = _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ _run(symbol="BTC-USDT", exchange="okx", levels=5, notional_quote=1234)++ assert calls == [("okx", "BTC/USDT", orderbook_depth_tool._BOOK_FETCH_LIMIT)]+++def test_units_block_distinguishes_base_and_quote(monkeypatch: pytest.MonkeyPatch) -> None:+ _install(monkeypatch, _raw_book(_BIDS, _ASKS))+ result = _run(symbol="BTC-USDT")++ units = result["units"]+ assert "amount_base" in units+ assert "notional_quote / *_notional_quote / filled_notional_quote" in units+++def test_tool_metadata_is_readonly_and_repeatable() -> None:+ tool = OrderBookDepthTool()+ assert tool.name == "orderbook_depth"+ assert tool.is_readonly is True+ assert tool.repeatable is Truediff --git a/agent/tests/test_quantlib_tool.py b/agent/tests/test_quantlib_tool.pynew file mode 100644index 000000000..5c9fb6321--- /dev/null+++ b/agent/tests/test_quantlib_tool.py@@ -0,0 +1,238 @@+"""Tests for the quantlib_call tool.++The load-bearing tests are the three structural limits. A tool that can reach+arbitrary modules, private helpers, or file writers would be a shell by another+name, which is precisely what this tool exists to avoid.+"""++from __future__ import annotations++import json++import pytest++from src.tools import build_registry+from src.tools.quantlib_tool import ALLOWED_MODULES, QuantlibCallTool+++def tool():+ return QuantlibCallTool()+++def call(tool, **kwargs):+ return json.loads(tool.execute(**kwargs))+++# --- structural limits: this must not be a shell ---+++def test_a_module_outside_the_allowlist_is_unreachable(tool):+ for module in ("os", "subprocess", "builtins", "src.agent.loop", "sys"):+ result = call(tool, action="call", module=module, function="system", kwargs={})+ assert result["ok"] is False+ assert "unknown module" in result["error"]+++def test_the_module_string_never_reaches_importlib(tool):+ # A dotted path that WOULD import if passed through is still refused,+ # because resolution is a dict lookup and not an import.+ result = call(tool, action="call", module="src.quantlib.risk", function="historical_var", kwargs={})+ assert result["ok"] is False+ assert "unknown module" in result["error"]+++def test_private_helpers_are_not_callable(tool):+ for name in ("_clean_returns", "_validate_confidence", "_tail_index"):+ result = call(tool, action="call", module="risk", function=name, kwargs={})+ assert result["ok"] is False+ assert "not a public function" in result["error"]+++def test_dunders_are_not_callable(tool):+ for name in ("__builtins__", "__loader__", "__class__"):+ result = call(tool, action="call", module="risk", function=name, kwargs={})+ assert result["ok"] is False+++def test_file_writing_exporters_are_refused_with_a_reason(tool):+ result = call(tool, action="call", module="valuation.artifact",+ function="export_dcf_workbook", kwargs={})+ assert result["ok"] is False+ assert "writes to a path" in result["error"]+++def test_exporters_are_absent_from_the_listing_too(tool):+ listed = call(tool, action="list", module="valuation.artifact")+ names = {f["name"] for f in listed["functions"]}+ assert not any(n.startswith("export_") for n in names)+++def test_every_allowlisted_module_actually_imports(tool):+ for short in ALLOWED_MODULES:+ result = call(tool, action="list", module=short)+ assert result["ok"] is True, f"{short} failed to list: {result}"+++# --- discovery ---+++def test_list_without_a_module_returns_the_module_set(tool):+ result = call(tool, action="list")+ assert result["ok"] is True+ assert set(result["modules"]) == set(ALLOWED_MODULES)+++def test_list_a_module_returns_functions_with_summaries(tool):+ result = call(tool, action="list", module="risk")+ names = {f["name"] for f in result["functions"]}+ assert {"historical_var", "historical_cvar", "max_drawdown_analysis"} <= names+ assert all(isinstance(f["summary"], str) for f in result["functions"])+++def test_describe_returns_a_signature_and_docstring(tool):+ result = call(tool, action="describe", module="options", function="bs_price")+ assert result["ok"] is True+ assert "S" in result["signature"] and "sigma" in result["signature"]+ assert "Black-Scholes" in result["doc"]+++def test_describe_and_call_require_both_module_and_function(tool):+ for action in ("describe", "call"):+ assert call(tool, action=action, module="risk")["ok"] is False+ assert call(tool, action=action, function="historical_var")["ok"] is False+++def test_unknown_action_rejected(tool):+ assert call(tool, action="exec")["ok"] is False+++# --- computation matches the library ---+++def test_bs_price_matches_the_textbook_value(tool):+ result = call(tool, action="call", module="options", function="bs_price",+ kwargs={"S": 100, "K": 100, "T": 1.0, "r": 0.05, "sigma": 0.2,+ "option_type": "call"})+ assert result["result"] == pytest.approx(10.4506, abs=1e-4)+++def test_result_matches_a_direct_import(tool):+ from src.quantlib.risk import historical_var++ returns = [0.01, -0.02, -0.05, 0.03, -0.01, 0.02, -0.03, 0.04, -0.06, 0.01]+ through_tool = call(tool, action="call", module="risk", function="historical_var",+ kwargs={"returns": returns, "confidence": 0.9})["result"]+ assert through_tool == pytest.approx(historical_var(returns, confidence=0.9))+++def test_a_dataclass_result_serializes_field_by_field(tool):+ result = call(tool, action="call", module="var_backtest", function="kupiec_pof",+ kwargs={"violations": 10, "observations": 1000, "confidence": 0.99})+ assert result["ok"] is True+ assert result["result"]["violations"] == 10+ assert result["result"]["p_value"] == pytest.approx(1.0)+ assert result["result"]["rejected"] is False+++# --- pandas envelopes ---+++def test_a_series_envelope_reaches_the_function_with_its_index(tool):+ result = call(+ tool, action="call", module="timeseries", function="compute_half_life",+ kwargs={"spread": {"__series__": {+ "index": list(range(200)),+ "values": [((-1) ** i) * (0.9 ** i) for i in range(200)],+ }}},+ )+ assert result["ok"] is True+ assert isinstance(result["result"], (int, float))+++def test_a_dataframe_envelope_is_decoded(tool):+ result = call(+ tool, action="call", module="factormodel", function="portfolio_style_exposure",+ kwargs={+ "holdings": {"__series__": {"index": ["A", "B"], "values": [0.5, 0.5]}},+ "exposures": {"__dataframe__": {+ "index": ["A", "B"], "columns": ["value"], "data": [[1.0], [-1.0]]}},+ },+ )+ assert result["ok"] is True+ assert result["result"]["__series__"]["values"][0] == pytest.approx(0.0)+++def test_a_plain_list_stays_a_list(tool):+ # Most functions take a sequence; coercing every list into a Series would+ # break the ones that do not.+ result = call(tool, action="call", module="risk", function="historical_cvar",+ kwargs={"returns": [0.01, -0.02, -0.05, 0.03, -0.01,+ 0.02, -0.03, 0.04, -0.06, 0.01]})+ assert result["ok"] is True+++def test_a_malformed_envelope_is_reported_not_crashed(tool):+ result = call(tool, action="call", module="risk", function="historical_var",+ kwargs={"returns": {"__series__": {"index": [1, 2]}}})+ assert result["ok"] is False+ assert "envelope" in result["error"]+++# --- error surfaces are informative, never raised ---+++def test_a_wrong_argument_returns_the_signature_to_fix_it_with(tool):+ result = call(tool, action="call", module="options", function="bs_price",+ kwargs={"S": 100})+ assert result["ok"] is False+ assert "signature" in result+++def test_a_domain_refusal_is_surfaced_verbatim(tool):+ # The library refuses a confidence outside (0,1); that refusal is the+ # answer, and must reach the caller instead of becoming a crash.+ result = call(tool, action="call", module="risk", function="historical_var",+ kwargs={"returns": [0.01, -0.02, 0.03], "confidence": 1.5})+ assert result["ok"] is False+ assert "confidence" in result["error"]+++def test_kwargs_must_be_an_object(tool):+ result = call(tool, action="call", module="risk", function="historical_var", kwargs=[1, 2])+ assert result["ok"] is False+++def test_execute_never_raises_whatever_it_is_given(tool):+ for bad in (+ {"action": "call", "module": None, "function": None},+ {"action": None},+ {"action": "call", "module": "risk", "function": "historical_var", "kwargs": None},+ ):+ assert json.loads(tool.execute(**bad))["ok"] in (True, False)+++# --- serialization conventions ---+++def test_non_finite_floats_are_explicit_strings_not_null(tool):+ # A NaN arriving as JSON null reads as "absent", which is a different claim.+ result = call(tool, action="call", module="options", function="implied_volatility",+ kwargs={"market_price": 1e-9, "S": 100, "K": 200, "T": 0.01,+ "r": 0.05, "option_type": "call"})+ if result["ok"]:+ assert result["result"] in ("NaN", "Infinity", "-Infinity") or isinstance(+ result["result"], (int, float)+ )+++def test_registry_exposes_the_tool_without_shell_tools_enabled():+ # The whole point: reachable on a registry built the way the API and MCP+ # transports build it, with shell tools off.+ registry = build_registry(include_shell_tools=False)+ assert "quantlib_call" in registry.tool_names+ assert "bash" not in registry.tool_names+++def test_the_tool_is_read_only(tool):+ assert tool.is_readonly is True