"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(quantlib): promote the finance-math layer out of markdown
Haozhe Wu62b8d9d7adfb
diff --git a/agent/backtest/engines/options_portfolio.py b/agent/backtest/engines/options_portfolio.pyindex 6ed13c25d..8404db6c9 100644--- a/agent/backtest/engines/options_portfolio.py+++ b/agent/backtest/engines/options_portfolio.py@@ -12,6 +12,10 @@ v2 enhancements over v1:Signal interface: OptionsSignalEngine.generate(data_map) returns a list of trade instructions.Artifacts: equity.csv, metrics.csv, trades.csv, greeks.csv.++Black-Scholes price and Greeks come from ``src.quantlib.options``. What stays+here is the engine's own volatility surface -- historical vol, the smile, and+the per-leg vol every pricing site must agree on."""import json@@ -21,95 +25,8 @@ from typing import Any, Dict, List, Optionalimport numpy as npimport pandas as pd-from scipy.stats import norm---# --- Black-Scholes pricing ------def bs_price(S: float, K: float, T: float, r: float, sigma: float,- option_type: str = "call") -> float:- """Black-Scholes European option pricing.-- Args:- S: Underlying spot price.- K: Strike price.- T: Time to expiry in years.- r: Risk-free rate (annualised).- sigma: Annualised volatility.- option_type: Option type, "call" or "put".-- Returns:- Theoretical option price.-- Example:- >>> round(bs_price(100, 100, 1.0, 0.05, 0.2, "call"), 2)- 10.45- """- # Non-positive S/K makes log(S/K) undefined; reuse the intrinsic fallback- # (iv_smile_adjustment already soft-guards non-positive S/K).- if T <= 0 or sigma <= 0 or S <= 0 or K <= 0:- if option_type == "call":- return max(S - K, 0.0)- return max(K - S, 0.0)-- d1 = (np.log(S / K) + (r + sigma ** 2 / 2) * T) / (sigma * np.sqrt(T))- d2 = d1 - sigma * np.sqrt(T)-- if option_type == "call":- return float(S * norm.cdf(d1) - K * np.exp(-r * T) * norm.cdf(d2))- return float(K * np.exp(-r * T) * norm.cdf(-d2) - S * norm.cdf(-d1))---# --- Greeks -----def bs_greeks(S: float, K: float, T: float, r: float, sigma: float,- option_type: str = "call") -> Dict[str, float]:- """Calculate Black-Scholes Greeks.-- Args:- S: Underlying spot price.- K: Strike price.- T: Time to expiry in years.- r: Risk-free rate (annualised).- sigma: Annualised volatility.- option_type: Option type, "call" or "put".-- Returns:- Dict containing delta, gamma, theta, vega.- """- if T <= 0 or sigma <= 0 or S <= 0 or K <= 0:- intrinsic_call = 1.0 if S > K else 0.0- delta = intrinsic_call if option_type == "call" else intrinsic_call - 1.0- return {"delta": delta, "gamma": 0.0, "theta": 0.0, "vega": 0.0}-- sqrt_T = np.sqrt(T)- d1 = (np.log(S / K) + (r + sigma ** 2 / 2) * T) / (sigma * sqrt_T)- d2 = d1 - sigma * sqrt_T- nd1_pdf = float(norm.pdf(d1))-- # Delta- if option_type == "call":- delta = float(norm.cdf(d1))- else:- delta = float(norm.cdf(d1) - 1.0)-- # Gamma (same for call and put)- gamma = float(nd1_pdf / (S * sigma * sqrt_T))-- # Theta (daily)- theta_common = -(S * nd1_pdf * sigma) / (2 * sqrt_T)- if option_type == "call":- theta = theta_common - r * K * np.exp(-r * T) * norm.cdf(d2)- else:- theta = theta_common + r * K * np.exp(-r * T) * norm.cdf(-d2)- theta = float(theta / 365.0) # convert to daily-- # Vega (per 1% change in volatility)- vega = float(S * nd1_pdf * sqrt_T / 100.0)-- return {"delta": delta, "gamma": gamma, "theta": theta, "vega": vega}+from src.quantlib.options import bs_greeks, bs_price, normalise_option_type# --- Historical volatility ---@@ -188,19 +105,24 @@ class OptionPosition:"""A single option leg position.Attributes:- option_type: "call" or "put".+ option_type: "call" or "put", folded to lower case on construction so+ that settlement here and pricing in ``src.quantlib.options`` cannot+ disagree about a leg typed ``"Call"``.strike: Strike price.expiry: Expiry date.qty: Quantity (positive = long, negative = short).entry_price: Theoretical option price at entry.entry_date: Entry date string.underlying_code: Underlying instrument code.++ Raises:+ ValueError: If ``option_type`` is neither call nor put."""def __init__(self, option_type: str, strike: float, expiry: str,qty: int, entry_price: float, entry_date: str,underlying_code: str):- self.option_type = option_type+ self.option_type = normalise_option_type(option_type)self.strike = strikeself.expiry = pd.Timestamp(expiry)self.qty = qty@@ -413,7 +335,10 @@ def run_options_backtest(iv_val = ivs.get(underlying, 0.3)for leg in legs:- leg_type = leg.get("type", "call")+ # Fold before it is priced, matched and recorded: config comes+ # from the user, and a raw "Call" would price as a call and+ # settle as a put.+ leg_type = normalise_option_type(leg.get("type", "call"))strike = leg.get("strike", spot)expiry = leg.get("expiry", "")qty = leg.get("qty", 1)@@ -516,6 +441,7 @@ def run_options_backtest(total_gamma = 0.0total_theta = 0.0total_vega = 0.0+ total_rho = 0.0for pos in positions:spot = spot_prices.get(pos.underlying_code, 0.0)@@ -532,6 +458,7 @@ def run_options_backtest(total_gamma += greeks["gamma"] * pos.qty * contract_multipliertotal_theta += greeks["theta"] * pos.qty * contract_multipliertotal_vega += greeks["vega"] * pos.qty * contract_multiplier+ total_rho += greeks["rho"] * pos.qty * contract_multiplierequity_records.append({"timestamp": date_str,@@ -546,6 +473,7 @@ def run_options_backtest("gamma": round(total_gamma, 6),"theta": round(total_theta, 6),"vega": round(total_vega, 6),+ "rho": round(total_rho, 6),"num_positions": len(positions),})@@ -604,7 +532,9 @@ def _find_matching_position(Args:positions: Current open positions.underlying: Underlying instrument code.- option_type: Option type.+ option_type: Option type, already folded by ``normalise_option_type``;+ ``OptionPosition`` folds its own, so both sides compare in lower+ case.strike: Strike price.expiry: Expiry date string.diff --git a/agent/src/quantlib/__init__.py b/agent/src/quantlib/__init__.pynew file mode 100644index 000000000..fa7e1e305--- /dev/null+++ b/agent/src/quantlib/__init__.py@@ -0,0 +1,32 @@+"""Tested financial-mathematics primitives.++Formulas here were previously carried as markdown inside skills, where the LLM+retyped them into throwaway Python on every run. That delivery model is not+reproducible (different code each run), not reviewable (no tests, no version)+and not auditable (no artifact). Everything in this package is the opposite:+one implementation, pinned by tests, called by both the skills and the engines.++Import submodules directly -- this file deliberately imports nothing, so that a+missing optional dependency in one domain cannot break the others::++ from src.quantlib.options import implied_volatility+ from src.quantlib.fixedincome import dv01++Submodules:+ options Black-Scholes price/greeks and implied-volatility inversion+ fixedincome Bond pricing, YTM, duration/convexity/DV01, curve fitting+ credit Altman Z, Merton/KMV, spread analytics+ timeseries Stationarity, cointegration, GARCH, bootstrap+ risk VaR/CVaR, drawdown, Monte Carlo, EVT tail fitting+ attribution Brinson-Fachler allocation/selection/interaction+ impact Market-impact and slippage models+ fundmath Private-markets fund maths on the irregular cash-flow spine+ performance Client money-weighted performance (XIRR, TWR) on that spine++Two modules expose a function named ``xirr`` and they are not interchangeable.+``fundmath.xirr`` takes a ``CashFlowSeries`` under a valuation policy, scans a+bounded rate window and (via ``xirr_all``) knows about multiple roots, raising+``XIRRError``. ``performance.xirr`` takes bare ``(date, amount)`` pairs, returns+the single root its bisection bracket isolates and raises+``UnsolvableRateError``. Import the one whose input you actually hold.+"""diff --git a/agent/src/quantlib/attribution.py b/agent/src/quantlib/attribution.pynew file mode 100644index 000000000..5fae8aa1e--- /dev/null+++ b/agent/src/quantlib/attribution.py@@ -0,0 +1,398 @@+"""Brinson-Fachler performance attribution with residual-free multi-period linking.++Single-period decomposition splits the active return (portfolio minus benchmark)+into three sector-level effects::++ Allocation_i = (w_p,i - w_b,i) * (r_b,i - R_b)+ Selection_i = w_b,i * (r_p,i - r_b,i)+ Interaction_i = (w_p,i - w_b,i) * (r_p,i - r_b,i)++The sum of all three over all sectors equals ``R_p - R_b`` *identically* -- there+is no residual and none is reported. The identity holds for any sector returns+whatsoever, provided only that the two weight vectors carry the same total; that+is the one precondition this module enforces (see :func:`brinson_fachler`).++Multi-period linking uses **Carino** logarithmic linking, for three reasons:++1. It is residual-free. Naively summing single-period arithmetic effects does not+ reproduce the compounded active return, because returns compound and effects+ are added; Carino's scaling factors absorb exactly that gap.+2. Its scaling factor for a period depends only on that period's total portfolio+ and benchmark return -- never on the effects being linked. Linking is therefore+ deterministic, order-independent, and cannot be steered by how the analyst+ chose to bucket sectors. Menchero's linking is likewise residual-free but+ distributes a correction term computed from the effects themselves, which adds+ machinery this module does not need.+3. It is what ``skills/performance-attribution/SKILL.md`` already prescribes, so+ the tested implementation and the documented method agree.++Carino defines a total factor ``k`` and a per-period factor ``k_t``::++ k = (ln(1 + R_P) - ln(1 + R_B)) / (R_P - R_B)+ k_t = (ln(1 + R_p,t) - ln(1 + R_b,t)) / (R_p,t - R_b,t)++and scales every single-period effect by ``k_t / k``. Because each period's+effects sum to ``R_p,t - R_b,t``, the linked effects telescope through the+logarithms and sum to the compounded active return ``R_P - R_B`` exactly.++Only the standard library is imported here, so this module stays importable even+when an optional numerical dependency used elsewhere in ``quantlib`` is missing.+"""++from __future__ import annotations++import math+from collections.abc import Mapping, Sequence+from dataclasses import dataclass++#: Largest tolerated difference between the portfolio and benchmark weight sums.+#: Beyond this the Brinson identity stops holding, so it is an error, not a warning.+DEFAULT_WEIGHT_SUM_TOLERANCE = 1e-9++#: Below this absolute gap between a period's portfolio and benchmark return, the+#: Carino factor is evaluated at its analytic limit rather than by a difference of+#: logarithms, which would lose precision to catastrophic cancellation.+_CARINO_LIMIT_EPS = 1e-9+++@dataclass(frozen=True)+class SectorEffect:+ """One sector's single-period Brinson-Fachler decomposition.++ Attributes:+ sector: Sector label.+ portfolio_weight: Portfolio weight of the sector (``w_p,i``).+ benchmark_weight: Benchmark weight of the sector (``w_b,i``).+ portfolio_return: Portfolio return within the sector (``r_p,i``).+ benchmark_return: Benchmark return within the sector (``r_b,i``).+ allocation: Allocation effect, from over/under-weighting the sector.+ selection: Selection effect, from picking better names inside the sector.+ interaction: Interaction effect, the cross term of the two.+ """++ sector: str+ portfolio_weight: float+ benchmark_weight: float+ portfolio_return: float+ benchmark_return: float+ allocation: float+ selection: float+ interaction: float++ @property+ def total(self) -> float:+ """Return the sector's total contribution to the active return.++ Returns:+ Sum of the allocation, selection and interaction effects.+ """+ return self.allocation + self.selection + self.interaction+++@dataclass(frozen=True)+class BrinsonResult:+ """Single-period attribution for a whole portfolio.++ The three aggregate effects sum to :attr:`active_return` exactly; no residual+ term exists or is reported.++ Attributes:+ sectors: Per-sector decompositions, portfolio order first, then any+ benchmark-only sectors.+ portfolio_return: Total portfolio return ``R_p = sum(w_p,i * r_p,i)``.+ benchmark_return: Total benchmark return ``R_b = sum(w_b,i * r_b,i)``.+ active_return: ``R_p - R_b``.+ allocation: Sum of every sector's allocation effect.+ selection: Sum of every sector's selection effect.+ interaction: Sum of every sector's interaction effect.+ """++ sectors: tuple[SectorEffect, ...]+ portfolio_return: float+ benchmark_return: float+ active_return: float+ allocation: float+ selection: float+ interaction: float++ @property+ def total_effect(self) -> float:+ """Return the summed effects, which equal :attr:`active_return`.++ Returns:+ Allocation plus selection plus interaction.+ """+ return self.allocation + self.selection + self.interaction+++@dataclass(frozen=True)+class LinkedSectorEffect:+ """One sector's Carino-linked effects across every period.++ Weights and returns are deliberately absent: they compound rather than add,+ so a multi-period "weight" would have no single defensible definition.++ Attributes:+ sector: Sector label.+ allocation: Linked allocation effect.+ selection: Linked selection effect.+ interaction: Linked interaction effect.+ """++ sector: str+ allocation: float+ selection: float+ interaction: float++ @property+ def total(self) -> float:+ """Return the sector's total linked contribution.++ Returns:+ Sum of the linked allocation, selection and interaction effects.+ """+ return self.allocation + self.selection + self.interaction+++@dataclass(frozen=True)+class LinkedAttribution:+ """Multi-period attribution produced by Carino linking.++ The three aggregate effects sum to :attr:`active_return`, the *compounded*+ active return, exactly.++ Attributes:+ sectors: Per-sector linked decompositions.+ portfolio_return: Compounded portfolio return over all periods.+ benchmark_return: Compounded benchmark return over all periods.+ active_return: ``portfolio_return - benchmark_return``.+ allocation: Linked allocation effect, summed over sectors.+ selection: Linked selection effect, summed over sectors.+ interaction: Linked interaction effect, summed over sectors.+ scaling_factors: The ``k_t / k`` multiplier applied to each period, in+ period order. Exposed so an attribution report can be audited.+ """++ sectors: tuple[LinkedSectorEffect, ...]+ portfolio_return: float+ benchmark_return: float+ active_return: float+ allocation: float+ selection: float+ interaction: float+ scaling_factors: tuple[float, ...]++ @property+ def total_effect(self) -> float:+ """Return the summed linked effects, which equal :attr:`active_return`.++ Returns:+ Allocation plus selection plus interaction.+ """+ return self.allocation + self.selection + self.interaction+++def brinson_fachler(+ portfolio_weights: Mapping[str, float],+ benchmark_weights: Mapping[str, float],+ portfolio_returns: Mapping[str, float],+ benchmark_returns: Mapping[str, float],+ weight_sum_tolerance: float = DEFAULT_WEIGHT_SUM_TOLERANCE,+) -> BrinsonResult:+ """Decompose one period's active return into allocation, selection and interaction.++ Sector returns may be omitted only where the corresponding weight is zero; the+ missing return is then filled from the other side. That makes a benchmark-only+ sector's selection and interaction vanish and charges the whole effect to+ allocation -- you cannot show selection skill in something you did not own --+ and it treats an off-benchmark holding symmetrically. The choice never+ threatens the tie-out, which is independent of the sector returns used.++ Args:+ portfolio_weights: Sector label to portfolio weight.+ benchmark_weights: Sector label to benchmark weight.+ portfolio_returns: Sector label to within-sector portfolio return.+ benchmark_returns: Sector label to within-sector benchmark return.+ weight_sum_tolerance: Largest tolerated difference between the two weight+ sums. Defaults to :data:`DEFAULT_WEIGHT_SUM_TOLERANCE`.++ Returns:+ A :class:`BrinsonResult` whose allocation, selection and interaction sum+ to its ``active_return`` to floating-point precision, provided the two+ weight vectors really do carry the same total.++ The tie-out is exactly as good as ``weight_sum_tolerance`` allows: a+ weight-sum gap ``dW`` leaves a residual of ``-R_b * dW``, because the+ ``R_b * sum(w_p - w_b)`` term of the allocation effect no longer vanishes.+ At the default tolerance that residual is below 1e-10 and invisible.+ Loosen the tolerance and it becomes visible in basis points -- a 2%+ weight-sum gap against a 5% benchmark return is a 10bp residual -- so+ loosen it only to absorb rounding in the weights, never to force through+ two vectors that genuinely disagree.++ Raises:+ ValueError: If no sectors were supplied, if the two weight vectors do not+ sum to the same total within ``weight_sum_tolerance``, or if a sector+ carries a non-zero weight on a side but no return on that side.+ """+ ordered: list[str] = list(portfolio_weights)+ ordered.extend(sector for sector in benchmark_weights if sector not in portfolio_weights)+ if not ordered:+ raise ValueError("brinson_fachler needs at least one sector")++ portfolio_total = math.fsum(portfolio_weights.values())+ benchmark_total = math.fsum(benchmark_weights.values())+ if abs(portfolio_total - benchmark_total) > weight_sum_tolerance:+ raise ValueError(+ "portfolio and benchmark weights must sum to the same total for the Brinson "+ f"identity to hold; got {portfolio_total!r} and {benchmark_total!r} "+ f"(difference {portfolio_total - benchmark_total!r} exceeds {weight_sum_tolerance!r})"+ )++ resolved: list[tuple[str, float, float, float, float]] = []+ for sector in ordered:+ w_p = float(portfolio_weights.get(sector, 0.0))+ w_b = float(benchmark_weights.get(sector, 0.0))+ r_p = portfolio_returns.get(sector)+ r_b = benchmark_returns.get(sector)+ if r_p is None:+ if w_p != 0.0:+ raise ValueError(f"sector {sector!r} has portfolio weight {w_p!r} but no portfolio return")+ if r_b is None:+ raise ValueError(f"sector {sector!r} has no portfolio return and no benchmark return")+ r_p = r_b+ if r_b is None:+ if w_b != 0.0:+ raise ValueError(f"sector {sector!r} has benchmark weight {w_b!r} but no benchmark return")+ r_b = r_p+ resolved.append((sector, w_p, w_b, float(r_p), float(r_b)))++ total_portfolio_return = math.fsum(w_p * r_p for _, w_p, _, r_p, _ in resolved)+ total_benchmark_return = math.fsum(w_b * r_b for _, _, w_b, _, r_b in resolved)++ effects: list[SectorEffect] = []+ for sector, w_p, w_b, r_p, r_b in resolved:+ active_weight = w_p - w_b+ effects.append(+ SectorEffect(+ sector=sector,+ portfolio_weight=w_p,+ benchmark_weight=w_b,+ portfolio_return=r_p,+ benchmark_return=r_b,+ allocation=active_weight * (r_b - total_benchmark_return),+ selection=w_b * (r_p - r_b),+ interaction=active_weight * (r_p - r_b),+ )+ )++ return BrinsonResult(+ sectors=tuple(effects),+ portfolio_return=total_portfolio_return,+ benchmark_return=total_benchmark_return,+ active_return=total_portfolio_return - total_benchmark_return,+ allocation=math.fsum(effect.allocation for effect in effects),+ selection=math.fsum(effect.selection for effect in effects),+ interaction=math.fsum(effect.interaction for effect in effects),+ )+++def carino_factor(portfolio_return: float, benchmark_return: float) -> float:+ """Return the Carino logarithmic scaling factor for one return pair.++ The factor is ``(ln(1 + Rp) - ln(1 + Rb)) / (Rp - Rb)``. When the two returns+ coincide that expression is 0/0, so the analytic limit ``1 / (1 + Rp)`` applies.+ It is evaluated in the equivalent symmetric form ``2 / ((1 + Rp) + (1 + Rb))``,+ which reduces to ``1 / (1 + Rp)`` when the returns are equal but stays accurate+ to second order just short of coincidence, where the difference of logarithms+ would lose most of its significant digits to cancellation.++ Args:+ portfolio_return: Portfolio return for the period, as a decimal fraction.+ benchmark_return: Benchmark return for the period, as a decimal fraction.++ Returns:+ The scaling factor.++ Raises:+ ValueError: If either return is at or below -100%, which would make the+ wealth relative non-positive and the logarithm undefined.+ """+ portfolio_wealth = 1.0 + portfolio_return+ benchmark_wealth = 1.0 + benchmark_return+ if portfolio_wealth <= 0.0 or benchmark_wealth <= 0.0:+ raise ValueError(+ "Carino linking needs returns above -100%; got portfolio "+ f"{portfolio_return!r} and benchmark {benchmark_return!r}"+ )+ if abs(portfolio_return - benchmark_return) < _CARINO_LIMIT_EPS:+ return 2.0 / (portfolio_wealth + benchmark_wealth)+ return (math.log(portfolio_wealth) - math.log(benchmark_wealth)) / (portfolio_return - benchmark_return)+++def carino_link(periods: Sequence[BrinsonResult]) -> LinkedAttribution:+ """Link single-period Brinson results into a residual-free multi-period attribution.++ Every period's effects are scaled by ``k_t / k`` and summed. Because each+ period's three effects already sum to that period's active return, the linked+ effects sum to the compounded active return exactly.++ Sectors absent from a period are treated as contributing zero for that period,+ which is what a zero weight on both sides would have produced anyway.++ Args:+ periods: Single-period results in chronological order.++ Returns:+ A :class:`LinkedAttribution` whose allocation, selection and interaction+ sum to its ``active_return`` to floating-point precision.++ Raises:+ ValueError: If ``periods`` is empty, or if any period's return is at or+ below -100%, which the logarithmic linking cannot represent.+ """+ if not periods:+ raise ValueError("carino_link needs at least one period")++ portfolio_wealth = math.prod(1.0 + period.portfolio_return for period in periods)+ benchmark_wealth = math.prod(1.0 + period.benchmark_return for period in periods)+ total_portfolio_return = portfolio_wealth - 1.0+ total_benchmark_return = benchmark_wealth - 1.0+ total_factor = carino_factor(total_portfolio_return, total_benchmark_return)++ scaling_factors = tuple(+ carino_factor(period.portfolio_return, period.benchmark_return) / total_factor for period in periods+ )++ order: list[str] = []+ scaled: dict[str, list[float]] = {}+ for period, scale in zip(periods, scaling_factors, strict=True):+ for effect in period.sectors:+ if effect.sector not in scaled:+ order.append(effect.sector)+ scaled[effect.sector] = [0.0, 0.0, 0.0]+ bucket = scaled[effect.sector]+ bucket[0] += scale * effect.allocation+ bucket[1] += scale * effect.selection+ bucket[2] += scale * effect.interaction++ sectors = tuple(+ LinkedSectorEffect(+ sector=sector,+ allocation=scaled[sector][0],+ selection=scaled[sector][1],+ interaction=scaled[sector][2],+ )+ for sector in order+ )++ return LinkedAttribution(+ sectors=sectors,+ portfolio_return=total_portfolio_return,+ benchmark_return=total_benchmark_return,+ active_return=total_portfolio_return - total_benchmark_return,+ allocation=math.fsum(sector.allocation for sector in sectors),+ selection=math.fsum(sector.selection for sector in sectors),+ interaction=math.fsum(sector.interaction for sector in sectors),+ scaling_factors=scaling_factors,+ )diff --git a/agent/src/quantlib/credit.py b/agent/src/quantlib/credit.pynew file mode 100644index 000000000..03d03cea5--- /dev/null+++ b/agent/src/quantlib/credit.py@@ -0,0 +1,675 @@+"""Credit-risk primitives: Altman Z-Score, Merton/KMV, and spread analytics.++Executable form of the credit models that used to live as markdown code blocks+in ``src/skills/credit-analysis/SKILL.md``. Differences from those originals are+deliberate and each is called out in the relevant docstring; the two that bite+hardest are:++* **Spread input units are explicit.** The markdown's two spread helpers+ disagreed with each other -- :func:`credit_spread_analysis` multiplied by 100+ (yields in percent) while :func:`spread_term_structure` multiplied by 10000+ (yields in decimals). Both now take ``input_unit``, defaulting to whatever the+ markdown silently assumed, so neither changes behaviour but neither can be+ misread.+* **Altman's X4 denominator is total liabilities**, not "total debt". The skill's+ own variable table says 总负债账面值; the markdown's parameter name said+ ``total_debt``. The name here follows the model.++All rates and ratios are decimals unless a name ends in ``_bp``.+"""++from __future__ import annotations++import math+from collections.abc import Mapping+from dataclasses import dataclass++import numpy as np+import pandas as pd+from scipy.optimize import fsolve+from scipy.stats import norm++__all__ = [+ "ALTMAN_MODELS",+ "AltmanModelSpec",+ "AltmanZScore",+ "MertonResult",+ "SPREAD_INPUT_UNITS",+ "EDF_REFERENCE_BANDS",+ "MERTON_SOLVER_RESTARTS",+ "MERTON_SOLVER_STEP_TOL",+ "ZONE_LABELS_ZH",+ "altman_z_score",+ "merton_asset_solve",+ "merton_model",+ "distance_to_default",+ "kmv_default_point",+ "kmv_distance_to_default",+ "edf_reference_band",+ "credit_spread_analysis",+ "spread_term_structure",+]+++@dataclass(frozen=True)+class AltmanModelSpec:+ """Coefficients and cut-offs of one Altman Z-Score variant.++ Attributes:+ coefficients: Weights on ``(X1, X2, X3, X4, X5)``. ``X5`` carries a+ weight of 0.0 in variants that drop the asset-turnover term.+ safe_threshold: Scores strictly above this sit in the safe zone.+ distress_threshold: Scores strictly below this sit in the distress zone.+ uses_x5: Whether the variant needs a revenue figure at all.+ equity_basis: What ``equity_value`` must be for this variant --+ ``"market"`` for the market capitalisation, ``"book"`` for the book+ value of equity.+ """++ coefficients: tuple[float, float, float, float, float]+ safe_threshold: float+ distress_threshold: float+ uses_x5: bool+ equity_basis: str+++#: The three published Altman variants carried by the credit-analysis skill.+ALTMAN_MODELS: Mapping[str, AltmanModelSpec] = {+ # Altman (1968), listed manufacturers.+ "original": AltmanModelSpec((1.2, 1.4, 3.3, 0.6, 1.0), 2.99, 1.81, True, "market"),+ # Z' -- privately held firms; X4 switches to book equity.+ "prime": AltmanModelSpec(+ (0.717, 0.847, 3.107, 0.420, 0.998), 2.90, 1.23, True, "book"+ ),+ # Z'' -- non-manufacturers / emerging markets; X5 dropped entirely.+ "double_prime": AltmanModelSpec((6.56, 3.26, 6.72, 1.05, 0.0), 2.60, 1.10, False, "book"),+}++#: Chinese labels for the three Z-Score zones, as printed in the skill.+ZONE_LABELS_ZH: Mapping[str, str] = {+ "safe": "安全区(低违约风险)",+ "grey": "灰色区(需深入分析)",+ "distress": "危险区(高违约风险)",+}+++@dataclass(frozen=True)+class AltmanZScore:+ """Outcome of an Altman Z-Score evaluation.++ Attributes:+ z_score: The composite score.+ model: Which variant produced it; a key of :data:`ALTMAN_MODELS`.+ zone: ``"safe"``, ``"grey"`` or ``"distress"``.+ label_zh: The Chinese zone label from :data:`ZONE_LABELS_ZH`.+ components: The ``X1``..``X5`` ratios. ``x5`` is ``None`` for variants+ that do not use it.+ safe_threshold: Cut-off above which the zone is ``"safe"``.+ distress_threshold: Cut-off below which the zone is ``"distress"``.+ """++ z_score: float+ model: str+ zone: str+ label_zh: str+ components: Mapping[str, float | None]+ safe_threshold: float+ distress_threshold: float+++def altman_z_score(+ *,+ working_capital: float,+ retained_earnings: float,+ ebit: float,+ equity_value: float,+ total_liabilities: float,+ total_assets: float,+ revenue: float | None = None,+ model: str = "original",+) -> AltmanZScore:+ """Score a firm's distress risk with one of the three Altman variants.++ Every argument is keyword-only, deliberately. Six interchangeable float+ parameters is exactly the shape where a positional call silently computes+ the wrong answer, and this signature does not match the argument order of+ the markdown block it replaced -- ``revenue`` and ``total_assets`` are+ swapped relative to it. A positional call written from memory of the old+ block would divide by revenue and return a confident, wrong Z with no+ error. Keyword-only makes that a ``TypeError`` instead.++ Args:+ working_capital: Current assets less current liabilities.+ retained_earnings: Cumulative retained earnings.+ ebit: Earnings before interest and tax.+ equity_value: Market capitalisation for ``"original"``; book value of+ equity for ``"prime"`` and ``"double_prime"``. The required basis is+ recorded on each :class:`AltmanModelSpec`.+ total_liabilities: Book value of *all* liabilities, not just interest+ bearing debt. This is the X4 denominator in Altman's definition.+ total_assets: Total assets; the denominator of X1, X2, X3 and X5.+ revenue: Sales for the period. Required unless the variant drops X5.+ model: A key of :data:`ALTMAN_MODELS`.++ Returns:+ An :class:`AltmanZScore` with the score, the zone and every input ratio.++ Raises:+ ValueError: If ``model`` is unknown, a denominator is zero, or the+ variant needs ``revenue`` and it was not supplied.+ """+ spec = ALTMAN_MODELS.get(model)+ if spec is None:+ raise ValueError(+ f"unknown model {model!r}; expected one of {tuple(ALTMAN_MODELS)}"+ )+ if total_assets == 0:+ raise ValueError("total_assets must be non-zero")+ if total_liabilities == 0:+ raise ValueError("total_liabilities must be non-zero")+ if spec.uses_x5 and revenue is None:+ raise ValueError(f"model {model!r} needs revenue for the X5 term")++ x1 = working_capital / total_assets+ x2 = retained_earnings / total_assets+ x3 = ebit / total_assets+ x4 = equity_value / total_liabilities+ x5 = revenue / total_assets if spec.uses_x5 else None++ weights = spec.coefficients+ z = weights[0] * x1 + weights[1] * x2 + weights[2] * x3 + weights[3] * x4+ if x5 is not None:+ z += weights[4] * x5++ if z > spec.safe_threshold:+ zone = "safe"+ elif z < spec.distress_threshold:+ zone = "distress"+ else:+ zone = "grey"++ return AltmanZScore(+ z_score=float(z),+ model=model,+ zone=zone,+ label_zh=ZONE_LABELS_ZH[zone],+ components={"x1": x1, "x2": x2, "x3": x3, "x4": x4, "x5": x5},+ safe_threshold=spec.safe_threshold,+ distress_threshold=spec.distress_threshold,+ )+++@dataclass(frozen=True)+class MertonResult:+ """Solved Merton structural model for one issuer.++ Attributes:+ asset_value: Implied market value of assets, in the units of the inputs.+ asset_vol: Implied annualised asset volatility as a decimal.+ d1: Black-Scholes ``d1`` on the asset value.+ d2: Black-Scholes ``d2``; equals the risk-neutral distance to default.+ distance_to_default: Distance to default at ``asset_drift``. When the+ drift is the risk-free rate this is exactly ``d2``.+ default_probability: Risk-neutral default probability ``N(-d2)``.+ debt_value: Present value of the risky zero-coupon debt.+ credit_spread: Continuously compounded spread over the risk-free rate,+ as a decimal.+ """++ asset_value: float+ asset_vol: float+ d1: float+ d2: float+ distance_to_default: float+ default_probability: float+ debt_value: float+ credit_spread: float++ @property+ def credit_spread_bp(self) -> float:+ """Credit spread expressed in basis points.++ Returns:+ ``credit_spread`` multiplied by 10000.+ """+ return self.credit_spread * 1e4+++def _merton_d1_d2(+ asset_value: float,+ asset_vol: float,+ debt_face: float,+ risk_free: float,+ horizon: float,+) -> tuple[float, float]:+ """Black-Scholes ``d1``/``d2`` for equity written on the firm's assets.++ Args:+ asset_value: Market value of assets.+ asset_vol: Annualised asset volatility as a decimal.+ debt_face: Face value of the zero-coupon debt.+ risk_free: Continuously compounded risk-free rate as a decimal.+ horizon: Years to the debt's maturity.++ Returns:+ Tuple ``(d1, d2)``.+ """+ vol_t = asset_vol * math.sqrt(horizon)+ d1 = (+ math.log(asset_value / debt_face) + (risk_free + 0.5 * asset_vol**2) * horizon+ ) / vol_t+ return d1, d1 - vol_t+++#: Step tolerance handed to the Merton root finder. ``fsolve``'s ``xtol`` bounds+#: the *step*, and because the unknowns are solved in log space that step is a+#: relative move in ``sigma_V``. At the SciPy default (~1.5e-8) a low-volatility,+#: high-leverage issuer -- exactly the case Merton is used for -- halts while the+#: scaled residual is still ~1e-7, so convergence is judged on the residual below+#: and the step tolerance is pinned near machine precision instead.+MERTON_SOLVER_STEP_TOL: float = 1e-13++#: Extra solves started from the previous answer when the residual still misses.+MERTON_SOLVER_RESTARTS: int = 2+++def merton_asset_solve(+ equity_value: float,+ equity_vol: float,+ debt_face: float,+ risk_free: float,+ horizon: float,+ tolerance: float = 1e-8,+) -> tuple[float, float]:+ """Back out asset value and asset volatility from observable equity.++ Solves the standard pair of equations simultaneously::++ E = V*N(d1) - D*exp(-r*T)*N(d2)+ sigma_E = N(d1) * sigma_V * V / E++ The unknowns are solved in log space so the root finder cannot wander into a+ negative asset value or a negative volatility, which the markdown version+ could.++ Args:+ equity_value: Market capitalisation.+ equity_vol: Annualised equity volatility as a decimal.+ debt_face: Face value of debt, treated as a single zero-coupon claim.+ risk_free: Continuously compounded risk-free rate as a decimal.+ horizon: Years to the debt's maturity.+ tolerance: Largest residual, relative to ``equity_value``, accepted as a+ solution.++ Returns:+ Tuple ``(asset_value, asset_vol)``.++ Raises:+ ValueError: If any input is non-positive, or the system does not+ converge to within ``tolerance``.+ """+ if min(equity_value, equity_vol, debt_face, horizon) <= 0:+ raise ValueError(+ "equity_value, equity_vol, debt_face and horizon must all be positive"+ )++ def residuals(log_params: np.ndarray) -> list[float]:+ asset_value, asset_vol = np.exp(log_params)+ d1, d2 = _merton_d1_d2(asset_value, asset_vol, debt_face, risk_free, horizon)+ equity_eq = (+ asset_value * norm.cdf(d1)+ - debt_face * math.exp(-risk_free * horizon) * norm.cdf(d2)+ - equity_value+ )+ vol_eq = norm.cdf(d1) * asset_vol * asset_value - equity_vol * equity_value+ return [equity_eq / equity_value, vol_eq / equity_value]++ start_value = equity_value + debt_face * math.exp(-risk_free * horizon)+ point = np.log([start_value, equity_vol * equity_value / start_value])+ for _ in range(MERTON_SOLVER_RESTARTS + 1):+ point = fsolve(+ residuals, point, full_output=True, xtol=MERTON_SOLVER_STEP_TOL+ )[0]+ worst = max(abs(r) for r in residuals(point))+ if math.isfinite(worst) and worst <= tolerance:+ break+ else:+ raise ValueError(+ "Merton system did not converge: worst scaled residual "+ f"{worst:.3g} exceeds tolerance {tolerance:g}"+ )++ asset_value, asset_vol = (float(v) for v in np.exp(point))+ return asset_value, asset_vol+++def merton_model(+ equity_value: float,+ equity_vol: float,+ debt_face: float,+ risk_free: float,+ horizon: float,+ asset_drift: float | None = None,+) -> MertonResult:+ """Estimate default probability and credit spread from equity market data.++ Args:+ equity_value: Market capitalisation.+ equity_vol: Annualised equity volatility as a decimal.+ debt_face: Face value of debt, treated as a single zero-coupon claim.+ risk_free: Continuously compounded risk-free rate as a decimal.+ horizon: Years to the debt's maturity.+ asset_drift: Expected asset return used for the real-world distance to+ default. Defaults to ``risk_free``, which is what the markdown did;+ supplying an equity-style drift instead gives the KMV reading.++ Returns:+ A :class:`MertonResult`.++ Raises:+ ValueError: If an input is non-positive or the asset system does not+ converge.+ """+ asset_value, asset_vol = merton_asset_solve(+ equity_value, equity_vol, debt_face, risk_free, horizon+ )+ d1, d2 = _merton_d1_d2(asset_value, asset_vol, debt_face, risk_free, horizon)+ drift = risk_free if asset_drift is None else asset_drift++ discounted_face = debt_face * math.exp(-risk_free * horizon)+ debt_value = float(+ discounted_face * norm.cdf(d2) + asset_value * norm.cdf(-d1)+ )+ spread = -math.log(debt_value / discounted_face) / horizon++ return MertonResult(+ asset_value=asset_value,+ asset_vol=asset_vol,+ d1=d1,+ d2=d2,+ distance_to_default=distance_to_default(+ asset_value, asset_vol, debt_face, horizon, drift+ ),+ default_probability=float(norm.cdf(-d2)),+ debt_value=debt_value,+ credit_spread=spread,+ )+++def distance_to_default(+ asset_value: float,+ asset_vol: float,+ default_point: float,+ horizon: float,+ drift: float = 0.0,+) -> float:+ """Merton distance to default, in standard deviations of log asset value.++ Args:+ asset_value: Market value of assets.+ asset_vol: Annualised asset volatility as a decimal.+ default_point: Asset level at which default is triggered. Merton uses+ the full face value of debt; KMV uses :func:`kmv_default_point`.+ horizon: Years to the measurement date.+ drift: Expected asset return. Pass the risk-free rate for the+ risk-neutral reading, an expected return for the real-world one.++ Returns:+ Distance to default. Larger is safer; under a lognormal assumption the+ matching default probability is ``N(-dd)``.++ Raises:+ ValueError: If any of the value, volatility, default point or horizon is+ non-positive.+ """+ if min(asset_value, asset_vol, default_point, horizon) <= 0:+ raise ValueError(+ "asset_value, asset_vol, default_point and horizon must all be positive"+ )+ numerator = math.log(asset_value / default_point) + (+ drift - 0.5 * asset_vol**2+ ) * horizon+ return numerator / (asset_vol * math.sqrt(horizon))+++def kmv_default_point(+ short_term_debt: float,+ long_term_debt: float,+ long_term_weight: float = 0.5,+) -> float:+ """KMV default point: all short-term debt plus part of the long-term book.++ Args:+ short_term_debt: Debt maturing inside one year.+ long_term_debt: Debt maturing beyond one year.+ long_term_weight: Fraction of long-term debt included. Moody's KMV uses+ 0.5; it is an argument because the calibration is a convention, not+ a result.++ Returns:+ The default point in the units of the inputs.++ Raises:+ ValueError: If either debt figure is negative, or the weight is outside+ ``[0, 1]``.+ """+ if short_term_debt < 0 or long_term_debt < 0:+ raise ValueError("debt figures must be non-negative")+ if not 0.0 <= long_term_weight <= 1.0:+ raise ValueError(f"long_term_weight must lie in [0, 1], got {long_term_weight}")+ return short_term_debt + long_term_weight * long_term_debt+++def kmv_distance_to_default(+ asset_value: float,+ asset_vol: float,+ default_point: float,+) -> float:+ """KMV's linear distance to default, ``(V - DP) / (V * sigma_V)``.++ This is the form the skill documents for KMV and is *not* the same quantity+ as :func:`distance_to_default`: it measures the gap in units of the asset+ value's own standard deviation rather than in log space, and it carries no+ horizon or drift. Keep the two apart -- KMV then maps this number to an+ empirical EDF rather than through the normal CDF.++ Args:+ asset_value: Market value of assets.+ asset_vol: Annualised asset volatility as a decimal.+ default_point: Output of :func:`kmv_default_point`.++ Returns:+ Distance to default in standard deviations. Larger is safer; negative+ means assets already sit below the default point.++ Raises:+ ValueError: If ``asset_value`` or ``asset_vol`` is non-positive.+ """+ if asset_value <= 0 or asset_vol <= 0:+ raise ValueError("asset_value and asset_vol must be positive")+ return (asset_value - default_point) / (asset_value * asset_vol)+++#: Reference DD-to-EDF bands from the skill, as ``(dd_floor, edf_low, edf_high)``+#: with EDF as decimals. ``math.inf`` marks an open end.+EDF_REFERENCE_BANDS: tuple[tuple[float, float, float], ...] = (+ (4.0, 0.0, 0.001),+ (2.0, 0.001, 0.01),+ (1.0, 0.01, 0.05),+ (-math.inf, 0.05, math.inf),+)+++def edf_reference_band(dd: float) -> tuple[float, float]:+ """Look up the indicative EDF range for a distance to default.++ This is the skill's published rule of thumb, not a fitted mapping. A real+ KMV EDF comes from a proprietary default database; treat the output as a+ sanity band and never as a calibrated probability.++ Args:+ dd: Distance to default.++ Returns:+ Tuple ``(edf_low, edf_high)`` as decimals; the upper end is+ ``math.inf`` for the worst band.++ Raises:+ ValueError: If ``dd`` is not a finite number.+ """+ if not math.isfinite(dd):+ raise ValueError(f"dd must be finite, got {dd}")+ for floor, low, high in EDF_REFERENCE_BANDS:+ if dd > floor:+ return low, high+ return EDF_REFERENCE_BANDS[-1][1], EDF_REFERENCE_BANDS[-1][2]+++#: Multipliers turning a yield difference into basis points, by input unit.+SPREAD_INPUT_UNITS: Mapping[str, float] = {+ "decimal": 10_000.0,+ "percent": 100.0,+ "bp": 1.0,+}+++def _bp_multiplier(input_unit: str) -> float:+ """Resolve a yield input unit to its basis-point multiplier.++ Args:+ input_unit: A key of :data:`SPREAD_INPUT_UNITS`.++ Returns:+ The multiplier that converts the input unit to basis points.++ Raises:+ ValueError: If the unit is not recognised.+ """+ try:+ return SPREAD_INPUT_UNITS[input_unit]+ except KeyError:+ raise ValueError(+ f"unknown input_unit {input_unit!r}; expected one of "+ f"{tuple(SPREAD_INPUT_UNITS)}"+ ) from None+++def credit_spread_analysis(+ bond_yields: pd.Series,+ risk_free_yields: pd.Series,+ window: int = 252,+ lookback_periods: int = 21,+ signal_z: float = 1.5,+ input_unit: str = "percent",+) -> pd.DataFrame:+ """Time-series view of an issuer's spread: level, z-score and percentile.++ .. warning::+ ``historical_percentile`` is a **whole-sample** rank, carried over from+ the markdown template this replaced. Every row is ranked against the+ rows that come *after* it as well, so the column is look-ahead biased+ and must never be fed to a backtest as a signal -- the same date will+ report a different percentile once more data arrives. It is a+ descriptive summary of the sample you are holding. ``z_score`` and+ ``signal`` are rolling and therefore causal; use those instead.++ Args:+ bond_yields: Credit yields indexed by date.+ risk_free_yields: Matching risk-free yields on the *same* index. An+ index mismatch raises rather than silently producing NaN, which is+ what plain pandas subtraction would have done.+ window: Rolling window, in observations, for the mean and standard+ deviation. 252 is one trading year.+ lookback_periods: Horizon for the slower change column; 21 is one+ trading month.+ signal_z: Absolute z-score at which the row is flagged rich or cheap.+ input_unit: Unit of the two yield series -- a key of+ :data:`SPREAD_INPUT_UNITS`. Defaults to ``"percent"``, matching the+ markdown template's implicit assumption.++ Returns:+ A DataFrame on the input index with columns ``spread_bp``,+ ``rolling_mean_bp``, ``rolling_std_bp``, ``z_score``,+ ``historical_percentile``, ``change_1p_bp``, ``change_lookback_bp`` and+ ``signal``. ``signal`` is one of ``"rich"``, ``"neutral"``, ``"cheap"``.+ Every column except ``historical_percentile`` is causal; see the warning+ above.++ Raises:+ ValueError: If the two series do not share an index, if ``window`` or+ ``lookback_periods`` is not positive, or if ``input_unit`` is+ unknown.+ """+ if window <= 0 or lookback_periods <= 0:+ raise ValueError("window and lookback_periods must be positive")+ if len(bond_yields) != len(risk_free_yields) or not bond_yields.index.equals(+ risk_free_yields.index+ ):+ raise ValueError("bond_yields and risk_free_yields must share one index")++ spread_bp = (bond_yields - risk_free_yields) * _bp_multiplier(input_unit)++ rolling_mean = spread_bp.rolling(window).mean()+ rolling_std = spread_bp.rolling(window).std()+ z_score = (spread_bp - rolling_mean) / rolling_std++ result = pd.DataFrame(+ {+ "spread_bp": spread_bp,+ "rolling_mean_bp": rolling_mean,+ "rolling_std_bp": rolling_std,+ "z_score": z_score,+ "historical_percentile": spread_bp.rank(pct=True),+ "change_1p_bp": spread_bp.diff(),+ "change_lookback_bp": spread_bp.diff(lookback_periods),+ }+ )+ result["signal"] = "neutral"+ result.loc[z_score < -signal_z, "signal"] = "rich"+ result.loc[z_score > signal_z, "signal"] = "cheap"+ return result+++def spread_term_structure(+ issuers: Mapping[str, Mapping[float, float]],+ risk_free_curve: Mapping[float, float] | pd.Series,+ input_unit: str = "decimal",+ decimals: int | None = 1,+) -> pd.DataFrame:+ """Cross-sectional spread grid: one row per issuer, one column per tenor.++ Args:+ issuers: ``{issuer: {tenor_years: yield}}``.+ risk_free_curve: ``{tenor_years: yield}`` on the same unit basis. Tenors+ missing from the curve produce NaN rather than an error, so a+ partially quoted issuer still yields a row.+ input_unit: Unit of every yield passed in -- a key of+ :data:`SPREAD_INPUT_UNITS`. Defaults to ``"decimal"``, matching the+ markdown template's implicit assumption. Note this differs from+ :func:`credit_spread_analysis`, whose template assumed percent.+ decimals: Rounding applied to the basis-point output; ``None`` keeps+ full precision.++ Returns:+ A DataFrame indexed by issuer with one ``"{tenor}Y_spread_bp"`` column+ per tenor seen.++ Raises:+ ValueError: If ``issuers`` is empty or ``input_unit`` is unknown.+ """+ if not issuers:+ raise ValueError("issuers must contain at least one entry")+ multiplier = _bp_multiplier(input_unit)+ curve = dict(risk_free_curve)++ records = []+ for issuer, tenor_curve in issuers.items():+ row: dict[str, float] = {}+ for tenor, yld in tenor_curve.items():+ reference = curve.get(tenor, np.nan)+ spread = (yld - reference) * multiplier+ row[f"{tenor}Y_spread_bp"] = (+ spread if decimals is None else round(spread, decimals)+ )+ records.append(pd.Series(row, name=issuer))+ return pd.DataFrame(records)diff --git a/agent/src/quantlib/fixedincome.py b/agent/src/quantlib/fixedincome.pynew file mode 100644index 000000000..a6827f4ff--- /dev/null+++ b/agent/src/quantlib/fixedincome.py@@ -0,0 +1,793 @@+"""Fixed-income primitives: day count, bond math and yield-curve fitting.++This module is the executable form of the formulas that used to live as markdown+code blocks in ``src/skills/credit-analysis/SKILL.md``. Two things are deliberately+different from the markdown originals:++* **Day count is explicit.** The markdown priced everything in whole coupon+ periods, which silently assumes settlement lands exactly on a coupon date and+ that no accrued interest is owed. :func:`year_fraction` and+ :func:`accrued_interest` make that assumption visible and adjustable.+* **Compounding is explicit.** The markdown hard-coded discrete periodic+ compounding at ``freq``. That is still the default (``compounding="discrete"``),+ but continuous compounding is selectable.++All rates are decimals (``0.05`` means 5%), all maturities/horizons are in years,+and every duration/convexity figure is returned in years (or years squared),+never in coupon periods.+"""++from __future__ import annotations++import datetime as _dt+import math+from collections.abc import Callable, Sequence+from dataclasses import dataclass++import numpy as np+from scipy.optimize import brentq, minimize++__all__ = [+ "DAY_COUNT_CONVENTIONS",+ "DEFAULT_DAY_COUNT",+ "COMPOUNDING_CONVENTIONS",+ "DEFAULT_COMPOUNDING",+ "CurveFit",+ "year_fraction",+ "accrued_interest",+ "bond_cashflows",+ "bond_price",+ "ytm_solve",+ "macaulay_duration",+ "modified_duration",+ "convexity",+ "dv01",+ "effective_duration",+ "nelson_siegel",+ "svensson",+ "fit_yield_curve",+]++#: Day-count conventions understood by :func:`year_fraction`.+DAY_COUNT_CONVENTIONS: tuple[str, ...] = (+ "ACT/365F",+ "ACT/360",+ "ACT/ACT",+ "30/360",+ "30E/360",+)++#: Convention assumed when the caller does not name one.+DEFAULT_DAY_COUNT: str = "ACT/365F"++#: Compounding conventions understood by the pricing functions.+COMPOUNDING_CONVENTIONS: tuple[str, ...] = ("discrete", "continuous")++#: Compounding assumed when the caller does not name one (the markdown's behaviour).+DEFAULT_COMPOUNDING: str = "discrete"+++def year_fraction(+ start: _dt.date,+ end: _dt.date,+ day_count: str = DEFAULT_DAY_COUNT,+) -> float:+ """Accrual factor between two dates under a named day-count convention.++ Args:+ start: Period start (accrual runs from this date, inclusive).+ end: Period end (accrual runs to this date, exclusive).+ day_count: One of :data:`DAY_COUNT_CONVENTIONS`. ``ACT/ACT`` is the+ ISDA variant: each calendar year contributes+ ``days_in_that_year / (365 or 366)``.++ Returns:+ Year fraction as a float. Negative if ``end`` precedes ``start``.++ Raises:+ ValueError: If ``day_count`` is not a recognised convention.+ """+ if day_count not in DAY_COUNT_CONVENTIONS:+ raise ValueError(+ f"unknown day_count {day_count!r}; expected one of {DAY_COUNT_CONVENTIONS}"+ )++ if end < start:+ return -year_fraction(end, start, day_count)++ if day_count == "ACT/365F":+ return (end - start).days / 365.0+ if day_count == "ACT/360":+ return (end - start).days / 360.0+ if day_count in ("30/360", "30E/360"):+ d1, d2 = start.day, end.day+ if day_count == "30/360":+ # US bond basis: clip D1 to 30, then clip D2 only when the ADJUSTED+ # D1 is 30. That fires whether D1 was clipped down from 31 or was+ # already 30 -- both are the ISDA rule. Hand-checked: 2024-01-30 to+ # 2024-03-31 gives 60/360, 2024-01-29 to 2024-03-31 gives 62/360.+ if d1 == 31:+ d1 = 30+ if d2 == 31 and d1 == 30:+ d2 = 30+ else: # 30E/360 (Eurobond basis) clips both legs unconditionally.+ d1 = min(d1, 30)+ d2 = min(d2, 30)+ months = 12 * (end.year - start.year) + (end.month - start.month)+ return (30.0 * months + (d2 - d1)) / 360.0++ # ACT/ACT (ISDA): accumulate each calendar year against its own basis.+ total = 0.0+ cursor = start+ while cursor < end:+ year_end = _dt.date(cursor.year + 1, 1, 1)+ chunk_end = min(year_end, end)+ basis = 366.0 if _is_leap(cursor.year) else 365.0+ total += (chunk_end - cursor).days / basis+ cursor = chunk_end+ return total+++def _is_leap(year: int) -> bool:+ """Report whether a Gregorian year is a leap year.++ Args:+ year: Four-digit calendar year.++ Returns:+ True when the year has 366 days.+ """+ return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)+++def accrued_interest(+ face: float,+ coupon_rate: float,+ freq: int,+ last_coupon: _dt.date,+ settlement: _dt.date,+ next_coupon: _dt.date,+ day_count: str = DEFAULT_DAY_COUNT,+) -> float:+ """Interest earned by the seller between the last coupon and settlement.++ Dirty price = clean price + accrued interest. :func:`bond_price` returns the+ price on a coupon date, where accrued interest is zero by construction; use+ this function to move a mid-period settlement onto that basis.++ Args:+ face: Par amount the coupon is computed on.+ coupon_rate: Annual coupon rate as a decimal.+ freq: Coupon payments per year (1 = annual, 2 = semi-annual).+ last_coupon: Date of the most recent coupon payment.+ settlement: Settlement date of the trade.+ next_coupon: Date of the upcoming coupon payment.+ day_count: One of :data:`DAY_COUNT_CONVENTIONS`.++ Returns:+ Accrued interest in the same currency units as ``face``.++ Raises:+ ValueError: If ``freq`` is not positive, if the coupon dates are not+ ordered, or if ``settlement`` falls outside the coupon period.+ """+ if freq <= 0:+ raise ValueError(f"freq must be positive, got {freq}")+ if not last_coupon < next_coupon:+ raise ValueError("last_coupon must precede next_coupon")+ if not last_coupon <= settlement <= next_coupon:+ raise ValueError("settlement must fall inside [last_coupon, next_coupon]")++ period = year_fraction(last_coupon, next_coupon, day_count)+ if period == 0.0:+ return 0.0+ elapsed = year_fraction(last_coupon, settlement, day_count)+ return face * coupon_rate / freq * (elapsed / period)+++def bond_cashflows(+ face: float,+ coupon_rate: float,+ n_periods: int,+ freq: int = 1,+) -> tuple[np.ndarray, np.ndarray]:+ """Coupon schedule of a bullet bond, in periods and amounts.++ Args:+ face: Redemption amount paid with the final coupon.+ coupon_rate: Annual coupon rate as a decimal.+ n_periods: Number of remaining coupon periods.+ freq: Coupon payments per year.++ Returns:+ Tuple ``(periods, amounts)`` where ``periods`` is ``1..n_periods`` as+ floats and ``amounts`` is the cash paid at each. Time in years is+ ``periods / freq``.++ Raises:+ ValueError: If ``face`` is not positive, if ``n_periods`` is not a+ positive integer, or if ``freq`` is not positive.+ """+ if face <= 0:+ # Guarding here rather than in each caller is what makes the guard+ # coherent: dv01 divides a price by face, so a negative face cancels its+ # own sign error and returns a confidently positive risk number.+ raise ValueError(f"face must be positive, got {face}")+ if isinstance(n_periods, bool) or not isinstance(n_periods, (int, np.integer)):+ # A float slips past `<= 0` and dies inside np.full with a numpy message+ # that names neither the argument nor this function.+ raise ValueError(f"n_periods must be an integer, got {n_periods!r}")+ if n_periods <= 0:+ raise ValueError(f"n_periods must be positive, got {n_periods}")+ if freq <= 0:+ raise ValueError(f"freq must be positive, got {freq}")++ periods = np.arange(1, n_periods + 1, dtype=float)+ amounts = np.full(n_periods, face * coupon_rate / freq, dtype=float)+ amounts[-1] += face+ return periods, amounts+++def _discount_factors(+ ytm: float,+ periods: np.ndarray,+ freq: int,+ compounding: str,+) -> np.ndarray:+ """Discount factors for a set of period indices.++ Args:+ ytm: Annual yield as a decimal.+ periods: Period indices (1-based, in units of ``1 / freq`` years).+ freq: Coupon payments per year.+ compounding: One of :data:`COMPOUNDING_CONVENTIONS`.++ Returns:+ Array of discount factors aligned with ``periods``.++ Raises:+ ValueError: If ``compounding`` is unknown or the discrete periodic yield+ is at or below -100%, which makes the discount factor undefined.+ """+ if compounding == "discrete":+ periodic = 1.0 + ytm / freq+ if periodic <= 0.0:+ raise ValueError(+ f"discrete compounding needs 1 + ytm/freq > 0, got {periodic}"+ )+ return periodic ** (-periods)+ if compounding == "continuous":+ return np.exp(-ytm * periods / freq)+ raise ValueError(+ f"unknown compounding {compounding!r}; expected one of {COMPOUNDING_CONVENTIONS}"+ )+++def bond_price(+ face: float,+ coupon_rate: float,+ ytm: float,+ n_periods: int,+ freq: int = 1,+ compounding: str = DEFAULT_COMPOUNDING,+) -> float:+ """Present value of a bullet bond settling on a coupon date.++ The result is a *clean* price: settlement is assumed to sit on a coupon date+ so no interest has accrued. Add :func:`accrued_interest` for a dirty price.++ Args:+ face: Par/redemption amount, conventionally 100.+ coupon_rate: Annual coupon rate as a decimal (0.05 == 5%).+ ytm: Annual yield to maturity as a decimal.+ n_periods: Number of remaining coupon periods.+ freq: Coupon payments per year (1 = annual, 2 = semi-annual).+ compounding: One of :data:`COMPOUNDING_CONVENTIONS`.++ Returns:+ Present value in the same units as ``face``.++ Raises:+ ValueError: If the schedule arguments or ``compounding`` are invalid.++ Examples:+ >>> round(bond_price(100, 0.05, 0.04, 5), 4)+ 104.4518+ """+ periods, amounts = bond_cashflows(face, coupon_rate, n_periods, freq)+ return float(amounts @ _discount_factors(ytm, periods, freq, compounding))+++def ytm_solve(+ price: float,+ face: float,+ coupon_rate: float,+ n_periods: int,+ freq: int = 1,+ compounding: str = DEFAULT_COMPOUNDING,+ bracket: tuple[float, float] = (-0.5, 10.0),+) -> float:+ """Invert :func:`bond_price` for the yield that reproduces a market price.++ Args:+ price: Observed price, on the same clean basis as :func:`bond_price`.+ face: Par/redemption amount.+ coupon_rate: Annual coupon rate as a decimal.+ n_periods: Number of remaining coupon periods.+ freq: Coupon payments per year.+ compounding: One of :data:`COMPOUNDING_CONVENTIONS`.+ bracket: ``(low, high)`` annual yields to search between. The default+ spans -50% to +1000%, which covers every traded bond; widen it only+ if you know the root sits outside.++ Returns:+ Annual yield to maturity as a decimal.++ Raises:+ ValueError: If the price is not reachable inside ``bracket``.+ """+ low, high = bracket+ if low >= high:+ raise ValueError(f"bracket must be increasing, got {bracket}")++ def pv_diff(y: float) -> float:+ return bond_price(face, coupon_rate, y, n_periods, freq, compounding) - price++ try:+ return float(brentq(pv_diff, low, high))+ except ValueError as exc:+ raise ValueError(+ f"no yield in {bracket} reprices this bond to {price}: {exc}"+ ) from exc+++def macaulay_duration(+ face: float,+ coupon_rate: float,+ ytm: float,+ n_periods: int,+ freq: int = 1,+ compounding: str = DEFAULT_COMPOUNDING,+) -> float:+ """Present-value-weighted average time to the bond's cash flows.++ Args:+ face: Par/redemption amount.+ coupon_rate: Annual coupon rate as a decimal.+ ytm: Annual yield to maturity as a decimal.+ n_periods: Number of remaining coupon periods.+ freq: Coupon payments per year.+ compounding: One of :data:`COMPOUNDING_CONVENTIONS`.++ Returns:+ Macaulay duration in **years**.++ Raises:+ ValueError: If the schedule arguments or ``compounding`` are invalid.+ """+ periods, amounts = bond_cashflows(face, coupon_rate, n_periods, freq)+ pv = amounts * _discount_factors(ytm, periods, freq, compounding)+ return float((periods / freq) @ pv / pv.sum())+++def modified_duration(+ face: float,+ coupon_rate: float,+ ytm: float,+ n_periods: int,+ freq: int = 1,+ compounding: str = DEFAULT_COMPOUNDING,+) -> float:+ """Semi-elasticity of price to yield, ``-(dP/dy)/P``.++ Args:+ face: Par/redemption amount.+ coupon_rate: Annual coupon rate as a decimal.+ ytm: Annual yield to maturity as a decimal.+ n_periods: Number of remaining coupon periods.+ freq: Coupon payments per year.+ compounding: One of :data:`COMPOUNDING_CONVENTIONS`. Under continuous+ compounding modified duration equals Macaulay duration.++ Returns:+ Modified duration in years, positive for a conventional bond.++ Raises:+ ValueError: If the schedule arguments or ``compounding`` are invalid.+ """+ d_mac = macaulay_duration(face, coupon_rate, ytm, n_periods, freq, compounding)+ if compounding == "continuous":+ return d_mac+ return d_mac / (1.0 + ytm / freq)+++def convexity(+ face: float,+ coupon_rate: float,+ ytm: float,+ n_periods: int,+ freq: int = 1,+ compounding: str = DEFAULT_COMPOUNDING,+) -> float:+ """Second-order price sensitivity to yield, ``(d2P/dy2)/P``.++ Args:+ face: Par/redemption amount.+ coupon_rate: Annual coupon rate as a decimal.+ ytm: Annual yield to maturity as a decimal.+ n_periods: Number of remaining coupon periods.+ freq: Coupon payments per year.+ compounding: One of :data:`COMPOUNDING_CONVENTIONS`.++ Returns:+ Convexity in years squared. Positive for any bond without embedded+ short optionality.++ Raises:+ ValueError: If the schedule arguments or ``compounding`` are invalid.+ """+ periods, amounts = bond_cashflows(face, coupon_rate, n_periods, freq)+ discounts = _discount_factors(ytm, periods, freq, compounding)+ pv = amounts * discounts+ price = pv.sum()+ if compounding == "continuous":+ return float(((periods / freq) ** 2) @ pv / price)+ weights = periods * (periods + 1.0) / (freq**2)+ return float(weights @ pv / price / (1.0 + ytm / freq) ** 2)+++def dv01(+ face: float,+ coupon_rate: float,+ ytm: float,+ n_periods: int,+ freq: int = 1,+ par_amount: float = 1_000_000.0,+ compounding: str = DEFAULT_COMPOUNDING,+) -> float:+ """Cash value of one basis point on a stated par position.++ Args:+ face: Par/redemption amount the quoted price is per, conventionally 100.+ coupon_rate: Annual coupon rate as a decimal.+ ytm: Annual yield to maturity as a decimal.+ n_periods: Number of remaining coupon periods.+ freq: Coupon payments per year.+ par_amount: Par value held. The market value hedged is+ ``par_amount * price / face``.+ compounding: One of :data:`COMPOUNDING_CONVENTIONS`.++ Returns:+ Price change, in currency units, for a 1bp rise in yield, reported as a+ positive number.++ Raises:+ ValueError: If ``face`` is zero, or the schedule/compounding is invalid.+ """+ if face == 0:+ raise ValueError("face must be non-zero")+ d_mod = modified_duration(face, coupon_rate, ytm, n_periods, freq, compounding)+ price = bond_price(face, coupon_rate, ytm, n_periods, freq, compounding)+ return d_mod * (price / face) * 1e-4 * par_amount+++def effective_duration(+ reprice: Callable[[float], float],+ yield_level: float,+ bump: float = 1e-4,+) -> float:+ """Duration by symmetric repricing, valid for bonds with embedded options.++ Analytic duration assumes the cash flows do not move when the yield does.+ For a callable bond or an MBS they do, so the sensitivity has to come from+ a pricing model that is re-run at each shifted yield.++ Args:+ reprice: Callable mapping a yield level to a price. It must contain the+ option/prepayment logic; nothing here inspects it.+ yield_level: Base yield to bump around.+ bump: Half-width of the symmetric shock, as a decimal (1e-4 = 1bp).++ Returns:+ Effective duration in years, ``(P_down - P_up) / (2 * P_0 * bump)``.++ Raises:+ ValueError: If ``bump`` is not positive or the base price is zero.+ """+ if bump <= 0:+ raise ValueError(f"bump must be positive, got {bump}")+ base = reprice(yield_level)+ if base == 0:+ raise ValueError("base price is zero; effective duration is undefined")+ down = reprice(yield_level - bump)+ up = reprice(yield_level + bump)+ return (down - up) / (2.0 * base * bump)+++def _decay_factors(tau: np.ndarray, lam: float) -> tuple[np.ndarray, np.ndarray]:+ """Nelson-Siegel slope and curvature loadings for one decay parameter.++ Args:+ tau: Maturities in years, non-negative.+ lam: Decay parameter in years, strictly positive.++ Returns:+ Tuple ``(slope_loading, curvature_loading)``. At ``tau == 0`` the limits+ 1 and 0 are used rather than dividing by zero.++ Raises:+ ValueError: If ``lam`` is not strictly positive.+ """+ if lam <= 0:+ raise ValueError(f"decay parameter must be positive, got {lam}")+ x = tau / lam+ safe = np.where(x > 0, x, 1.0)+ slope = np.where(x > 0, (1.0 - np.exp(-safe)) / safe, 1.0)+ return slope, slope - np.exp(-x)+++def _as_tau(tau: float | Sequence[float] | np.ndarray) -> tuple[np.ndarray, bool]:+ """Normalise a maturity argument to a float array.++ Args:+ tau: Scalar maturity or a sequence of maturities in years.++ Returns:+ Tuple ``(array, was_scalar)``.++ Raises:+ ValueError: If any maturity is negative.+ """+ arr = np.asarray(tau, dtype=float)+ was_scalar = arr.ndim == 0+ arr = np.atleast_1d(arr)+ if np.any(arr < 0):+ raise ValueError("maturities must be non-negative")+ return arr, was_scalar+++def nelson_siegel(+ tau: float | Sequence[float] | np.ndarray,+ beta0: float,+ beta1: float,+ beta2: float,+ lambda1: float,+) -> float | np.ndarray:+ """Nelson-Siegel zero-rate curve.++ Args:+ tau: Maturity or maturities in years.+ beta0: Level factor; the asymptotic long rate.+ beta1: Slope factor; ``beta0 + beta1`` is the instantaneous short rate.+ beta2: Curvature factor; peaks near ``lambda1``.+ lambda1: Decay parameter in years, strictly positive.++ Returns:+ Zero rate(s) as decimals. A float when ``tau`` was scalar, else an array.++ Raises:+ ValueError: If ``lambda1`` is not positive or a maturity is negative.+ """+ arr, was_scalar = _as_tau(tau)+ slope, curve = _decay_factors(arr, lambda1)+ out = beta0 + beta1 * slope + beta2 * curve+ return float(out[0]) if was_scalar else out+++def svensson(+ tau: float | Sequence[float] | np.ndarray,+ beta0: float,+ beta1: float,+ beta2: float,+ beta3: float,+ lambda1: float,+ lambda2: float,+) -> float | np.ndarray:+ """Svensson curve: Nelson-Siegel plus a second curvature hump.++ Args:+ tau: Maturity or maturities in years.+ beta0: Level factor.+ beta1: Slope factor.+ beta2: First curvature factor, decaying at ``lambda1``.+ beta3: Second curvature factor, decaying at ``lambda2``.+ lambda1: First decay parameter in years, strictly positive.+ lambda2: Second decay parameter in years, strictly positive.++ Returns:+ Zero rate(s) as decimals. A float when ``tau`` was scalar, else an array.++ Raises:+ ValueError: If a decay parameter is not positive or a maturity is negative.+ """+ arr, was_scalar = _as_tau(tau)+ slope, curve1 = _decay_factors(arr, lambda1)+ _, curve2 = _decay_factors(arr, lambda2)+ out = beta0 + beta1 * slope + beta2 * curve1 + beta3 * curve2+ return float(out[0]) if was_scalar else out+++#: Search range, in years, for the Nelson-Siegel/Svensson decay parameters.+CURVE_DECAY_BOUNDS: tuple[float, float] = (0.05, 30.0)++#: Number of grid points per decay parameter used to seed the curve fit.+CURVE_DECAY_GRID: int = 48+++@dataclass(frozen=True)+class CurveFit:+ """Result of :func:`fit_yield_curve`; call it to evaluate the fitted curve.++ Attributes:+ model: ``"nelson_siegel"`` or ``"svensson"``.+ params: Fitted parameters. Nelson-Siegel is+ ``(beta0, beta1, beta2, lambda1)``; Svensson is+ ``(beta0, beta1, beta2, beta3, lambda1, lambda2)``.+ rmse: Root-mean-square fitting error against the input yields, in the+ same units as those yields (decimals). Defaults to ``nan``, not+ zero: a hand-constructed curve has not been fitted to anything, and+ a default of 0.0 would let it report a perfect fit it never+ achieved. :func:`fit_yield_curve` always populates it.+ """++ model: str+ params: tuple[float, ...]+ rmse: float = math.nan++ def __call__(+ self, tau: float | Sequence[float] | np.ndarray+ ) -> float | np.ndarray:+ """Evaluate the fitted curve at one or more maturities.++ Args:+ tau: Maturity or maturities in years.++ Returns:+ Zero rate(s) as decimals.++ Raises:+ ValueError: If the stored model name is not recognised.+ """+ if self.model == "nelson_siegel":+ return nelson_siegel(tau, *self.params)+ if self.model == "svensson":+ return svensson(tau, *self.params)+ raise ValueError(f"unknown curve model {self.model!r}")+++def _curve_design(tau: np.ndarray, lambdas: Sequence[float]) -> np.ndarray:+ """Linear design matrix for a curve model with fixed decay parameters.++ Args:+ tau: Maturities in years.+ lambdas: One decay parameter for Nelson-Siegel, two for Svensson.++ Returns:+ Matrix whose columns are the level, slope and curvature loadings.++ Raises:+ ValueError: If a decay parameter is not positive.+ """+ slope, curve1 = _decay_factors(tau, lambdas[0])+ columns = [np.ones_like(tau), slope, curve1]+ for lam in lambdas[1:]:+ columns.append(_decay_factors(tau, lam)[1])+ return np.column_stack(columns)+++def _profiled_ssr(+ lambdas: Sequence[float], tau: np.ndarray, yields: np.ndarray+) -> tuple[float, np.ndarray]:+ """Best achievable squared error for fixed decay parameters.++ The betas enter the curve linearly, so for any decay parameters the optimal+ betas come from ordinary least squares. Only the decay parameters need a+ non-linear search, which is what makes the fit reliable.++ Args:+ lambdas: Decay parameters to condition on.+ tau: Maturities in years.+ yields: Observed zero rates aligned with ``tau``.++ Returns:+ Tuple ``(sum_of_squared_residuals, betas)``. The SSR is ``inf`` when the+ decay parameters are outside the admissible range.+ """+ if any(lam <= 0 for lam in lambdas):+ return float("inf"), np.zeros(len(lambdas) + 2)+ design = _curve_design(tau, lambdas)+ betas, *_ = np.linalg.lstsq(design, yields, rcond=None)+ residual = design @ betas - yields+ return float(residual @ residual), betas+++def fit_yield_curve(+ maturities: Sequence[float] | np.ndarray,+ yields: Sequence[float] | np.ndarray,+ model: str = "svensson",+ decay_bounds: tuple[float, float] = CURVE_DECAY_BOUNDS,+ grid_points: int = CURVE_DECAY_GRID,+) -> CurveFit:+ """Fit a Nelson-Siegel or Svensson curve to observed zero rates.++ The betas are solved exactly by least squares at every candidate decay+ parameter, and only the one or two decay parameters are searched -- first on+ a log-spaced grid, then refined with Nelder-Mead. This matters: a+ single-start L-BFGS-B over all parameters at once, which is what the skill's+ old markdown template did, cannot recover a curve it generated itself. On a+ 10-tenor noise-free Nelson-Siegel curve it stops at an RMSE of 6.4e-4+ (6.4bp) against this function's 4.0e-14.++ Args:+ maturities: Maturities in years, strictly positive.+ yields: Zero rates as decimals, aligned with ``maturities``.+ model: ``"nelson_siegel"`` or ``"svensson"``.+ decay_bounds: ``(low, high)`` search range in years for each decay+ parameter.+ grid_points: Grid resolution per decay parameter for the coarse pass.++ Returns:+ A :class:`CurveFit`, callable at arbitrary maturities.++ Raises:+ ValueError: If ``model`` is unknown, the inputs disagree in length, or+ there are fewer observations than free parameters.+ """+ if model not in ("nelson_siegel", "svensson"):+ raise ValueError(+ f"unknown model {model!r}; expected 'nelson_siegel' or 'svensson'"+ )+ tau = np.asarray(maturities, dtype=float)+ obs = np.asarray(yields, dtype=float)+ if tau.shape != obs.shape or tau.ndim != 1:+ raise ValueError("maturities and yields must be 1-D and the same length")+ if np.any(tau <= 0):+ raise ValueError("maturities must be strictly positive")++ n_decay = 1 if model == "nelson_siegel" else 2+ n_params = n_decay + 2 + n_decay # betas + decay parameters+ if tau.size < n_params:+ raise ValueError(+ f"{model} has {n_params} parameters but only {tau.size} observations"+ )++ low, high = decay_bounds+ if not 0 < low < high:+ raise ValueError(f"decay_bounds must satisfy 0 < low < high, got {decay_bounds}")+ grid = np.geomspace(low, high, grid_points)++ best_ssr = float("inf")+ best_lambdas: tuple[float, ...] = (grid[0],) * n_decay+ if n_decay == 1:+ candidates = [(lam,) for lam in grid]+ else:+ # lambda1 == lambda2 makes the two curvature columns identical, so the+ # second hump carries no information; keep the pairs separated.+ candidates = [+ (short, long) for short in grid for long in grid if long > short * 1.05+ ]+ for lambdas in candidates:+ ssr, _ = _profiled_ssr(lambdas, tau, obs)+ if ssr < best_ssr:+ best_ssr, best_lambdas = ssr, lambdas++ refined = minimize(+ lambda p: _profiled_ssr(np.exp(p), tau, obs)[0],+ np.log(best_lambdas),+ method="Nelder-Mead",+ options={"xatol": 1e-10, "fatol": 1e-18, "maxiter": 4000},+ )+ refined_lambdas = tuple(float(v) for v in np.exp(refined.x))+ refined_ssr, refined_betas = _profiled_ssr(refined_lambdas, tau, obs)+ if refined_ssr < best_ssr:+ best_ssr, best_lambdas = refined_ssr, refined_lambdas+ betas = refined_betas+ else:+ _, betas = _profiled_ssr(best_lambdas, tau, obs)++ params = tuple(float(b) for b in betas) + tuple(float(x) for x in best_lambdas)+ return CurveFit(+ model=model,+ params=params,+ rmse=float(np.sqrt(max(best_ssr, 0.0) / tau.size)),+ )diff --git a/agent/src/quantlib/impact.py b/agent/src/quantlib/impact.pynew file mode 100644index 000000000..b56d6cd40--- /dev/null+++ b/agent/src/quantlib/impact.py@@ -0,0 +1,267 @@+"""Market-impact and slippage models for backtest execution.++Four models, ordered by how much of the order book they claim to know:++========================= ================================== =====================+Model Impact Use when+========================= ================================== =====================+:func:`fixed_slippage` constant ``bps`` order < 0.5% of ADV+:func:`linear_impact` ``coeff * V / ADV`` order 0.5-5% of ADV+:func:`sqrt_impact` ``eta * sigma * sqrt(V / ADV)`` order > 5% of ADV+:func:`delayed_execution` shifts a signal forward in time always, for signal lag+========================= ================================== =====================++All three price models compute a non-negative impact and push the fill price+*against* the trader -- up when buying, down when selling.++The two size-aware models, :func:`linear_impact` and :func:`sqrt_impact`, are+additionally monotone non-decreasing in order size and return the untouched price+at zero size. :func:`fixed_slippage` takes no size at all: it charges its ``bps``+on every fill regardless of how small, which is the whole point of a fixed model+and the reason it is only appropriate below roughly 0.5% of ADV.++Every function here is scalar-only. Passing a numpy array or a pandas Series where+a ``float`` is documented raises rather than broadcasting.++These are backtest primitives. Nothing here places, routes or prices a live order.++Note on naming: the square-root model is frequently labelled "Almgren-Chriss" and+is indeed the impact term from that literature, but this module does **not**+implement Almgren-Chriss optimal execution -- there is no trading trajectory, no+permanent/temporary impact split and no risk-aversion parameter. Call it what it+is: a square-root impact function.+"""++from __future__ import annotations++import numpy as np+import pandas as pd+from numpy.typing import ArrayLike++#: Default fixed slippage in basis points (1bp = 0.01%).+DEFAULT_SLIPPAGE_BPS = 5.0++#: Default linear-impact coefficient; 0.05-0.2 is the usual calibrated range.+DEFAULT_LINEAR_IMPACT_COEFF = 0.1++#: Default square-root impact elasticity; 0.3-0.8 is the usual calibrated range.+DEFAULT_SQRT_IMPACT_ETA = 0.5++#: Default execution lag in bars. 1 bar matches the China A-share T+1 rule.+DEFAULT_DELAY_BARS = 1++#: Basis points in one unit (100%).+_BPS_PER_UNIT = 10_000.0+++def _check_order(price: ArrayLike, direction: int) -> np.ndarray:+ """Validate the price and side shared by every price-impact model.++ Args:+ price: Reference price before impact; scalar or array-like.+ direction: 1 to buy, -1 to sell.++ Returns:+ ``price`` as a float array (0-d for a scalar input).++ Raises:+ ValueError: If any ``price`` is not strictly positive, or if+ ``direction`` is anything other than 1 or -1. Direction multiplies+ the impact, so a value such as 2 would silently double the modelled+ cost.+ """+ prices = np.asarray(price, dtype=float)+ if not np.all(prices > 0.0):+ raise ValueError(f"price must be strictly positive, got {price!r}")+ if direction not in (1, -1):+ raise ValueError(f"direction must be 1 (buy) or -1 (sell), got {direction!r}")+ return prices+++def _participation_rate(volume_traded: ArrayLike, adv: ArrayLike) -> np.ndarray:+ """Return the order size as a fraction of average daily volume.++ Args:+ volume_traded: Order size, in the same unit as ``adv``.+ adv: Average daily volume, strictly positive.++ Returns:+ ``volume_traded / adv``, broadcast over both arguments.++ Raises:+ ValueError: If any ``volume_traded`` is negative or any ``adv`` is not+ strictly positive. A zero ``adv`` means the instrument does not+ trade, for which no impact model has an answer.+ """+ volumes = np.asarray(volume_traded, dtype=float)+ advs = np.asarray(adv, dtype=float)+ if not np.all(volumes >= 0.0):+ raise ValueError(f"volume_traded must be non-negative, got {volume_traded!r}")+ if not np.all(advs > 0.0):+ raise ValueError(f"adv must be strictly positive, got {adv!r}")+ return volumes / advs+++def _fill(prices: np.ndarray, direction: int, impact: np.ndarray) -> float | np.ndarray:+ """Apply a relative impact to a price and return the fill.++ Args:+ prices: Validated reference prices as a float array.+ direction: 1 to buy, -1 to sell.+ impact: Relative impact, same shape or broadcastable.++ Returns:+ The fill price -- a float for scalar input, an ndarray otherwise, so a+ scalar call never has to unwrap a 0-d array.++ Raises:+ ValueError: If the impact is large enough to drive a sell fill to zero+ or below. Both functions reject a non-positive input price, so+ returning one is incoherent: a sell filling at a negative price+ books a nonsensical profit. An order that large is outside the+ model's calibrated domain and the honest answer is a refusal, not+ an extrapolation.+ """+ fill = prices * (1.0 + direction * impact)+ if not np.all(fill > 0.0):+ raise ValueError(+ "impact drives the fill price to zero or below "+ f"(max relative impact {float(np.max(impact)):.4g}); the order is "+ "outside the model's domain -- split it or use a fill model that "+ "accounts for depth"+ )+ return float(fill) if fill.ndim == 0 else fill+++def fixed_slippage(price: float, direction: int, bps: float = DEFAULT_SLIPPAGE_BPS) -> float:+ """Apply a constant basis-point slippage to a fill price.++ The cheapest model, and adequate whenever the order is small enough that it+ does not move the book -- roughly under 0.5% of average daily volume.++ Args:+ price: Reference price before slippage.+ direction: 1 to buy, -1 to sell.+ bps: Slippage in basis points. Defaults to :data:`DEFAULT_SLIPPAGE_BPS`.++ Returns:+ The fill price after slippage: worse than ``price`` for both sides.++ Raises:+ ValueError: If ``price`` is not strictly positive, ``direction`` is not 1+ or -1, or ``bps`` is negative.+ """+ prices = _check_order(price, direction)+ rates = np.asarray(bps, dtype=float)+ if not np.all(rates >= 0.0):+ raise ValueError(f"bps must be non-negative, got {bps!r}")+ return _fill(prices, direction, rates / _BPS_PER_UNIT)+++def linear_impact(+ price: float,+ direction: int,+ volume_traded: float,+ adv: float,+ impact_coeff: float = DEFAULT_LINEAR_IMPACT_COEFF,+) -> float:+ """Apply market impact proportional to the participation rate.++ Impact is ``impact_coeff * volume_traded / adv``. Marginal impact is constant,+ which overstates the cost of very large orders; prefer :func:`sqrt_impact`+ once the order exceeds roughly 5% of average daily volume.++ Args:+ price: Reference price before impact.+ direction: 1 to buy, -1 to sell.+ volume_traded: Order size, in the same unit as ``adv``.+ adv: Average daily volume, strictly positive.+ impact_coeff: Impact coefficient. Defaults to+ :data:`DEFAULT_LINEAR_IMPACT_COEFF`.++ Returns:+ The fill price after impact.++ Raises:+ ValueError: If ``price`` is not strictly positive, ``direction`` is not 1+ or -1, ``volume_traded`` is negative, ``adv`` is not strictly+ positive, or ``impact_coeff`` is negative.+ """+ prices = _check_order(price, direction)+ coeffs = np.asarray(impact_coeff, dtype=float)+ if not np.all(coeffs >= 0.0):+ raise ValueError(f"impact_coeff must be non-negative, got {impact_coeff!r}")+ return _fill(prices, direction, coeffs * _participation_rate(volume_traded, adv))+++def sqrt_impact(+ price: float,+ direction: int,+ volume_traded: float,+ adv: float,+ volatility: float,+ eta: float = DEFAULT_SQRT_IMPACT_ETA,+) -> float:+ """Apply square-root market impact, the best empirically supported form.++ Impact is ``eta * volatility * sqrt(volume_traded / adv)``. Marginal impact+ falls as the order grows, which matches observed execution data far better+ than the linear form.++ This is the impact term familiar from the Almgren-Chriss literature; it is not+ Almgren-Chriss optimal execution, which additionally solves for a trading+ trajectory under a risk-aversion penalty. No trajectory is computed here.++ Args:+ price: Reference price before impact.+ direction: 1 to buy, -1 to sell.+ volume_traded: Order size, in the same unit as ``adv``.+ adv: Average daily volume, strictly positive.+ volatility: Daily return volatility as a decimal fraction, non-negative.+ eta: Impact elasticity. Defaults to :data:`DEFAULT_SQRT_IMPACT_ETA`.++ Returns:+ The fill price after impact.++ Raises:+ ValueError: If ``price`` is not strictly positive, ``direction`` is not 1+ or -1, ``volume_traded`` is negative, ``adv`` is not strictly+ positive, or ``volatility`` or ``eta`` is negative.+ """+ prices = _check_order(price, direction)+ vols = np.asarray(volatility, dtype=float)+ etas = np.asarray(eta, dtype=float)+ if not np.all(vols >= 0.0):+ raise ValueError(f"volatility must be non-negative, got {volatility!r}")+ if not np.all(etas >= 0.0):+ raise ValueError(f"eta must be non-negative, got {eta!r}")+ impact = etas * vols * np.sqrt(_participation_rate(volume_traded, adv))+ return _fill(prices, direction, impact)+++def delayed_execution(signal_series: pd.Series, delay_bars: int = DEFAULT_DELAY_BARS) -> pd.Series:+ """Shift a signal forward to model the lag between decision and fill.++ A signal computed from a bar's data cannot be traded on that same bar. Shifting+ it forward is what keeps a backtest honest.++ Args:+ signal_series: Signal indexed in chronological order.+ delay_bars: Bars to delay by. Defaults to :data:`DEFAULT_DELAY_BARS`+ (T+1). 0 means same-bar execution.++ Returns:+ The signal shifted forward by ``delay_bars``, with the leading positions+ set to NaN by the shift.++ Raises:+ TypeError: If ``signal_series`` is not a :class:`pandas.Series`.+ ValueError: If ``delay_bars`` is negative. A negative shift would pull+ future signal values into the past, which is look-ahead bias and+ silently inflates every backtest that contains it.+ """+ if not isinstance(signal_series, pd.Series):+ raise TypeError(f"signal_series must be a pandas Series, got {type(signal_series).__name__}")+ if delay_bars < 0:+ raise ValueError(f"delay_bars must be non-negative; a negative shift is look-ahead bias, got {delay_bars!r}")+ return signal_series.shift(delay_bars)diff --git a/agent/src/quantlib/options.py b/agent/src/quantlib/options.pynew file mode 100644index 000000000..09f320f23--- /dev/null+++ b/agent/src/quantlib/options.py@@ -0,0 +1,371 @@+"""Black-Scholes pricing, Greeks and implied-volatility inversion.++One implementation, called by both the backtest engine and the+``options-payoff`` skill. It merges two copies that had drifted apart: the+engine's (``backtest/engines/options_portfolio.py``, no dividend yield, no rho,+but with correct degenerate-input handling) and the skill's markdown listing+(dividend yield and rho, but it crashed on a non-positive spot/strike and+reported a zero delta for an expiring in-the-money option).++Conventions, fixed here so callers never have to guess:+ * ``T`` is in years, ``r`` and ``q`` are continuously compounded annual rates.+ * ``theta`` is per calendar day, ``vega`` and ``rho`` are per 1 percentage+ point of volatility / rate. ``delta`` and ``gamma`` are per 1.0 of spot.+ * Nothing is rounded. Rounding is a presentation decision and it destroys the+ vega precision the implied-volatility solver needs.++Degenerate inputs (``T <= 0``, ``sigma <= 0``, ``S <= 0`` or ``K <= 0``) collapse+the lognormal to a point mass, so the price is the intrinsic value and every+second-order Greek is zero. They return that rather than raising, because an+expiring or zero-strike leg is a normal state for a backtest to walk through.+"""++from __future__ import annotations++from typing import Dict++import numpy as np+from scipy.optimize import brentq+from scipy.stats import norm++__all__ = ["bs_price", "bs_greeks", "implied_volatility", "normalise_option_type"]++#: Widest volatility the implied-vol search will consider (1000% annualised).+#: Anything solving above this is an outlier or a bad print, not a vol.+MAX_SIGMA = 10.0+#: Narrowest volatility the search will consider; the bisection lower bracket.+MIN_SIGMA = 1e-6+#: Below this vega, Newton's step is numerically meaningless and the solver+#: hands over to bisection (deep in- or out-of-the-money, or near expiry).+MIN_VEGA = 1e-10+#: Brenner-Subrahmanyam seed is only valid near the money; clamp it before use.+MAX_SEED_SIGMA = 5.0+MIN_SEED_SIGMA = 1e-3+#: One volatility point. A solved vol is only reported when moving sigma by this+#: much moves the price by more than the solve tolerance -- otherwise a whole+#: band of volatilities fits the quote equally well and the "solution" is+#: whichever endpoint the search wandered to.+SIGMA_RESOLUTION = 0.01++_CALL = "call"+_PUT = "put"+++def normalise_option_type(option_type: str) -> str:+ """Fold an option-type string to ``"call"`` or ``"put"``.++ Public because callers that *store* an option type must fold it with the+ same rule the pricing functions use. Anything that keeps the raw string and+ later compares it with ``== "call"`` will price a leg typed ``"Call"`` as a+ call here and settle it as a put there.++ Args:+ option_type: Caller-supplied option type, any case, may be padded.++ Returns:+ Either ``"call"`` or ``"put"``.++ Raises:+ ValueError: If the string is neither.+ """+ folded = str(option_type).strip().lower()+ if folded not in (_CALL, _PUT):+ raise ValueError(f"option_type must be 'call' or 'put', got {option_type!r}")+ return folded+++def _intrinsic(S: float, K: float, option_type: str) -> float:+ """Undiscounted exercise value of an option.++ Args:+ S: Underlying spot price.+ K: Strike price.+ option_type: Normalised ``"call"`` or ``"put"``.++ Returns:+ ``max(S - K, 0)`` for a call, ``max(K - S, 0)`` for a put. Always a+ float, even for integer inputs, so the public annotations hold.+ """+ return float(max(S - K, 0.0) if option_type == _CALL else max(K - S, 0.0))+++def _is_degenerate(S: float, K: float, T: float, sigma: float) -> bool:+ """Report whether the lognormal has collapsed to a point mass.++ Args:+ S: Underlying spot price.+ K: Strike price.+ T: Time to expiry in years.+ sigma: Annualised volatility.++ Returns:+ True when no diffusion remains, so closed-form d1/d2 are undefined.+ """+ return T <= 0 or sigma <= 0 or S <= 0 or K <= 0+++def _d1_d2(S: float, K: float, T: float, r: float, sigma: float,+ q: float) -> tuple[float, float]:+ """Compute the Black-Scholes d1 and d2 terms.++ Args:+ S: Underlying spot price.+ K: Strike price.+ T: Time to expiry in years.+ r: Risk-free rate, continuously compounded.+ sigma: Annualised volatility.+ q: Continuous dividend yield.++ Returns:+ The pair ``(d1, d2)``.+ """+ sqrt_T = np.sqrt(T)+ d1 = (np.log(S / K) + (r - q + sigma ** 2 / 2) * T) / (sigma * sqrt_T)+ return float(d1), float(d1 - sigma * sqrt_T)+++def bs_price(S: float, K: float, T: float, r: float, sigma: float,+ option_type: str = "call", q: float = 0.0) -> float:+ """Price a European option with the Black-Scholes-Merton formula.++ Args:+ S: Underlying spot price.+ K: Strike price.+ T: Time to expiry in years.+ r: Risk-free rate, continuously compounded and annualised.+ sigma: Annualised volatility.+ option_type: ``"call"`` or ``"put"``, case-insensitive.+ q: Continuous dividend yield, annualised. Defaults to 0.++ Returns:+ Theoretical option price. Degenerate inputs return intrinsic value.++ Raises:+ ValueError: If ``option_type`` is neither call nor put.++ Example:+ >>> round(bs_price(100, 100, 1.0, 0.05, 0.2, "call"), 2)+ 10.45+ """+ option_type = normalise_option_type(option_type)+ if _is_degenerate(S, K, T, sigma):+ return _intrinsic(S, K, option_type)++ d1, d2 = _d1_d2(S, K, T, r, sigma, q)+ spot_pv = S * np.exp(-q * T)+ strike_pv = K * np.exp(-r * T)++ if option_type == _CALL:+ return float(spot_pv * norm.cdf(d1) - strike_pv * norm.cdf(d2))+ return float(strike_pv * norm.cdf(-d2) - spot_pv * norm.cdf(-d1))+++def bs_greeks(S: float, K: float, T: float, r: float, sigma: float,+ option_type: str = "call", q: float = 0.0) -> Dict[str, float]:+ """Compute the five Black-Scholes-Merton Greeks.++ Args:+ S: Underlying spot price.+ K: Strike price.+ T: Time to expiry in years.+ r: Risk-free rate, continuously compounded and annualised.+ sigma: Annualised volatility.+ option_type: ``"call"`` or ``"put"``, case-insensitive.+ q: Continuous dividend yield, annualised. Defaults to 0.++ Returns:+ Dict with ``delta``, ``gamma``, ``theta``, ``vega`` and ``rho``.+ ``theta`` is per calendar day; ``vega`` and ``rho`` are per 1 percentage+ point. Degenerate inputs return the point-mass Greeks: delta is 1/0 for+ a call and 0/-1 for a put depending on moneyness, everything else zero.+ Exactly at the money the degenerate delta is the limiting value, 0.5 for+ a call and -0.5 for a put, which is the only pair that keeps put-call+ delta parity holding at the tie as it does everywhere else.++ Raises:+ ValueError: If ``option_type`` is neither call nor put.+ """+ option_type = normalise_option_type(option_type)+ if _is_degenerate(S, K, T, sigma):+ # An expiring in-the-money option still has unit exposure to spot, so+ # delta must not be reported as zero here. At S == K the one-sided+ # limits disagree (1 from above, 0 from below for a call), so take the+ # midpoint: any other choice breaks call_delta - put_delta == 1 at+ # precisely one point and silently corrupts a hedge ratio there.+ if S == K:+ delta = 0.5 if option_type == _CALL else -0.5+ elif option_type == _CALL:+ delta = 1.0 if S > K else 0.0+ else:+ delta = -1.0 if S < K else 0.0+ return {"delta": delta, "gamma": 0.0, "theta": 0.0, "vega": 0.0, "rho": 0.0}++ sqrt_T = float(np.sqrt(T))+ d1, d2 = _d1_d2(S, K, T, r, sigma, q)+ pdf_d1 = float(norm.pdf(d1))+ disc_q = float(np.exp(-q * T))+ disc_r = float(np.exp(-r * T))++ carry_theta = -(S * disc_q * pdf_d1 * sigma) / (2 * sqrt_T)+ if option_type == _CALL:+ delta = disc_q * float(norm.cdf(d1))+ theta = (carry_theta+ - r * K * disc_r * float(norm.cdf(d2))+ + q * S * disc_q * float(norm.cdf(d1)))+ rho = K * T * disc_r * float(norm.cdf(d2)) / 100.0+ else:+ delta = disc_q * (float(norm.cdf(d1)) - 1.0)+ theta = (carry_theta+ + r * K * disc_r * float(norm.cdf(-d2))+ - q * S * disc_q * float(norm.cdf(-d1)))+ rho = -K * T * disc_r * float(norm.cdf(-d2)) / 100.0++ return {+ "delta": float(delta),+ "gamma": float(disc_q * pdf_d1 / (S * sigma * sqrt_T)),+ "theta": float(theta / 365.0),+ "vega": float(S * disc_q * pdf_d1 * sqrt_T / 100.0),+ "rho": float(rho),+ }+++def _no_arbitrage_bounds(S: float, K: float, T: float, r: float,+ option_type: str, q: float) -> tuple[float, float]:+ """Return the price interval Black-Scholes can actually reach.++ As ``sigma`` goes to zero the price converges to the discounted forward+ intrinsic, and as ``sigma`` grows without bound a call converges to+ ``S*exp(-qT)`` and a put to ``K*exp(-rT)``. A quoted price outside that open+ interval has no implied volatility at all.++ Using the *undiscounted* intrinsic as the lower bound instead is wrong in+ both directions: with ``r > 0`` it lets through call prices no volatility can+ produce, and it rejects deep in-the-money European puts, which legitimately+ trade below ``K - S``.++ Args:+ S: Underlying spot price.+ K: Strike price.+ T: Time to expiry in years.+ r: Risk-free rate, continuously compounded.+ option_type: Normalised ``"call"`` or ``"put"``.+ q: Continuous dividend yield.++ Returns:+ The pair ``(lower, upper)``.+ """+ spot_pv = S * np.exp(-q * T)+ strike_pv = K * np.exp(-r * T)+ if option_type == _CALL:+ return max(spot_pv - strike_pv, 0.0), float(spot_pv)+ return max(strike_pv - spot_pv, 0.0), float(strike_pv)+++def implied_volatility(market_price: float, S: float, K: float, T: float,+ r: float, option_type: str = "call", q: float = 0.0,+ tol: float = 1e-6, max_iter: int = 200) -> float:+ """Invert Black-Scholes for volatility, Newton first then bisection.++ Seeds with the Brenner-Subrahmanyam at-the-money approximation+ ``sigma_0 = sqrt(2*pi/T) * price / S`` and iterates+ ``sigma -= (BS(sigma) - price) / vega``. Where vega collapses (deep in- or+ out-of-the-money, or close to expiry) Newton's step is meaningless, so the+ solver hands over to bracketed bisection on ``[MIN_SIGMA, MAX_SIGMA]``.++ Args:+ market_price: Observed option price, same units as ``S`` and ``K``.+ S: Underlying spot price.+ K: Strike price.+ T: Time to expiry in years; must be positive.+ r: Risk-free rate, continuously compounded and annualised.+ option_type: ``"call"`` or ``"put"``, case-insensitive.+ q: Continuous dividend yield, annualised. Defaults to 0.+ tol: Absolute price tolerance for convergence.+ max_iter: Maximum Newton iterations before falling back to bisection.++ Returns:+ Annualised implied volatility. ``nan`` if neither method converges+ inside ``[MIN_SIGMA, MAX_SIGMA]``, and also ``nan`` when the quote does+ not identify a volatility at all.++ The second case is the one worth understanding. Convergence is on+ *price*, so where the price is flat in ``sigma`` -- very deep in or out+ of the money, or right before expiry -- many volatilities satisfy+ ``tol`` and any of them would "converge". A 20-day call struck at half+ the spot prices identically to 16 decimal places for every ``sigma``+ from 0.05 to 0.60, so a solver that answers there is reporting the+ arbitrary endpoint of its own search, not a market volatility. This+ function refuses that: it checks vega at the candidate solution and+ returns ``nan`` when the price carries no volatility information. That+ is a property of the quote rather than a solver failure, and no+ price-tolerance method can do better -- but a confident wrong number is+ worse than an admitted absence.++ Raises:+ ValueError: If ``option_type`` is invalid, if ``T``, ``S`` or ``K`` is+ non-positive, or if ``market_price`` lies outside the no-arbitrage+ interval, which includes the intrinsic-value violation+ ``market_price < discounted intrinsic``.+ """+ option_type = normalise_option_type(option_type)+ if T <= 0:+ raise ValueError(f"T must be > 0 to imply a volatility, got {T}")+ if S <= 0 or K <= 0:+ raise ValueError(f"S and K must be > 0, got S={S}, K={K}")++ lower, upper = _no_arbitrage_bounds(S, K, T, r, option_type, q)+ if market_price < lower - tol:+ raise ValueError(+ f"market price {market_price} is below intrinsic value {lower}"+ )+ if market_price >= upper:+ raise ValueError(+ f"market price {market_price} is at or above the no-arbitrage "+ f"ceiling {upper}; no implied volatility exists"+ )++ def identified(candidate: float) -> float:+ """Return the candidate only if the quote actually pins it down.++ The test is whether one volatility point of movement shifts the price by+ more than the tolerance the solve was run to. If it does not, then a+ whole band of volatilities reprices within ``tol`` and whichever one the+ search happens to land on is an artefact of the search, not a reading of+ the market. Comparing vega against an absolute floor cannot express+ this, because the threshold has to scale with ``tol``.++ Args:+ candidate: A volatility that reprices to within ``tol``.++ Returns:+ ``candidate`` when the price responds to volatility there,+ otherwise ``nan``.+ """+ vega = bs_greeks(S, K, T, r, candidate, option_type, q)["vega"] * 100.0+ resolvable = abs(vega) * SIGMA_RESOLUTION >= tol+ return candidate if resolvable else float("nan")++ sigma = float(np.sqrt(2 * np.pi / T) * market_price / S)+ sigma = min(max(sigma, MIN_SEED_SIGMA), MAX_SEED_SIGMA)++ for _ in range(max_iter):+ diff = bs_price(S, K, T, r, sigma, option_type, q) - market_price+ if abs(diff) < tol:+ return identified(sigma)+ # bs_greeks reports vega per 1 percentage point; Newton needs per 1.0.+ vega = bs_greeks(S, K, T, r, sigma, option_type, q)["vega"] * 100.0+ if abs(vega) < MIN_VEGA:+ break+ sigma = min(max(sigma - diff / vega, MIN_SIGMA), MAX_SIGMA)++ try:+ return identified(float(brentq(+ lambda v: bs_price(S, K, T, r, v, option_type, q) - market_price,+ MIN_SIGMA, MAX_SIGMA, xtol=tol, maxiter=max_iter,+ )))+ except (ValueError, RuntimeError):+ # ValueError: the bracket does not straddle a root. RuntimeError: brentq+ # ran out of its own iterations. Both mean "no volatility found", and+ # the documented contract for that is nan, not an exception escaping+ # from a private implementation detail.+ return float("nan")diff --git a/agent/src/quantlib/risk.py b/agent/src/quantlib/risk.pynew file mode 100644index 000000000..92a391b00--- /dev/null+++ b/agent/src/quantlib/risk.py@@ -0,0 +1,511 @@+"""Risk measures: VaR/CVaR, drawdown, Monte Carlo simulation and EVT tail fitting.++SIGN CONVENTION -- read this before using anything here+------------------------------------------------------+**A loss is a positive number.** Every risk *magnitude* this module returns is+non-negative and grows as the risk gets worse:++* ``historical_var`` / ``parametric_var`` -- ``0.028`` means "a 2.8% loss".+* ``historical_cvar`` -- ``0.042`` means "a 4.2% average loss in the tail".+* ``max_drawdown_analysis()["max_drawdown"]`` -- ``0.325`` means "a 32.5%+ peak-to-trough decline". Note this is the opposite of the ``-0.325`` that a+ raw ``(equity / equity.cummax() - 1).min()`` produces; it is flipped here so+ that one rule covers the whole module.+* ``analyze_mc_results()["var"|"cvar"]`` -- same, positive losses.++Quantities that are *returns* rather than *losses* keep their natural sign and+are named ``*_return`` so the two can never be confused: ``mean_return``,+``worst_5pct_return`` and ``best_5pct_return`` are all signed returns, so a bad+outcome there is negative.++The invariant ``cvar >= var`` holds by construction for every pair of measures+computed from the same sample at the same confidence level. Note that this is+**not** ``cvar >= var >= 0``: the magnitudes are not clipped, so a sample whose+tail holds no actual loss reports a *negative* loss, i.e. a gain. Do not assert+non-negativity on a VaR; assert the ordering.++Quantile convention+-------------------+``historical_var`` uses a *non-interpolating lower order statistic*: with the+returns sorted ascending, it takes element ``ceil((1 - confidence) * n) - 1``+and negates it. No blending between neighbouring observations, so the result is+always an actually-observed return. ``historical_cvar`` averages every return at+or below that same order statistic (inclusive), which is the standard expected+shortfall and is what guarantees ``cvar >= var``.+"""++from __future__ import annotations++from collections.abc import Sequence++import math++import numpy as np+import pandas as pd+from scipy.stats import genpareto, norm++__all__ = [+ "historical_var",+ "parametric_var",+ "historical_cvar",+ "max_drawdown_analysis",+ "monte_carlo_gbm",+ "analyze_mc_results",+ "fit_gpd_tail",+]++TRADING_DAYS_PER_YEAR = 252+"""Day count used to annualise drift/volatility and to size a simulation step."""++GPD_SHAPE_SIGNIFICANCE_SIGMAS = 2.0+"""Standard errors a GPD shape must clear before ``fit_gpd_tail`` calls the tail+fat or bounded rather than exponential.++Measured over 200 refits per case: at 2.0 a truly exponential tail is labelled+``"exponential"`` 96.5% of the time, while ``xi = +0.40`` and ``xi = -0.35``+(n=3000) are still labelled correctly 100% of the time and ``xi = +0.10``+(n=2000) 98.5%. At 1.0 the exponential case drops to 70.5%, which is why the+band is not a single standard error.+"""+++def _clean_returns(returns: pd.Series | np.ndarray | Sequence[float]) -> np.ndarray:+ """Coerce a return series to a finite 1-D float array.++ Args:+ returns: Return observations as a pandas Series, numpy array or any+ sequence of floats. NaN and infinite values are dropped.++ Returns:+ A 1-D float64 array of the finite observations, in input order.++ Raises:+ ValueError: If the input is not 1-D or holds no finite observation.+ """+ values = np.asarray(returns, dtype=float)+ if values.ndim > 1:+ raise ValueError(f"returns must be 1-D, got shape {values.shape}")+ values = values.ravel()+ finite = values[np.isfinite(values)]+ if finite.size == 0:+ raise ValueError("returns contains no finite observation")+ return finite+++def _validate_confidence(confidence: float) -> None:+ """Check that a confidence level is a strict probability.++ Args:+ confidence: Confidence level, e.g. 0.95.++ Raises:+ ValueError: If ``confidence`` is not strictly between 0 and 1.+ """+ if not 0.0 < confidence < 1.0:+ raise ValueError(f"confidence must be in (0, 1), got {confidence}")+++def _validate_horizon(horizon: int) -> None:+ """Check that a holding period is a positive whole number of periods.++ Args:+ horizon: Holding period in periods (days for a daily return series).++ Raises:+ ValueError: If ``horizon`` is less than 1.+ """+ if horizon < 1:+ raise ValueError(f"horizon must be >= 1, got {horizon}")+++def _tail_index(n: int, confidence: float) -> int:+ """Position of the VaR order statistic in an ascending-sorted sample.++ Args:+ n: Number of observations, at least 1.+ confidence: Confidence level in (0, 1).++ Returns:+ The index ``ceil((1 - confidence) * n) - 1`` clamped into ``[0, n - 1]``.++ This is the textbook lower quantile. The floor form ``floor((1-c)*n)``+ agrees with it at every confidence level anyone uses -- 0.90, 0.95,+ 0.99 and friends are not exact binary fractions, so ``(1-c)*n`` is never+ exactly an integer and the two expressions coincide. They diverge only+ at levels like 0.5, 0.6 and 0.75, where the floor form picks the next+ observation up and understates the loss. Being right by construction+ rather than by floating-point accident costs nothing here.+ """+ return int(min(max(math.ceil((1.0 - confidence) * n) - 1, 0), n - 1))+++def historical_var(+ returns: pd.Series | np.ndarray | Sequence[float],+ confidence: float = 0.95,+ horizon: int = 1,+) -> float:+ """Value at Risk from the empirical distribution of past returns.++ Makes no distributional assumption: it simply reads the loss off the sorted+ sample at the ``1 - confidence`` order statistic (see the module docstring+ for the exact, non-interpolating convention).++ Args:+ returns: Periodic (usually daily) return series.+ confidence: Confidence level, commonly 0.95 or 0.99.+ horizon: Holding period in periods, scaled by the square-root-of-time+ rule. That rule assumes i.i.d. returns and understates risk when+ returns are autocorrelated.++ Returns:+ The VaR as a positive loss magnitude, e.g. 0.028 for a 2.8% loss. A+ sample with no losses in the tail yields a negative-signed "loss", i.e.+ a gain, which is reported as-is rather than clipped.++ Raises:+ ValueError: If ``returns`` has no finite observation, ``confidence`` is+ outside (0, 1), or ``horizon`` is below 1.+ """+ _validate_confidence(confidence)+ _validate_horizon(horizon)+ values = np.sort(_clean_returns(returns))+ quantile_return = values[_tail_index(values.size, confidence)]+ return float(-quantile_return * np.sqrt(horizon))+++def parametric_var(+ returns: pd.Series | np.ndarray | Sequence[float],+ confidence: float = 0.95,+ horizon: int = 1,+) -> float:+ """Value at Risk under a fitted normal distribution.++ Cheap and smooth, but it sees only a mean and a variance, so it misses fat+ tails. The direction of that error depends on the confidence level and is+ not uniform: a fat tail inflates the fitted sigma, which pushes the normal+ quantile *outward* at moderate confidence, where the empirical quantile is+ still in the well-behaved body. Measured over 300 t(4) samples of 750 daily+ returns, this function reads *above* ``historical_var`` in 100% of samples+ at 90% confidence and 92.7% at 95%, and only *below* it -- the classic+ understatement -- in 94.7% of samples at 99%. Compare the two at 99% or+ deeper if the point is to expose the tail.++ Args:+ returns: Periodic (usually daily) return series. The mean and the+ sample standard deviation (ddof=1) are estimated from it.+ confidence: Confidence level, commonly 0.95 or 0.99.+ horizon: Holding period in periods, scaled by square-root-of-time.++ Returns:+ The VaR as a positive loss magnitude: ``-(mu + z * sigma) * sqrt(horizon)``+ where ``z = norm.ppf(1 - confidence)``.++ Raises:+ ValueError: If ``returns`` holds fewer than two finite observations,+ ``confidence`` is outside (0, 1), or ``horizon`` is below 1.+ """+ _validate_confidence(confidence)+ _validate_horizon(horizon)+ values = _clean_returns(returns)+ if values.size < 2:+ raise ValueError("parametric_var needs at least 2 observations for a std estimate")+ mu = float(values.mean())+ sigma = float(values.std(ddof=1))+ z = float(norm.ppf(1.0 - confidence))+ return float(-(mu + z * sigma) * np.sqrt(horizon))+++def historical_cvar(+ returns: pd.Series | np.ndarray | Sequence[float],+ confidence: float = 0.95,+ horizon: int = 1,+) -> float:+ """Conditional VaR (expected shortfall) from the empirical distribution.++ The average loss *given* that the VaR threshold was breached. Unlike VaR it+ is subadditive, so it can be decomposed across a portfolio, which is why+ Basel III moved to it.++ Args:+ returns: Periodic (usually daily) return series.+ confidence: Confidence level, commonly 0.95 or 0.99.+ horizon: Holding period in periods, scaled by square-root-of-time.++ Returns:+ The CVaR as a positive loss magnitude. Always greater than or equal to+ ``historical_var`` on the same inputs, because it averages the VaR order+ statistic together with everything worse than it.++ Raises:+ ValueError: If ``returns`` has no finite observation, ``confidence`` is+ outside (0, 1), or ``horizon`` is below 1.+ """+ _validate_confidence(confidence)+ _validate_horizon(horizon)+ values = np.sort(_clean_returns(returns))+ tail = values[: _tail_index(values.size, confidence) + 1]+ return float(-tail.mean() * np.sqrt(horizon))+++def max_drawdown_analysis(equity: pd.Series | np.ndarray | Sequence[float]) -> dict:+ """Locate the worst peak-to-trough decline of an equity curve and its recovery.++ Args:+ equity: Net-value / equity series, strictly positive. A pandas Series+ keeps its index, so ``peak_date`` and friends come back as index+ labels; anything else is wrapped in a RangeIndex and the ``*_days``+ calendar fields are then None.++ Returns:+ dict with keys:+ max_drawdown (float): Worst decline as a **positive** fraction, so+ 0.25 means the curve fell 25% below its running peak. 0.0 when+ the curve never declines.+ peak_date: Index label of the running peak preceding the trough.+ trough_date: Index label of the deepest point.+ recovery_date: Index label of the first observation at or above the+ peak value, searched from the trough onward; None if the series+ ends still underwater.+ recovered (bool): Whether ``recovery_date`` was found.+ peak_to_trough_periods (int): Observations from peak to trough.+ trough_to_recovery_periods (int | None): Observations from trough to+ recovery, None if never recovered.+ underwater_days (int | None): Calendar days peak to trough; None+ unless the index is a DatetimeIndex.+ recovery_days (int | None): Calendar days trough to recovery; None+ unless the index is a DatetimeIndex and recovery happened.++ Raises:+ ValueError: If ``equity`` is not one-dimensional, has no finite+ observation, or any value is not strictly positive (a drawdown ratio+ is undefined at or below zero).+ """+ if not isinstance(equity, pd.Series):+ array = np.asarray(equity, dtype=float)+ if array.ndim > 1:+ # Flattening an (n, k) matrix concatenates unrelated curves into one+ # nonsense path and reports a drawdown for it. _clean_returns+ # already refuses this shape; refuse it here too.+ raise ValueError(f"equity must be 1-D, got shape {array.shape}")+ equity = pd.Series(array)+ series = equity+ series = series.astype(float)+ series = series[np.isfinite(series.to_numpy())]+ if series.empty:+ raise ValueError("equity contains no finite observation")+ values = series.to_numpy()+ if (values <= 0.0).any():+ raise ValueError("equity must be strictly positive to express drawdown as a fraction")++ running_peak = np.maximum.accumulate(values)+ drawdown = values / running_peak - 1.0 # <= 0 everywhere+ trough_pos = int(np.argmin(drawdown))+ peak_pos = int(np.argmax(values[: trough_pos + 1]))++ # A flat/rising curve has drawdown 0 at the trough, so the trough itself+ # already satisfies "back at the peak" and recovery is instantaneous.+ at_or_above_peak = np.flatnonzero(values[trough_pos:] >= values[peak_pos])+ recovery_pos = int(trough_pos + at_or_above_peak[0]) if at_or_above_peak.size else None++ index = series.index+ is_dated = isinstance(index, pd.DatetimeIndex)+ return {+ "max_drawdown": float(-drawdown[trough_pos]),+ "peak_date": index[peak_pos],+ "trough_date": index[trough_pos],+ "recovery_date": index[recovery_pos] if recovery_pos is not None else None,+ "recovered": recovery_pos is not None,+ "peak_to_trough_periods": trough_pos - peak_pos,+ "trough_to_recovery_periods": None if recovery_pos is None else recovery_pos - trough_pos,+ "underwater_days": int((index[trough_pos] - index[peak_pos]).days) if is_dated else None,+ "recovery_days": (+ int((index[recovery_pos] - index[trough_pos]).days)+ if is_dated and recovery_pos is not None+ else None+ ),+ }+++def monte_carlo_gbm(+ s0: float,+ mu: float,+ sigma: float,+ n_steps: int = TRADING_DAYS_PER_YEAR,+ n_paths: int = 10_000,+ *,+ seed: int | None = None,+ steps_per_year: int = TRADING_DAYS_PER_YEAR,+) -> np.ndarray:+ """Simulate price paths under geometric Brownian motion.++ Each step applies ``(mu - 0.5 * sigma**2) * dt + sigma * sqrt(dt) * Z`` in+ log space, so the terminal expectation is ``s0 * exp(mu * n_steps / steps_per_year)``.++ Args:+ s0: Initial price, strictly positive.+ mu: Annualised drift of the arithmetic return.+ sigma: Annualised volatility, non-negative. Zero gives a deterministic+ path, which is useful as a test fixture.+ n_steps: Number of simulated steps, at least 1.+ n_paths: Number of paths, at least 1. Use 10,000 or more before reading+ anything off the tail.+ seed: Seed for ``numpy.random.default_rng``. Keyword-only. Pass an int+ for a reproducible run; None draws fresh OS entropy and the result+ is then NOT reproducible.+ steps_per_year: Steps per year, i.e. ``dt = 1 / steps_per_year``.+ Defaults to the 252-day trading year.++ Returns:+ Price matrix of shape ``(n_paths, n_steps + 1)``. Column 0 is exactly+ ``s0`` on every path, so ``paths[:, -1] / paths[:, 0] - 1`` is the total+ return over the whole simulation.++ Raises:+ ValueError: If ``s0`` is not positive, ``sigma`` is negative, or any of+ ``n_steps`` / ``n_paths`` / ``steps_per_year`` is below 1.+ """+ if s0 <= 0.0:+ raise ValueError(f"s0 must be > 0, got {s0}")+ if sigma < 0.0:+ raise ValueError(f"sigma must be >= 0, got {sigma}")+ if n_steps < 1 or n_paths < 1:+ raise ValueError(f"n_steps and n_paths must be >= 1, got {n_steps} and {n_paths}")+ if steps_per_year < 1:+ raise ValueError(f"steps_per_year must be >= 1, got {steps_per_year}")++ dt = 1.0 / steps_per_year+ rng = np.random.default_rng(seed)+ shocks = rng.standard_normal((n_paths, n_steps))+ log_returns = (mu - 0.5 * sigma**2) * dt + sigma * np.sqrt(dt) * shocks+ paths = np.empty((n_paths, n_steps + 1), dtype=float)+ paths[:, 0] = s0+ paths[:, 1:] = s0 * np.exp(np.cumsum(log_returns, axis=1))+ return paths+++def analyze_mc_results(paths: np.ndarray, confidence: float = 0.95) -> dict:+ """Summarise the terminal distribution of a simulated price matrix.++ Args:+ paths: Price matrix of shape ``(n_paths, n_steps + 1)`` as returned by+ ``monte_carlo_gbm``; column 0 is the starting price.+ confidence: Confidence level for the VaR/CVaR of the terminal return.++ Returns:+ dict with keys:+ mean_return, median_return, std_return (float): Signed total+ returns over the simulation, so a bad outcome is negative.+ var, cvar (float): Positive loss magnitudes, computed with the same+ order-statistic convention as ``historical_var`` /+ ``historical_cvar``, so ``cvar >= var``.+ prob_loss (float): Fraction of paths ending below their start.+ worst_5pct_return, best_5pct_return (float): Signed 5th and 95th+ percentiles of the terminal return (linear interpolation).++ Raises:+ ValueError: If ``paths`` is not 2-D with at least two columns, holds a+ non-positive starting price, or ``confidence`` is outside (0, 1).+ """+ _validate_confidence(confidence)+ matrix = np.asarray(paths, dtype=float)+ if matrix.ndim != 2 or matrix.shape[1] < 2:+ raise ValueError(f"paths must be 2-D with >= 2 columns, got shape {matrix.shape}")+ start = matrix[:, 0]+ if (start <= 0.0).any():+ raise ValueError("paths column 0 (the starting price) must be strictly positive")++ returns = matrix[:, -1] / start - 1.0+ return {+ "mean_return": float(np.mean(returns)),+ "median_return": float(np.median(returns)),+ "std_return": float(np.std(returns, ddof=1)) if returns.size > 1 else 0.0,+ "var": historical_var(returns, confidence),+ "cvar": historical_cvar(returns, confidence),+ "prob_loss": float(np.mean(returns < 0.0)),+ "worst_5pct_return": float(np.percentile(returns, 5.0)),+ "best_5pct_return": float(np.percentile(returns, 95.0)),+ }+++def fit_gpd_tail(+ returns: pd.Series | np.ndarray | Sequence[float],+ threshold_pct: float = 5.0,+) -> dict:+ """Fit the loss tail with a generalised Pareto distribution (POT method).++ Extreme value theory says the exceedances over a high enough threshold+ converge to a GPD regardless of the parent distribution, which is what makes+ this usable where a normal fit is not. The location is pinned at zero+ because exceedances are non-negative by construction.++ ``tail_type`` is decided against ``shape_stderr``, not against exact zero. A+ maximum-likelihood shape is a float and is therefore never exactly ``0.0``,+ so a hard ``shape > 0`` test would label a genuinely exponential tail "fat"+ or "bounded" on the sign of estimation noise alone and would make the+ ``"exponential"`` label unreachable in practice.++ Args:+ returns: Periodic (usually daily) return series.+ threshold_pct: Percentile defining the left tail, e.g. 5.0 keeps the+ worst 5% of returns. Must be in (0, 100).++ Returns:+ dict with keys:+ threshold (float): The signed return at ``threshold_pct``; losses+ worse than this are the exceedances.+ n_exceedances (int): Number of observations in the tail.+ exceedance_rate (float): ``n_exceedances / n_observations``.+ shape_xi (float): GPD shape. ``> 0`` fat tail, ``== 0`` exponential+ tail, ``< 0`` bounded tail.+ shape_stderr (float): Asymptotic standard error of ``shape_xi``,+ ``|1 + xi| / sqrt(n_exceedances)``. Only valid for ``xi > -0.5``;+ below that the GPD likelihood is non-regular and the figure is+ indicative at best.+ scale_sigma (float): GPD scale, in units of loss magnitude.+ tail_type (str): ``"fat"`` when ``shape_xi`` clears+ ``GPD_SHAPE_SIGNIFICANCE_SIGMAS * shape_stderr``, ``"bounded"``+ when it clears it on the negative side, otherwise+ ``"exponential"`` -- i.e. a shape indistinguishable from zero at+ this sample size is reported as exponential rather than being+ rounded into one of the two extremes.++ Raises:+ ValueError: If ``threshold_pct`` is outside (0, 100), ``returns`` has no+ finite observation, or the threshold leaves fewer than 2 exceedances+ to fit.+ """+ if not 0.0 < threshold_pct < 100.0:+ raise ValueError(f"threshold_pct must be in (0, 100), got {threshold_pct}")+ values = _clean_returns(returns)+ threshold = float(np.percentile(values, threshold_pct))+ # Exceedances are loss magnitudes, hence non-negative: a positive number is+ # "how far below the threshold this return fell".+ exceedances = threshold - values[values < threshold]+ if exceedances.size < 2:+ raise ValueError(+ f"need at least 2 exceedances to fit a GPD, got {exceedances.size} "+ f"at threshold_pct={threshold_pct}"+ )++ shape, _loc, scale = genpareto.fit(exceedances, floc=0.0)+ # Asymptotic MLE standard error of the GPD shape. Empirically checked+ # against the spread of 12 refits per shape at n=2000: predicted+ # 0.0291/0.0246/0.0224/0.0179 vs observed 0.0313/0.0244/0.0212/0.0162 for+ # true xi of +0.30/+0.10/0.00/-0.20.+ shape_stderr = float(abs(1.0 + shape) / np.sqrt(exceedances.size))+ band = GPD_SHAPE_SIGNIFICANCE_SIGMAS * shape_stderr+ if shape > band:+ tail_type = "fat"+ elif shape < -band:+ tail_type = "bounded"+ else:+ tail_type = "exponential"+ return {+ "threshold": threshold,+ "n_exceedances": int(exceedances.size),+ "exceedance_rate": float(exceedances.size / values.size),+ "shape_xi": float(shape),+ "shape_stderr": shape_stderr,+ "scale_sigma": float(scale),+ "tail_type": tail_type,+ }diff --git a/agent/src/quantlib/timeseries.py b/agent/src/quantlib/timeseries.pynew file mode 100644index 000000000..441a2901a--- /dev/null+++ b/agent/src/quantlib/timeseries.py@@ -0,0 +1,649 @@+"""Time-series and statistical tests for quantitative research.++Promoted verbatim-in-behaviour from the ``quant-statistics`` skill, where these+eleven routines existed only as markdown the LLM retyped on every run. One+implementation, pinned by tests, is now importable::++ from src.quantlib.timeseries import adf_test, cointegration_test++Optional dependencies+---------------------+Neither ``statsmodels`` nor ``arch`` is declared by ``vibe-trading-ai`` (checked+in ``pyproject.toml`` and ``agent/requirements.txt``; only ``numpy``, ``pandas``+and ``scipy`` are). They are therefore imported lazily *inside* each function+that needs them, so importing this module never fails and a user who only wants+the bootstrap helpers never pays for a compiler-heavy install. A function whose+backend is absent raises :class:`ImportError` naming the package and the exact+install command -- it never silently degrades to a wrong number.++ * ``statsmodels`` -- everything except :func:`bootstrap_statistic` and+ :func:`bootstrap_sharpe`, which are pure numpy.+ * ``arch`` -- :func:`fit_garch` only.++Related, deliberately not merged+--------------------------------+``backtest.validation.bootstrap_sharpe_ci`` also bootstraps a Sharpe ratio, but+it consumes an *equity curve* (it calls ``pct_change`` itself) and returns+backtest-report keys (``observed_sharpe``/``prob_positive``). :func:`bootstrap_sharpe`+here consumes a *return series* and returns the generic bootstrap envelope. They+are different call contracts; neither wraps the other.+"""++from __future__ import annotations++import contextlib+import importlib+import io+from typing import Any, Callable++import numpy as np+import pandas as pd++__all__ = [+ "adf_test",+ "cointegration_test",+ "find_hedge_ratio",+ "compute_half_life",+ "granger_test",+ "fit_garch",+ "heteroscedasticity_test",+ "autocorrelation_test",+ "vif_test",+ "bootstrap_statistic",+ "bootstrap_sharpe",+]++# Durbin-Watson conventional reading points. A DW of 2 means no first-order+# autocorrelation; these are the textbook bands either side of it.+_DW_POSITIVE_BELOW = 1.5+_DW_NEGATIVE_ABOVE = 2.5++#: Both packages ship in the one ``stats`` extra, so the hint is the same for+#: either miss: installing the extra resolves both at their pinned floors.+_INSTALL_HINT = 'pip install "vibe-trading-ai[stats]"'+++def _require(module_path: str, package: str, feature: str) -> Any:+ """Import an optional backend module or raise an actionable ImportError.++ Args:+ module_path: Dotted module to import, e.g. ``"statsmodels.tsa.stattools"``.+ package: Distribution name the user must install, e.g. ``"statsmodels"``.+ feature: Human-readable name of the calling feature, used in the message.++ Returns:+ The imported module object.++ Raises:+ ImportError: If the module is unavailable. The message names the missing+ package and the ``stats`` extra that provides it.+ """+ try:+ return importlib.import_module(module_path)+ except ImportError as exc: # pragma: no cover - exercised via monkeypatch+ raise ImportError(+ f"{feature} requires the optional '{package}' package, which is "+ f"not part of the base install. "+ f"Install it with: {_INSTALL_HINT}"+ ) from exc+++def _ols_params(endog: Any, exog_with_const: Any) -> np.ndarray:+ """Fit an OLS model and return its coefficients as a positional array.++ ``statsmodels`` returns ``params`` as a pandas Series when handed pandas+ input, where ``params[1]`` is a *label* lookup and misbehaves. Converting to+ an ndarray makes ``[0] = intercept, [1] = slope`` unambiguous.++ Args:+ endog: Dependent variable.+ exog_with_const: Design matrix that already includes a constant column.++ Returns:+ Coefficients as a 1-D numpy array, intercept first.+ """+ sm = _require("statsmodels.api", "statsmodels", "OLS regression")+ fitted = sm.OLS(np.asarray(endog, dtype=float), np.asarray(exog_with_const, dtype=float)).fit()+ return np.asarray(fitted.params, dtype=float)+++def adf_test(series: pd.Series, significance: float = 0.05) -> dict:+ """Augmented Dickey-Fuller unit-root (stationarity) test.++ H0 = a unit root exists (non-stationary); H1 = stationary. Regressing+ non-stationary series on each other produces spurious regression, so this is+ the gate before any level-on-level model.++ Args:+ series: Time series to test. NaNs are dropped.+ significance: Significance level for the ``is_stationary`` verdict.++ Returns:+ Dict with keys ``adf_statistic`` (float), ``p_value`` (float),+ ``lags_used`` (int), ``is_stationary`` (bool) and ``critical_values``+ (dict mapping ``'1%'``/``'5%'``/``'10%'`` to floats).++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ ValueError: If fewer than 2 non-NaN observations remain.+ """+ stattools = _require("statsmodels.tsa.stattools", "statsmodels", "adf_test")+ clean = pd.Series(series).dropna()+ if len(clean) < 2:+ raise ValueError(f"adf_test needs at least 2 non-NaN observations, got {len(clean)}")++ result = stattools.adfuller(clean, autolag="AIC")+ return {+ "adf_statistic": float(result[0]),+ "p_value": float(result[1]),+ "lags_used": int(result[2]),+ "is_stationary": bool(result[1] < significance),+ "critical_values": {k: float(v) for k, v in result[4].items()},+ }+++def cointegration_test(y: pd.Series, x: pd.Series, significance: float = 0.05) -> dict:+ """Engle-Granger two-step cointegration test.++ H0 = no cointegrating relationship. Two individually non-stationary series+ are cointegrated when some linear combination of them is stationary, which+ is the statistical premise of pair trading.++ Args:+ y: First price series.+ x: Second price series, same length as ``y``.+ significance: Significance level for the ``is_cointegrated`` verdict.++ Returns:+ Dict with keys ``test_statistic`` (float), ``p_value`` (float),+ ``is_cointegrated`` (bool) and ``critical_values`` (dict mapping+ ``'1%'``/``'5%'``/``'10%'`` to floats).++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ ValueError: If the two series differ in length, or carry different+ indices. Two same-length series with different indices would+ otherwise be joined *positionally* and could report a spurious+ cointegration, so the mismatch is refused rather than guessed --+ the same contract :func:`find_hedge_ratio` enforces, since the pair+ workflow runs both on the same two legs.+ """+ stattools = _require("statsmodels.tsa.stattools", "statsmodels", "cointegration_test")+ y_ser = pd.Series(y, dtype=float)+ x_ser = pd.Series(x, dtype=float)+ if len(y_ser) != len(x_ser):+ raise ValueError(f"cointegration_test needs equal-length series, got {len(y_ser)} and {len(x_ser)}")+ if not y_ser.index.equals(x_ser.index):+ raise ValueError("cointegration_test needs y and x sharing one index")++ score, p_value, critical = stattools.coint(y_ser.to_numpy(), x_ser.to_numpy())+ return {+ "test_statistic": float(score),+ "p_value": float(p_value),+ "is_cointegrated": bool(p_value < significance),+ "critical_values": {+ "1%": float(critical[0]),+ "5%": float(critical[1]),+ "10%": float(critical[2]),+ },+ }+++def compute_half_life(spread: pd.Series) -> float:+ """Estimate mean-reversion half-life of a spread by delta regression.++ Regresses ``ΔS_t`` on ``S_{t-1}`` (Ornstein-Uhlenbeck discretisation) and+ reports ``-ln(2) / b``, the time for a deviation to decay by half.++ Args:+ spread: Spread series, in observation order.++ Returns:+ Half-life in observation periods. Returns ``inf`` when the estimated+ reversion coefficient is non-negative, i.e. the series does not revert.++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ ValueError: If fewer than 3 usable lag/delta pairs remain, or the spread+ never moves. A flat regressor is refused rather than fitted:+ ``sm.add_constant`` leaves an already-constant column alone, so the+ design would silently collapse to one column and the slope lookup+ would be a bare ``IndexError``.+ """+ sm = _require("statsmodels.api", "statsmodels", "compute_half_life")+ series = pd.Series(spread, dtype=float)+ lagged = series.shift(1)+ delta = series - lagged+ # Align on the index where BOTH the level and its delta exist; dropping each+ # side independently would silently mis-pair rows around interior NaNs.+ frame = pd.concat({"delta": delta, "lag": lagged}, axis=1).dropna()+ if len(frame) < 3:+ raise ValueError(f"compute_half_life needs at least 3 lag/delta pairs, got {len(frame)}")+ if frame["lag"].std(ddof=0) == 0:+ raise ValueError("compute_half_life needs a spread that varies; this one is constant")++ params = _ols_params(frame["delta"], sm.add_constant(frame[["lag"]]))+ reversion = params[1]+ if reversion >= 0:+ return float("inf")+ return float(-np.log(2) / reversion)+++def find_hedge_ratio(y: pd.Series, x: pd.Series) -> dict:+ """Fit the pair-trading hedge ratio ``y = α + β·x + ε``.++ The tradeable spread is ``y - β·x``; its mean and standard deviation define+ the z-score used to enter and exit, and its half-life says how long a round+ trip should take.++ Args:+ y: Dependent price series.+ x: Independent (hedging) price series, same length as ``y``.++ Returns:+ Dict with keys ``hedge_ratio`` (β, float), ``intercept`` (α, float),+ ``spread_mean`` (float), ``spread_std`` (float, sample ddof=1) and+ ``half_life`` (float, in observation periods).++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ ValueError: If the series differ in length, carry different indices,+ fewer than 3 aligned non-NaN observations remain, or ``x`` is+ constant. A flat hedging leg is refused rather than fitted:+ ``sm.add_constant`` leaves an already-constant column alone, so the+ design would silently collapse to one column and the β lookup would+ be a bare ``IndexError``.+ """+ sm = _require("statsmodels.api", "statsmodels", "find_hedge_ratio")+ frame = pd.concat({"y": pd.Series(y, dtype=float), "x": pd.Series(x, dtype=float)}, axis=1)+ if len(frame) != len(pd.Series(y)) or len(frame) != len(pd.Series(x)):+ raise ValueError("find_hedge_ratio needs y and x sharing one index")+ frame = frame.dropna()+ if len(frame) < 3:+ raise ValueError(f"find_hedge_ratio needs at least 3 aligned observations, got {len(frame)}")+ if frame["x"].std(ddof=0) == 0:+ raise ValueError("find_hedge_ratio needs an x that varies; this one is constant")++ params = _ols_params(frame["y"], sm.add_constant(frame[["x"]]))+ intercept, beta = float(params[0]), float(params[1])+ spread = frame["y"] - beta * frame["x"]++ return {+ "hedge_ratio": beta,+ "intercept": intercept,+ "spread_mean": float(spread.mean()),+ "spread_std": float(spread.std()),+ "half_life": compute_half_life(spread),+ }+++def granger_test(data: pd.DataFrame, x_col: str, y_col: str, max_lag: int = 5) -> dict:+ """Test whether ``x`` Granger-causes ``y``.++ Granger causality is predictive, not structural: it asks only whether past+ ``x`` improves the forecast of ``y`` beyond ``y``'s own past. It is not+ evidence of a causal mechanism.++ Args:+ data: Frame containing both columns.+ x_col: Name of the candidate predictor column.+ y_col: Name of the predicted column.+ max_lag: Maximum lag order to test; every lag from 1 to this is reported.++ Returns:+ Dict mapping lag (int, 1..``max_lag``) to the SSR F-test p-value (float).+ A small p-value rejects "x does not Granger-cause y".++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ KeyError: If either column is missing from ``data``.+ ValueError: If ``max_lag`` is below 1, or if ``x_col`` and ``y_col`` are+ the same column. Testing a series against itself hands statsmodels a+ duplicated column, where the F-test trivially fails to reject and+ every p-value comes back 1.0 -- an answer that looks like a finding.+ """+ if x_col == y_col:+ raise ValueError(+ f"x_col and y_col must differ; both are {x_col!r}. A series cannot "+ "Granger-cause itself and the test returns p=1.0 regardless."+ )+ stattools = _require("statsmodels.tsa.stattools", "statsmodels", "granger_test")+ if max_lag < 1:+ raise ValueError(f"granger_test needs max_lag >= 1, got {max_lag}")+ missing = [c for c in (y_col, x_col) if c not in data.columns]+ if missing:+ raise KeyError(f"granger_test: column(s) not in data: {missing}")++ # statsmodels >= 0.14 dropped the `verbose` kwarg and prints the full test+ # table to stdout unconditionally; swallow it so a library call stays quiet.+ with contextlib.redirect_stdout(io.StringIO()):+ results = stattools.grangercausalitytests(data[[y_col, x_col]].dropna(), maxlag=max_lag)+ return {lag: float(results[lag][0]["ssr_ftest"][1]) for lag in range(1, max_lag + 1)}+++def fit_garch(returns: pd.Series, horizon: int = 5) -> dict:+ """Fit a GARCH(1,1) model and forecast forward volatility.++ Model: ``r_t = μ + ε_t`` with ``σ²_t = ω + α·ε²_{t-1} + β·σ²_{t-1}``.+ ``α + β`` is volatility persistence (typically 0.95-0.99 in equities).++ Args:+ returns: Daily return series as *fractions* (0.01 = 1%). Scaled to+ percent internally, which is what ``arch`` optimises well on.+ horizon: Number of days ahead to forecast.++ Returns:+ Dict with keys ``omega``, ``alpha``, ``beta``, ``persistence``,+ ``long_run_vol``, ``current_vol`` (all float, volatilities as daily+ fractions), ``forecast_vol`` (numpy array of length ``horizon``, daily+ fractions), ``horizon`` (int), ``aic`` and ``bic`` (float).+ ``long_run_vol`` is ``nan`` when persistence >= 1 (no finite+ unconditional variance).++ Raises:+ ImportError: If ``arch`` is not installed.+ ValueError: If ``horizon`` is below 1.+ """+ arch_mod = _require("arch", "arch", "fit_garch")+ if horizon < 1:+ raise ValueError(f"fit_garch needs horizon >= 1, got {horizon}")++ model = arch_mod.arch_model(+ pd.Series(returns, dtype=float).dropna() * 100,+ vol="Garch",+ p=1,+ q=1,+ mean="Constant",+ dist="normal",+ )+ result = model.fit(disp="off")++ omega = float(result.params["omega"])+ alpha = float(result.params["alpha[1]"])+ beta = float(result.params["beta[1]"])+ persistence = alpha + beta++ # `conditional_volatility` is already a standard deviation (in percent);+ # the skill's markdown took sqrt of it again, which is dimensionally wrong.+ current_vol = float(np.asarray(result.conditional_volatility, dtype=float)[-1]) / 100+ forecast = result.forecast(horizon=horizon, reindex=False)+ forecast_vol = np.sqrt(np.asarray(forecast.variance.values, dtype=float)[-1, :]) / 100++ return {+ "omega": omega,+ "alpha": alpha,+ "beta": beta,+ "persistence": persistence,+ "long_run_vol": float(np.sqrt(omega / (1 - persistence)) / 100) if persistence < 1 else float("nan"),+ "current_vol": current_vol,+ "forecast_vol": forecast_vol,+ "horizon": horizon,+ "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).++ H0 = homoskedasticity. Financial residuals are almost always+ heteroskedastic, so the practical answer is usually HAC standard errors+ rather than dropping the model.++ Both p-values are Lagrange-multiplier p-values: ``white_p`` is+ ``het_white``'s and ``bp_p`` is ``het_breuschpagan``'s studentised+ (Koenker) ``n·R²`` variant, which is what statsmodels returns by default.++ Args:+ model_result: A fitted ``statsmodels`` regression result, i.e. the object+ returned by ``sm.OLS(...).fit()``. Its ``.resid`` and+ ``.model.exog`` are read.+ significance: Significance level for the verdict and the advice string.++ Returns:+ Dict with keys ``white_p`` (float), ``bp_p`` (float),+ ``has_heteroscedasticity`` (bool) and ``fix`` (str advice). ``fix``+ tracks ``has_heteroscedasticity``, so the verdict and the advice can+ never contradict each other.++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ """+ diagnostic = _require("statsmodels.stats.diagnostic", "statsmodels", "heteroscedasticity_test")+ white_p = float(diagnostic.het_white(model_result.resid, model_result.model.exog)[1])+ bp_p = float(diagnostic.het_breuschpagan(model_result.resid, model_result.model.exog)[1])++ # Either test rejecting is enough to act on. Keying the advice off `white_p`+ # alone -- as the skill's markdown did -- returns "No adjustment needed"+ # alongside `has_heteroscedasticity: True` whenever only BP rejects.+ has_het = bool(white_p < significance or bp_p < significance)+ return {+ "white_p": white_p,+ "bp_p": bp_p,+ "has_heteroscedasticity": has_het,+ "fix": (+ "Use HAC standard errors (Newey-West) or WLS"+ if has_het+ else "No adjustment needed"+ ),+ }+++def autocorrelation_test(residuals: pd.Series, lags: int = 10, significance: float = 0.05) -> dict:+ """Test residuals for serial correlation (Durbin-Watson and Ljung-Box).++ H0 = no autocorrelation. Durbin-Watson sees only lag 1; Ljung-Box tests the+ joint hypothesis across all lags up to ``lags``.++ Caveat, measured not assumed: ``has_autocorrelation`` is ``any(p < significance)``+ over ``lags`` p-values, so it is a family of tests, not one. On pure white+ noise it fires about 13% of the time at ``lags=10`` versus about 2% at+ ``lags=1`` (120 seeds, n=1500 -- see ``test_ljung_box_any_lag_rule_inflates_+ the_false_positive_rate``). Read a lone flag at high ``lags`` as a prompt to+ look at ``ljung_box_p`` per lag, not as a 5%-level rejection.++ Args:+ residuals: Residual series to test.+ lags: Highest lag included in the Ljung-Box test.+ significance: Significance level for the ``has_autocorrelation`` verdict.++ Returns:+ Dict with keys ``durbin_watson`` (float), ``dw_interpretation`` (str,+ one of ``'positive autocorrelation'`` / ``'no autocorrelation'`` /+ ``'negative autocorrelation'``), ``ljung_box_p`` (numpy array of+ p-values, one per lag), ``has_autocorrelation`` (bool) and ``fix`` (str).++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ ValueError: If ``lags`` is below 1.+ """+ diagnostic = _require("statsmodels.stats.diagnostic", "statsmodels", "autocorrelation_test")+ stattools = _require("statsmodels.stats.stattools", "statsmodels", "autocorrelation_test")+ if lags < 1:+ raise ValueError(f"autocorrelation_test needs lags >= 1, got {lags}")++ clean = pd.Series(residuals, dtype=float).dropna()+ if lags >= clean.size:+ # acorr_ljungbox silently caps lags and then dies on a shape mismatch+ # with a numpy message that names neither argument.+ raise ValueError(+ f"lags must be < the number of observations; got lags={lags} "+ f"for {clean.size} observations"+ )+ dw = float(stattools.durbin_watson(clean))+ lb_p = np.asarray(diagnostic.acorr_ljungbox(clean, lags=lags)["lb_pvalue"].values, dtype=float)++ if dw < _DW_POSITIVE_BELOW:+ interpretation = "positive autocorrelation"+ elif dw < _DW_NEGATIVE_ABOVE:+ interpretation = "no autocorrelation"+ else:+ interpretation = "negative autocorrelation"++ return {+ "durbin_watson": dw,+ "dw_interpretation": interpretation,+ "ljung_box_p": lb_p,+ "has_autocorrelation": bool(np.any(lb_p < significance)),+ "fix": "Use Newey-West standard errors or include lag terms",+ }+++def vif_test(+ X: pd.DataFrame,+ severe_threshold: float = 10.0,+ watch_threshold: float = 5.0,+) -> pd.DataFrame:+ """Score each regressor's variance inflation factor for multicollinearity.++ VIF measures how much a coefficient's variance is inflated by correlation+ with the other regressors. Include a constant column if the model has one --+ VIF is otherwise distorted by the un-centred means.++ Args:+ X: Design matrix, one column per feature. Must contain no NaN or inf --+ ``statsmodels`` raises ``MissingDataError`` on either.+ severe_threshold: VIF strictly above which collinearity is flagged+ severe. A VIF exactly on the threshold is not flagged.+ watch_threshold: VIF strictly above which collinearity is flagged as+ worth watching. A VIF exactly on the threshold is not flagged.++ Returns:+ DataFrame with one row per column of ``X`` and columns ``feature``+ (str), ``VIF`` (float) and ``concern`` (str, one of ``'severe'`` /+ ``'watch'`` / ``'normal'``).++ Raises:+ ImportError: If ``statsmodels`` is not installed.+ ValueError: If ``X`` has no columns.+ """+ influence = _require(+ "statsmodels.stats.outliers_influence", "statsmodels", "vif_test"+ )+ if X.shape[1] == 0:+ raise ValueError("vif_test needs at least one column")++ values = np.asarray(X, dtype=float)+ vifs = [float(influence.variance_inflation_factor(values, i)) for i in range(X.shape[1])]++ return pd.DataFrame(+ {+ "feature": list(X.columns),+ "VIF": vifs,+ "concern": [+ "severe" if v > severe_threshold else "watch" if v > watch_threshold else "normal"+ for v in vifs+ ],+ }+ )+++def bootstrap_statistic(+ data: np.ndarray,+ statistic_func: Callable[[np.ndarray], float],+ n_bootstrap: int = 10000,+ confidence: float = 0.95,+ seed: int | None = None,+) -> dict:+ """Percentile-bootstrap confidence interval for an arbitrary statistic.++ Resamples ``data`` with replacement ``n_bootstrap`` times, recomputes the+ statistic on each resample, and reads the confidence interval off the+ resulting distribution. Makes no distributional assumption, which matters+ because financial returns are fat-tailed.++ Args:+ data: One-dimensional sample of observations.+ statistic_func: Callable mapping a resample to a scalar, e.g. ``np.mean``.+ n_bootstrap: Number of bootstrap resamples.+ confidence: Confidence level in (0, 1), e.g. 0.95 for a 95% interval.+ seed: Seed for the random generator; pass an int for reproducible output.++ Returns:+ Dict with keys ``point_estimate``, ``bootstrap_mean``, ``bootstrap_std``,+ ``ci_lower``, ``ci_upper`` (all float) and ``confidence`` (float, echoed).++ Raises:+ ValueError: If ``data`` is empty, ``n_bootstrap`` is below 1, or+ ``confidence`` is not strictly inside (0, 1).+ """+ sample = np.asarray(data, dtype=float).ravel()+ if sample.size == 0:+ raise ValueError("bootstrap_statistic needs a non-empty sample")+ if n_bootstrap < 1:+ raise ValueError(f"bootstrap_statistic needs n_bootstrap >= 1, got {n_bootstrap}")+ if not 0.0 < confidence < 1.0:+ raise ValueError(f"bootstrap_statistic needs confidence in (0, 1), got {confidence}")++ rng = np.random.default_rng(seed)+ n = sample.size+ # Resample one draw at a time. Materialising the whole (n_bootstrap, n)+ # index matrix would be ~160MB at the default 10000 draws over 2000 bars.+ bootstrap_stats = np.empty(n_bootstrap, dtype=float)+ for i in range(n_bootstrap):+ bootstrap_stats[i] = float(statistic_func(sample[rng.integers(0, n, size=n)]))++ alpha = 1 - confidence+ return {+ "point_estimate": float(statistic_func(sample)),+ "bootstrap_mean": float(np.mean(bootstrap_stats)),+ "bootstrap_std": float(np.std(bootstrap_stats)),+ "ci_lower": float(np.percentile(bootstrap_stats, alpha / 2 * 100)),+ "ci_upper": float(np.percentile(bootstrap_stats, (1 - alpha / 2) * 100)),+ "confidence": confidence,+ }+++def bootstrap_sharpe(+ returns: pd.Series,+ n_bootstrap: int = 10000,+ confidence: float = 0.95,+ periods_per_year: int = 252,+ seed: int | None = None,+ ddof: int = 1,+) -> dict:+ """Bootstrap a confidence interval for an annualised Sharpe ratio.++ A point Sharpe with no interval is not evidence: an interval that straddles+ zero means the strategy is statistically indistinguishable from noise.++ Convention, stated because it differs from this repo's other Sharpe: the+ denominator defaults to the *sample* standard deviation (``ddof=1``).+ ``backtest.validation._sharpe`` uses the population one (``ddof=0``), so the+ two report Sharpes a factor ``sqrt(n / (n - 1))`` apart on identical data --+ about 0.2% over one year of daily bars. Neither is wrong, but comparing+ their numbers digit for digit is. Pass ``ddof=0`` to reconcile with the+ backtest engine's figure rather than eyeballing the gap.++ Args:+ returns: Periodic return series as fractions (not an equity curve).+ n_bootstrap: Number of bootstrap resamples.+ confidence: Confidence level in (0, 1).+ periods_per_year: Annualisation factor, e.g. 252 for daily bars.+ seed: Seed for the random generator; pass an int for reproducible output.+ ddof: Delta degrees of freedom for the standard deviation. 1 (default)+ is the sample estimator; 0 matches ``backtest.validation._sharpe``.++ Returns:+ The :func:`bootstrap_statistic` dict, plus ``is_significant`` (bool) --+ ``True`` when the whole interval sits above zero.++ Raises:+ ValueError: If the return series is empty or the bootstrap arguments are+ out of range (propagated from :func:`bootstrap_statistic`).+ """+ def sharpe(sample: np.ndarray) -> float:+ std = float(np.std(sample, ddof=ddof)) if sample.size > ddof else 0.0+ if std == 0.0:+ return 0.0+ return float(np.mean(sample) / std * np.sqrt(periods_per_year))++ result = bootstrap_statistic(+ np.asarray(pd.Series(returns, dtype=float).dropna(), dtype=float),+ sharpe,+ n_bootstrap=n_bootstrap,+ confidence=confidence,+ seed=seed,+ )+ result["is_significant"] = bool(result["ci_lower"] > 0)+ return resultdiff --git a/agent/src/skills/credit-analysis/SKILL.md b/agent/src/skills/credit-analysis/SKILL.mdindex b2e576130..73341b3c7 100644--- a/agent/src/skills/credit-analysis/SKILL.md+++ b/agent/src/skills/credit-analysis/SKILL.md@@ -225,26 +225,35 @@ CX = [Σ t(t+1)·CF_t/(1+y)^(t+2)] / P价格变化修正:ΔP/P ≈ -MD·Δy + 0.5·CX·(Δy)²```-#### 债券价格公式(完整)+#### 债券价格公式(实现)++定价函数是仓库里的实测代码,直接 import,**不要在会话里重新手写**:+```python-def bond_price(face, coupon_rate, ytm, n_periods, freq=1):- """附息债券定价(贴现现金流法)。-- Args:- face: 面值- coupon_rate: 票面利率(年化)- ytm: 到期收益率(年化)- n_periods: 剩余付息期数- freq: 每年付息次数(1=年付,2=半年付)-- Returns:- 债券现值(脏价)- """- c = face * coupon_rate / freq- y = ytm / freq- pv_coupons = c * (1 - (1+y)**(-n_periods)) / y- pv_face = face / (1+y)**n_periods- return pv_coupons + pv_face+from src.quantlib.fixedincome import bond_price++bond_price(face=100, coupon_rate=0.05, ytm=0.04, n_periods=5, freq=1)+# -> 104.4518... 5年期、票息5%、YTM=4%、年付+```++两个约定在这里是**显式参数**,不是隐含假设:++- `compounding`:`"discrete"`(默认,每年 `freq` 次离散复利,即上面 `P = Σ C/(1+y/m)^t` 的形式)或 `"continuous"`。+- 日算基准:`bond_price` 按整数付息期贴现,因此返回的是**付息日**的价格(净价,应计为 0)。+ 非付息日结算要另加应计利息才是全价(脏价):++```python+import datetime as dt+from src.quantlib.fixedincome import accrued_interest++accrued = accrued_interest(+ face=100, coupon_rate=0.05, freq=2,+ last_coupon=dt.date(2024, 1, 15),+ settlement=dt.date(2024, 4, 15),+ next_coupon=dt.date(2024, 7, 15),+ day_count="30/360", # ACT/365F(默认) | ACT/360 | ACT/ACT | 30/360 | 30E/360+) # -> 1.25+dirty_price = bond_price(100, 0.05, 0.04, 10, 2) + accrued```---@@ -513,450 +522,219 @@ P = Σ CF_t / (1 + r_t + OAS)^t----## 五、Python 代码模板+## 五、Python 实现(quantlib)++本章的模型**已经是仓库里的实测代码**,位于 `src/quantlib/fixedincome.py`(债券数学 + 曲线拟合)+与 `src/quantlib/credit.py`(Altman Z / Merton-KMV / 利差)。两个模块都有对应的+`tests/quantlib/test_fixedincome.py`、`tests/quantlib/test_credit.py`,久期与 DV01 是对+"重新定价 ±1bp" 逐点核过的。++**直接 import 调用,不要在会话里重写这些公式。** 手写一遍既拿不到测试保障,也不可复现。++一律的单位约定:利率与比率是小数(`0.05` 表示 5%),期限与时间跨度是**年**,+久期/凸性的返回值是**年 / 年²**(不是付息期数),带 `_bp` 后缀的才是基点。-### 5.1 债券定价与久期计算+### 5.1 债券定价、久期与 DV01```python-import numpy as np-from scipy.optimize import brentq---def bond_price(face: float, coupon_rate: float, ytm: float,- n_periods: int, freq: int = 1) -> float:- """附息债券净现值定价。-- Args:- face: 面值,通常100- coupon_rate: 年票面利率(小数形式,如0.05表示5%)- ytm: 年到期收益率(小数形式)- n_periods: 剩余付息期数- freq: 每年付息次数(1=年付,2=半年付)-- Returns:- 债券全价(脏价)-- Examples:- >>> bond_price(100, 0.05, 0.04, 5) # 5年期、5%票息、YTM=4%- 104.4518...- """- c = face * coupon_rate / freq- y = ytm / freq- if y == 0:- return c * n_periods + face- pv_coupons = c * (1 - (1 + y) ** (-n_periods)) / y- pv_face = face / (1 + y) ** n_periods- return pv_coupons + pv_face---def ytm_solve(price: float, face: float, coupon_rate: float,- n_periods: int, freq: int = 1) -> float:- """给定市场价格反求YTM(数值解法)。-- Args:- price: 债券市场价格(脏价)- face: 面值- coupon_rate: 年票面利率- n_periods: 剩余付息期数- freq: 每年付息次数-- Returns:- 年化YTM(小数形式)-- Raises:- ValueError: 无法在合理范围内找到解时- """- def pv_diff(y):- return bond_price(face, coupon_rate, y, n_periods, freq) - price-- try:- return brentq(pv_diff, -0.5, 10.0)- except ValueError as e:- raise ValueError(f"无法求解YTM,检查输入参数: {e}")---def macaulay_duration(face: float, coupon_rate: float, ytm: float,- n_periods: int, freq: int = 1) -> float:- """Macaulay久期(单位:期数,除以freq得年数)。-- Args:- face: 面值- coupon_rate: 年票面利率- ytm: 年到期收益率- n_periods: 剩余付息期数- freq: 每年付息次数-- Returns:- Macaulay久期(年)- """- c = face * coupon_rate / freq- y = ytm / freq- price = bond_price(face, coupon_rate, ytm, n_periods, freq)-- weighted_sum = sum(- t * (c / (1 + y) ** t)- for t in range(1, n_periods)- ) + n_periods * ((c + face) / (1 + y) ** n_periods)-- return (weighted_sum / price) / freq---def modified_duration(face: float, coupon_rate: float, ytm: float,- n_periods: int, freq: int = 1) -> float:- """修正久期。-- Returns:- 修正久期(对ytm的价格弹性,取负号后)- """- d_mac = macaulay_duration(face, coupon_rate, ytm, n_periods, freq)- return d_mac / (1 + ytm / freq)---def convexity(face: float, coupon_rate: float, ytm: float,- n_periods: int, freq: int = 1) -> float:- """债券凸性。-- Returns:- 凸性(年²)- """- c = face * coupon_rate / freq- y = ytm / freq- price = bond_price(face, coupon_rate, ytm, n_periods, freq)-- conv_sum = sum(- t * (t + 1) * (c / (1 + y) ** (t + 2))- for t in range(1, n_periods)- ) + n_periods * (n_periods + 1) * ((c + face) / (1 + y) ** (n_periods + 2))-- return (conv_sum / price) / (freq ** 2)---def dv01(face: float, coupon_rate: float, ytm: float,- n_periods: int, freq: int = 1, par_amount: float = 1_000_000) -> float:- """DV01(每百万面值的基点价值)。-- Args:- par_amount: 持仓面值,默认100万-- Returns:- 每1bp利率变动对应的价格变化(元)- """- d_mod = modified_duration(face, coupon_rate, ytm, n_periods, freq)- price = bond_price(face, coupon_rate, ytm, n_periods, freq)- return d_mod * (price / 100) * 0.0001 * par_amount+from src.quantlib.fixedincome import (+ bond_price, ytm_solve, macaulay_duration, modified_duration,+ convexity, dv01, effective_duration,+)++face, coupon, ytm, n, freq = 100, 0.05, 0.04, 5, 1++price = bond_price(face, coupon, ytm, n, freq) # 104.4518+ytm_solve(price, face, coupon, n, freq) # 0.04(价格反解 YTM)++macaulay_duration(face, coupon, ytm, n, freq) # 4.5571 年+modified_duration(face, coupon, ytm, n, freq) # 4.3818 年+convexity(face, coupon, ytm, n, freq) # 24.4766 年²+dv01(face, coupon, ytm, n, freq, par_amount=1_000_000) # 457.69 元/bp```----+**参数要点**++| 参数 | 说明 |+|------|------|+| `freq` | 每年付息次数,`1`=年付、`2`=半年付。所有函数都接受,绝不写死 |+| `compounding` | `"discrete"`(默认)或 `"continuous"`。连续复利下修正久期恒等于 Macaulay 久期 |+| `par_amount` | `dv01` 的持仓面值,默认 100 万;对冲的市值按 `par_amount * price / face` 计 |+| `bracket` | `ytm_solve` 的求根区间,默认 `(-0.5, 10.0)`,覆盖所有可交易债券 |++含权债(可赎回债、MBS)的现金流会随利率移动,解析久期不适用,改用重新定价法:++```python+d_eff = effective_duration(reprice=lambda y: my_oas_model(y), yield_level=0.04, bump=1e-4)+```++`reprice` 必须自带赎回/早偿逻辑;`effective_duration` 只负责 `(P_down - P_up) / (2·P₀·Δy)`。### 5.2 收益率曲线拟合(Nelson-Siegel / Svensson)```pythonimport numpy as np-from scipy.optimize import minimize-from typing import Tuple---def nelson_siegel(tau: np.ndarray, beta0: float, beta1: float,- beta2: float, lambda1: float) -> np.ndarray:- """Nelson-Siegel 即期利率模型。-- Args:- tau: 期限数组(年)- beta0: 长期利率水平(level)- beta1: 斜率因子(slope)- beta2: 曲率因子(curvature)- lambda1: 曲线衰减速度-- Returns:- 各期限即期利率数组- """- factor1 = (1 - np.exp(-tau / lambda1)) / (tau / lambda1)- factor2 = factor1 - np.exp(-tau / lambda1)- return beta0 + beta1 * factor1 + beta2 * factor2---def svensson(tau: np.ndarray, beta0: float, beta1: float,- beta2: float, beta3: float,- lambda1: float, lambda2: float) -> np.ndarray:- """Svensson 模型(NS扩展,双曲率因子)。-- Args:- tau: 期限数组(年)- beta0-beta3: 参数- lambda1, lambda2: 两个衰减速度参数-- Returns:- 各期限即期利率数组- """- f1 = (1 - np.exp(-tau / lambda1)) / (tau / lambda1)- f2 = f1 - np.exp(-tau / lambda1)- f3 = (1 - np.exp(-tau / lambda2)) / (tau / lambda2) - np.exp(-tau / lambda2)- return beta0 + beta1 * f1 + beta2 * f2 + beta3 * f3---def fit_yield_curve(maturities: np.ndarray, yields: np.ndarray,- model: str = "svensson") -> Tuple[np.ndarray, callable]:- """拟合收益率曲线并返回插值函数。-- Args:- maturities: 已知债券期限(年),如 [0.25, 0.5, 1, 2, 3, 5, 7, 10]- yields: 对应YTM(小数),如 [0.02, 0.021, ...]- model: "nelson_siegel" 或 "svensson"-- Returns:- (最优参数, 插值函数)-- Raises:- ValueError: 未知模型名称- """- if model == "nelson_siegel":- def objective(params):- fitted = nelson_siegel(maturities, *params)- return np.sum((fitted - yields) ** 2)- x0 = [0.04, -0.02, 0.01, 1.5]- bounds = [(0, 0.2), (-0.2, 0.2), (-0.2, 0.2), (0.1, 10)]- result = minimize(objective, x0, method="L-BFGS-B", bounds=bounds)- return result.x, lambda t: nelson_siegel(np.array(t), *result.x)-- elif model == "svensson":- def objective(params):- fitted = svensson(maturities, *params)- return np.sum((fitted - yields) ** 2)- x0 = [0.04, -0.02, 0.01, 0.01, 1.5, 5.0]- bounds = [(0, 0.2), (-0.2, 0.2), (-0.2, 0.2), (-0.2, 0.2),- (0.1, 10), (0.1, 20)]- result = minimize(objective, x0, method="L-BFGS-B", bounds=bounds)- return result.x, lambda t: svensson(np.array(t), *result.x)-- else:- raise ValueError(f"未知模型: {model},支持 nelson_siegel / svensson")+from src.quantlib.fixedincome import fit_yield_curve, nelson_siegel, svensson++maturities = np.array([0.25, 0.5, 1, 2, 3, 5, 7, 10, 20, 30])+yields = np.array([0.019, 0.020, 0.022, 0.024, 0.025, 0.027, 0.028, 0.029, 0.033, 0.035])++fit = fit_yield_curve(maturities, yields, model="svensson")+fit.params # (beta0, beta1, beta2, beta3, lambda1, lambda2)+fit.rmse # 拟合残差(小数,与输入同单位)+fit(4.5) # 任意期限插值 -> 该点即期利率+fit([1, 5, 10]) # 也接受数组```----+`fit_yield_curve` 返回一个 **`CurveFit` 对象**(不是 `(params, func)` 元组):它本身可调用,+同时带 `model` / `params` / `rmse` 三个只读字段。`model` 取 `"nelson_siegel"`(4 参数)+或 `"svensson"`(6 参数,双曲率因子)。++拟合方式是**可分离最小二乘**:给定衰减参数 λ 后 β 是线性的,用 OLS 精确求解,+只对 1~2 个 λ 做网格 + Nelder-Mead 搜索。这一点很要紧——对全部参数一起做单点起始的+L-BFGS-B(本 skill 早先模板的做法)**连自己生成的曲线都还原不回来**:+在 10 个期限的无噪 Nelson-Siegel 曲线上它停在 RMSE 6.4e-4(6.4bp),+而现在这个实现是 4.0e-14。++需要直接按参数取值(例如做因子分解、做情景模拟)时用底层函数:++```python+nelson_siegel(tau=[1, 5, 10], beta0=0.045, beta1=-0.02, beta2=0.03, lambda1=2.5)+svensson(tau=5.0, beta0=0.05, beta1=-0.03, beta2=0.04, beta3=-0.02,+ lambda1=1.2, lambda2=8.0)+```++`beta0` 是水平因子(长端渐近利率),`beta0 + beta1` 是瞬时短端利率,+`beta2` / `beta3` 是曲率因子,`lambda*` 是衰减速度(年)。传标量返回标量,传数组返回数组。### 5.3 Altman Z-Score 计算```python-import pandas as pd---def altman_z_score(working_capital: float, retained_earnings: float,- ebit: float, market_cap: float, total_debt: float,- revenue: float, total_assets: float,- model: str = "original") -> dict:- """Altman Z-Score 违约风险评估。-- Args:- working_capital: 营运资本(流动资产-流动负债)- retained_earnings: 留存收益- ebit: 息税前利润- market_cap: 股权市值(original)或账面净资产(prime/double_prime)- total_debt: 总债务- revenue: 营业收入- total_assets: 总资产- model: "original"(上市制造业)| "prime"(私有企业)| "double_prime"(非制造业)-- Returns:- 含Z-Score、各分项、风险等级的字典- """- x1 = working_capital / total_assets- x2 = retained_earnings / total_assets- x3 = ebit / total_assets- x4 = market_cap / total_debt- x5 = revenue / total_assets-- if model == "original":- z = 1.2*x1 + 1.4*x2 + 3.3*x3 + 0.6*x4 + 1.0*x5- safe_zone = z > 2.99- distress_zone = z < 1.81- elif model == "prime":- z = 0.717*x1 + 0.847*x2 + 3.107*x3 + 0.420*x4 + 0.998*x5- safe_zone = z > 2.90- distress_zone = z < 1.23- elif model == "double_prime":- # 去掉X5(非制造业资产周转率意义不同)- z = 6.56*x1 + 3.26*x2 + 6.72*x3 + 1.05*x4- safe_zone = z > 2.60- distress_zone = z < 1.10- else:- raise ValueError(f"未知模型: {model}")-- if safe_zone:- risk_level = "安全区(低违约风险)"- elif distress_zone:- risk_level = "危险区(高违约风险)"- else:- risk_level = "灰色区(需深入分析)"-- return {- "z_score": round(z, 4),- "risk_level": risk_level,- "components": {- "X1_流动性": round(x1, 4),- "X2_盈利积累": round(x2, 4),- "X3_盈利能力": round(x3, 4),- "X4_杠杆": round(x4, 4),- "X5_效率": round(x5, 4) if model != "double_prime" else "N/A",- }- }+from src.quantlib.credit import altman_z_score++z = altman_z_score(+ working_capital=200, # X1 分子:流动资产 - 流动负债+ retained_earnings=300, # X2 分子:留存收益+ ebit=150, # X3 分子:息税前利润+ equity_value=900, # X4 分子:original 用股权市值,prime/double_prime 用账面净资产+ total_liabilities=600, # X4 分母:全部负债的账面值+ total_assets=1000, # X1/X2/X3/X5 的分母+ revenue=1200, # X5 分子;double_prime 不需要,可省略+ model="original", # original | prime | double_prime+)++z.z_score # 3.255+z.zone # "safe" | "grey" | "distress"+z.label_zh # "安全区(低违约风险)"+z.components # {"x1": 0.20, "x2": 0.30, "x3": 0.15, "x4": 1.50, "x5": 1.20}+z.safe_threshold # 2.99+z.distress_threshold # 1.81```----+三个变体的系数与临界值在 `ALTMAN_MODELS` 里,与 §1.2 的表格一一对应:++| `model` | 适用对象 | 系数 (X1..X5) | 安全 / 危险 |+|---------|----------|---------------|-------------|+| `original` | 上市制造业(Altman 1968) | 1.2 / 1.4 / 3.3 / 0.6 / 1.0 | > 2.99 / < 1.81 |+| `prime`(Z') | 私有企业,X4 改用账面净资产 | 0.717 / 0.847 / 3.107 / 0.420 / 0.998 | > 2.90 / < 1.23 |+| `double_prime`(Z'') | 非制造业 / 新兴市场,去掉 X5 | 6.56 / 3.26 / 6.72 / 1.05 / — | > 2.60 / < 1.10 |++> **X4 的分母是「全部负债」,不是「有息负债」。** §1.2 的变量表写的是"总负债账面值",+> 参数名 `total_liabilities` 与模型定义一致。用有息负债代入会系统性高估 Z 值。-### 5.4 信用利差时序分析+同一份报表在三个变体下给出的分区可以不同(上例:`original` 安全区、`prime` 灰色区),+这正是重新标定的意义,不是矛盾。++### 5.4 信用利差分析```python-import pandas as pd-import numpy as np-from typing import Optional---def credit_spread_analysis(- bond_yields: pd.Series,- risk_free_yields: pd.Series,- window: int = 252,- issuer_name: Optional[str] = None-) -> pd.DataFrame:- """信用利差时序分析(Z-Score标准化 + 历史分位数)。-- Args:- bond_yields: 信用债收益率时间序列(%,日频)- risk_free_yields: 对应期限无风险利率(%,日频)- window: 滚动窗口(交易日数),默认252(1年)- issuer_name: 发行人名称,用于输出标注-- Returns:- 含信用利差、Z-Score、历史分位数的DataFrame-- Raises:- ValueError: 输入序列长度不一致时- """- if len(bond_yields) != len(risk_free_yields):- raise ValueError("收益率序列长度必须一致")-- spread = bond_yields - risk_free_yields- spread.name = f"{issuer_name or '未知发行人'}_信用利差(bp)"- spread_bp = spread * 100 # 转换为基点-- result = pd.DataFrame({"信用利差_bp": spread_bp})-- # 滚动统计- result["滚动均值"] = spread_bp.rolling(window).mean()- result["滚动标准差"] = spread_bp.rolling(window).std()- result["Z-Score"] = (spread_bp - result["滚动均值"]) / result["滚动标准差"]-- # 历史分位数(使用全样本)- result["历史分位数"] = spread_bp.rank(pct=True)-- # 利差变化- result["日变化_bp"] = spread_bp.diff()- result["月变化_bp"] = spread_bp.diff(21)-- # 信号生成- result["利差信号"] = "中性"- result.loc[result["Z-Score"] < -1.5, "利差信号"] = "偏贵(利差偏低)"- result.loc[result["Z-Score"] > 1.5, "利差信号"] = "偏便宜(利差偏高)"-- return result---def spread_term_structure(- issuers: dict,- risk_free_curve: pd.Series-) -> pd.DataFrame:- """信用利差期限结构分析。-- Args:- issuers: {发行人: {期限: 收益率}} 字典- 例:{"AAA城投": {1: 0.025, 3: 0.028, 5: 0.032}}- risk_free_curve: 无风险利率曲线 {期限: 收益率}-- Returns:- 信用利差期限结构矩阵(行=发行人,列=期限)- """- records = []- for issuer, ytm_curve in issuers.items():- row = {"发行人": issuer}- for term, ytm in ytm_curve.items():- rf = risk_free_curve.get(term, np.nan)- row[f"{term}Y利差(bp)"] = round((ytm - rf) * 10000, 1)- records.append(row)- return pd.DataFrame(records).set_index("发行人")+from src.quantlib.credit import credit_spread_analysis, spread_term_structure++df = credit_spread_analysis(+ bond_yields=bond_ytm_series, # pd.Series,索引=日期+ risk_free_yields=cgb_ytm_series, # 必须与上面同一个索引+ window=252, # 滚动窗口(交易日)+ lookback_periods=21, # 慢速变化列的回溯期+ signal_z=1.5, # 触发 rich/cheap 的 |z| 阈值+ input_unit="percent", # percent | decimal | bp+)```----+返回的 DataFrame 列固定为:`spread_bp`、`rolling_mean_bp`、`rolling_std_bp`、`z_score`、+`historical_percentile`、`change_1p_bp`、`change_lookback_bp`、`signal`。+`signal` 取 `"rich"`(利差偏低、偏贵)/ `"neutral"` / `"cheap"`(利差偏高、偏便宜)。-### 5.5 Merton 模型违约概率+> **`historical_percentile` 是全样本排名,带前视偏差,不能当回测信号用。** 它把每一行+> 和它**之后**的行一起排序——同一天的分位数会随着新数据到来而改变(实测:同一行在 50 行+> 切片上是 0.02,在 100 行上变成 0.01)。这是原模板的行为,保留是为了不静默改变口径。+> `z_score` 与 `signal` 走滚动窗口,是因果的,要做信号用这两个。```python-import numpy as np-from scipy.stats import norm-from scipy.optimize import fsolve-from typing import Tuple---def merton_model(- equity_value: float,- equity_vol: float,- debt_face: float,- risk_free: float,- T: float-) -> dict:- """Merton结构化模型:估算违约概率和信用利差。-- Args:- equity_value: 股权市值(亿元)- equity_vol: 股权年化波动率(小数)- debt_face: 债务面值(亿元,简化为零息债)- risk_free: 无风险利率(小数)- T: 债务到期年限-- Returns:- 含资产价值、距违约距离、违约概率、信用利差的字典- """- def equations(params):- V, sigma_V = params- d1 = (np.log(V / debt_face) + (risk_free + 0.5 * sigma_V**2) * T) / (sigma_V * np.sqrt(T))- d2 = d1 - sigma_V * np.sqrt(T)-- # 方程1:股权=资产看涨期权- eq1 = V * norm.cdf(d1) - debt_face * np.exp(-risk_free * T) * norm.cdf(d2) - equity_value- # 方程2:股权波动率=资产波动率的杠杆放大- eq2 = norm.cdf(d1) * sigma_V * V - equity_vol * equity_value- return [eq1, eq2]-- # 初始值估计- V0 = equity_value + debt_face- sigma_V0 = equity_vol * equity_value / V0-- solution = fsolve(equations, [V0, sigma_V0], full_output=True)- V_star, sigma_V_star = solution[0]-- d1 = (np.log(V_star / debt_face) + (risk_free + 0.5 * sigma_V_star**2) * T) / (sigma_V_star * np.sqrt(T))- d2 = d1 - sigma_V_star * np.sqrt(T)-- # 风险中性违约概率- pd_rn = norm.cdf(-d2)-- # 距违约距离(真实世界近似,用无风险利率代替真实漂移)- dd = d2-- # 信用利差(简化估算)- debt_value = debt_face * np.exp(-risk_free * T) * norm.cdf(d2) + V_star * norm.cdf(-d1)- if debt_value > 0 and T > 0:- credit_spread = -np.log(debt_value / (debt_face * np.exp(-risk_free * T))) / T- else:- credit_spread = np.nan-- return {- "资产价值_亿": round(V_star, 2),- "资产波动率": round(sigma_V_star, 4),- "距违约距离_DD": round(dd, 3),- "违约概率_RN": f"{pd_rn*100:.2f}%",- "信用利差_bp": round(credit_spread * 10000, 1) if not np.isnan(credit_spread) else "N/A",- }+grid = spread_term_structure(+ issuers={"AAA城投": {1: 0.025, 3: 0.028, 5: 0.032},+ "AA城投": {1: 0.032, 3: 0.041, 5: 0.055}},+ risk_free_curve={1: 0.020, 3: 0.022, 5: 0.025},+ input_unit="decimal", # 注意默认值与上面那个函数不同+ decimals=1,+)+# 行=发行人,列=1Y_spread_bp / 3Y_spread_bp / 5Y_spread_bp```+> **输入单位必须自己确认。** 两个函数的历史默认值不一致:`credit_spread_analysis`+> 默认收益率是**百分数**(`3.2` 表示 3.2%),`spread_term_structure` 默认是**小数**(`0.032`)。+> 默认值保留了原模板的行为,但 `input_unit` 现在是显式参数——喂数据前先看清楚手里的序列是哪一种,+> 搞反就是 100 倍的利差。++### 5.5 Merton 结构化模型与 KMV++```python+from src.quantlib.credit import (+ merton_model, merton_asset_solve, distance_to_default,+ kmv_default_point, kmv_distance_to_default, edf_reference_band,+)++m = merton_model(+ equity_value=100, # 股权市值+ equity_vol=0.40, # 股权年化波动率+ debt_face=100, # 债务面值(简化为单笔零息债)+ risk_free=0.03, # 连续复利无风险利率+ horizon=1.0, # 债务到期年限+ asset_drift=None, # 距违约距离用的资产漂移;None = 用 risk_free(风险中性口径)+)++m.asset_value # 197.04 反推出的资产价值+m.asset_vol # 0.2030 反推出的资产波动率+m.distance_to_default # 3.3868 asset_drift=None 时等于 d2+m.default_probability # 0.000354 风险中性违约概率 N(-d2)+m.credit_spread_bp # 0.176 bp+```++联立方程(§1.3 的两式)在 `merton_asset_solve` 里解,且是在**对数空间**求解的,+所以根不会跑到负资产或负波动率上;不收敛会直接抛 `ValueError`,不会静默返回垃圾解。++**Merton 与 KMV 的 DD 是两个不同的量,不要混用**:++```python+# Merton:对数空间、带漂移与期限+distance_to_default(asset_value=200, asset_vol=0.25, default_point=100,+ horizon=2.0, drift=0.06)++# KMV:线性缺口,无期限无漂移,违约点只含短债 + 部分长债+dp = kmv_default_point(short_term_debt=100, long_term_debt=200,+ long_term_weight=0.5) # -> 200+kmv_distance_to_default(asset_value=1000, asset_vol=0.25, default_point=dp) # -> 3.2++edf_reference_band(3.2) # -> (0.001, 0.01),即 §8 表里的 0.1%–1% 档+```++> `edf_reference_band` 只是把 §8 那张"DD → EDF"经验表做成了查表函数。+> 真正的 KMV EDF 来自穆迪的专有违约数据库,这里的输出只能当**量级校验**,+> 绝不能当作已标定的违约概率报出去。++**风险中性 vs 真实世界**:`asset_drift` 只影响 `distance_to_default`,不影响 `d2`、+`default_probability` 和 `credit_spread`——后三者按定义就是风险中性的。想看真实世界口径,+传一个预期资产回报进去,然后配 `edf_reference_band` 读档,不要拿 `N(-dd)` 当 EDF 报。+---## 六、中国固收市场特色diff --git a/agent/src/skills/execution-model/SKILL.md b/agent/src/skills/execution-model/SKILL.mdindex a4a49e316..919832a47 100644--- a/agent/src/skills/execution-model/SKILL.md+++ b/agent/src/skills/execution-model/SKILL.md@@ -24,22 +24,26 @@ Real world:No slippage model -> overly optimistic backtest -> losses in live trading```+**Do not retype these models.** All four are implemented and tested in+`src/quantlib/impact.py`; import them. The tested versions validate their inputs —+a zero ADV raises instead of dividing by zero, and a negative `delay_bars` raises+instead of silently introducing look-ahead bias.++```python+from src.quantlib.impact import fixed_slippage, linear_impact, sqrt_impact, delayed_execution+```+### 1. Fixed Slippage Model```python-def fixed_slippage(price: float, direction: int, bps: float = 5.0) -> float:- """- Args:- price: Original price- direction: 1=buy, -1=sell- bps: Slippage in basis points (1bp = 0.01%), default 5bp- Returns:- Execution price after slippage- """- slippage = price * bps / 10000- return price + direction * slippage+fixed_slippage(price=100.0, direction=1, bps=5.0) # 100.05 (buy pays up)+fixed_slippage(price=100.0, direction=-1, bps=5.0) # 99.95 (sell receives less)```+`direction` is 1 to buy or -1 to sell, and must be exactly one of those — it+multiplies the impact, so an unchecked 2 would silently double the modelled cost.+`bps` defaults to `DEFAULT_SLIPPAGE_BPS` (5.0).+**Reference fixed-slippage assumptions by market:**| Market | Instrument | Suggested Slippage (bps) | Notes |@@ -55,27 +59,17 @@ def fixed_slippage(price: float, direction: int, bps: float = 5.0) -> float:### 2. Linear Impact Model+`impact = impact_coeff × volume_traded / adv`+```python-def linear_impact(price: float, direction: int,- volume_traded: float, adv: float,- impact_coeff: float = 0.1) -> float:- """- Linear market impact: impact ∝ traded volume / ADV-- Args:- price: Original price- direction: 1=buy, -1=sell- volume_traded: Trade size (shares or notional)- adv: Average Daily Volume- impact_coeff: Impact coefficient, usually 0.05-0.2- Returns:- Execution price after impact- """- participation_rate = volume_traded / adv- impact = impact_coeff * participation_rate- return price * (1 + direction * impact)+# 100k shares against 1M ADV = 10% participation; at coeff 0.1 that is a 1% move.+linear_impact(price=100.0, direction=1, volume_traded=100_000, adv=1_000_000, impact_coeff=0.1)+# 101.0```+Marginal impact is constant here, which overstates the cost of very large orders.+`impact_coeff` defaults to `DEFAULT_LINEAR_IMPACT_COEFF` (0.1).+**Reference impact coefficients:**| Market | impact_coeff | Notes |@@ -85,38 +79,31 @@ def linear_impact(price: float, direction: int,| US equities | 0.03-0.08 | Market-maker buffering || Crypto | 0.05-0.15 | 24h trading is dispersed |-### 3. Square-Root Impact Model (Almgren-Chriss)+### 3. Square-Root Impact Model++`impact = η × σ × sqrt(volume_traded / adv)````python-import numpy as np--def sqrt_impact(price: float, direction: int,- volume_traded: float, adv: float,- volatility: float, eta: float = 0.5) -> float:- """- Square-root market impact (more accepted in academia):- impact = η × σ × sqrt(V/ADV)-- Args:- price: Original price- direction: 1=buy, -1=sell- volume_traded: Trade size- adv: Average daily volume- volatility: Daily volatility (standard deviation)- eta: Impact elasticity coefficient, usually 0.3-0.8- Returns:- Execution price after impact- """- participation = volume_traded / adv- impact = eta * volatility * np.sqrt(participation)- return price * (1 + direction * impact)+# 250k against 1M ADV = 25% participation; 0.5 × 0.02 × sqrt(0.25) = 0.005 = 50bps.+sqrt_impact(price=100.0, direction=1, volume_traded=250_000, adv=1_000_000,+ volatility=0.02, eta=0.5)+# 100.5 (100.49999999999999 in binary floating point)```+`volatility` is daily return volatility as a decimal fraction. `eta` defaults to+`DEFAULT_SQRT_IMPACT_ETA` (0.5); 0.3-0.8 is the usual calibrated range.+**Advantages of the square-root model**:- Strongest empirical support (standard in financial literature)- Marginal impact declines for larger orders (intuitive)- Parameters can be estimated from historical data+> **Naming.** This impact term is often labelled "Almgren-Chriss", and it does come+> from that literature, but it is **not** Almgren-Chriss optimal execution. There is+> no trading trajectory, no permanent/temporary impact split and no risk-aversion+> parameter here, and none is implemented anywhere in this repository. Call it a+> square-root impact function, and do not claim an optimal schedule was computed.+### Slippage Model Selection Decision Tree```@@ -173,22 +160,17 @@ Pros and cons:### Simulating Execution Delay in Backtests```python-def delayed_execution(signal_series: pd.Series, delay_bars: int = 1) -> pd.Series:- """- Simulate the delay from signal generation to execution-- Args:- signal_series: Original signal- delay_bars: Number of bars to delay, default 1 (T+1 execution)- Returns:- Delayed signal-- China A-shares: delay_bars=1 (T+1 rule)- Crypto: delay_bars=0 or 1- """- return signal_series.shift(delay_bars)+signals = delayed_execution(raw_signal, delay_bars=1) # T+1: trade tomorrow on today's signal+signals = delayed_execution(raw_signal, delay_bars=0) # same-bar execution```+- China A-shares: `delay_bars=1` (T+1 rule)+- Crypto: `delay_bars=0` or `1`++A negative `delay_bars` raises. It would pull future signal values into the past,+which is look-ahead bias and silently inflates every backtest containing it — the+tested implementation refuses rather than letting that pass unnoticed.+## Integrated Transaction-Cost Model### Total Cost Breakdown@@ -246,6 +228,9 @@ Implicit cost:### Advanced Execution Assumptions (implemented in `signal_engine.py`)```python+from src.quantlib.impact import delayed_execution++class SignalEngine:def __init__(self):# Execution assumption parameters@@ -259,7 +244,7 @@ class SignalEngine:raw_signal = self._compute_signal(df)# 2. Apply execution delay- delayed_signal = raw_signal.shift(self.execution_delay)+ delayed_signal = delayed_execution(raw_signal, self.execution_delay)# 3. Apply volume filter (do not trade when liquidity is too low)volume_ok = df['volume'] > df['volume'].rolling(20).mean() * 0.3@@ -347,3 +332,4 @@ Conclusion: the strategy still has meaningful profitability under 10bps slippage5. **Volume constraints**: order size should not exceed 5-10% of the day’s traded volume, otherwise the impact model becomes invalid6. **Backtest overfitting**: even with slippage included, the strategy may still overfit; out-of-sample validation matters more7. **`commission` in config**: the default `0.001` (0.1%) is a reasonable all-in cost estimate+8. **The models are implemented, not improvised**: `src/quantlib/impact.py` holds all four, tested. Import them rather than retyping; the tested versions reject a zero ADV, a negative order size and a negative execution delay, all of which the retyped versions used to accept silentlydiff --git a/agent/src/skills/market-microstructure/SKILL.md b/agent/src/skills/market-microstructure/SKILL.mdindex 1a21f5060..38c06c303 100644--- a/agent/src/skills/market-microstructure/SKILL.md+++ b/agent/src/skills/market-microstructure/SKILL.md@@ -130,7 +130,15 @@ Amihud calculation (China A-shares):### 1. Price-Impact Models-**Linear impact (Almgren-Chriss)**:+**Power-law impact**:++> **Naming.** This is the concave impact term from the Almgren-Chriss+> literature, and it is neither linear (the exponent is 0.6, not 1) nor+> Almgren-Chriss *optimal execution* — no trading trajectory, no+> permanent/temporary split and no risk-aversion parameter is computed here or+> anywhere in this repo. The tested implementation is+> `src.quantlib.impact.sqrt_impact`; call it rather than retyping the formula.+```Model: impact = η × σ × (Q / V)^0.6η: impact coefficient, about 0.5-1.5 for China A-sharesdiff --git a/agent/src/skills/options-payoff/SKILL.md b/agent/src/skills/options-payoff/SKILL.mdindex d43a934e9..b735f0271 100644--- a/agent/src/skills/options-payoff/SKILL.md+++ b/agent/src/skills/options-payoff/SKILL.md@@ -202,6 +202,10 @@ Notes:- IV > 500% is usually an outlier and should be filtered```+This is already implemented, guards included, as+`src.quantlib.options.implied_volatility` — see section 4.1. The formulas above+document what it computes; they are not an instruction to rewrite it.+---## 3. Payoff Diagram Analysis@@ -262,174 +266,51 @@ Plot one theoretical value curve for each `σ` and distinguish them by color to## 4. Python Code Templates-### 4.1 Black-Scholes Pricing Functions--```python-import numpy as np-from scipy.stats import norm-from scipy.optimize import brentq-from typing import Literal--def bs_price(- S: float,- K: float,- T: float,- r: float,- sigma: float,- option_type: Literal["call", "put"],- q: float = 0.0,-) -> float:- """Black-Scholes option pricing.-- Args:- S: Current underlying price- K: Strike price- T: Time to expiration in years- r: Risk-free rate in annualized continuous compounding, e.g. 0.03- sigma: Annualized volatility, e.g. 0.20- option_type: "call" or "put"- q: Continuous dividend yield, defaults to 0-- Returns:- Theoretical option price-- Raises:- ValueError: If sigma <= 0- """- if T <= 0:- # After expiration, return intrinsic value directly.- if option_type == "call":- return max(0.0, S - K)- return max(0.0, K - S)- if sigma <= 0:- raise ValueError(f"sigma must be > 0, got {sigma}")-- d1 = (np.log(S / K) + (r - q + 0.5 * sigma**2) * T) / (sigma * np.sqrt(T))- d2 = d1 - sigma * np.sqrt(T)-- if option_type == "call":- price = S * np.exp(-q * T) * norm.cdf(d1) - K * np.exp(-r * T) * norm.cdf(d2)- else:- price = K * np.exp(-r * T) * norm.cdf(-d2) - S * np.exp(-q * T) * norm.cdf(-d1)-- return float(price)---def bs_greeks(- S: float,- K: float,- T: float,- r: float,- sigma: float,- option_type: Literal["call", "put"],- q: float = 0.0,-) -> dict:- """Calculate the five major Greeks under the Black-Scholes model.-- Returns:- A dict with keys: delta, gamma, theta, vega, rho.- Theta and Vega are already converted to per-day and per-1% units.- """- if T <= 1e-6:- return {"delta": 0.0, "gamma": 0.0, "theta": 0.0, "vega": 0.0, "rho": 0.0}-- d1 = (np.log(S / K) + (r - q + 0.5 * sigma**2) * T) / (sigma * np.sqrt(T))- d2 = d1 - sigma * np.sqrt(T)- n_prime_d1 = norm.pdf(d1)- exp_qt = np.exp(-q * T)- exp_rt = np.exp(-r * T)-- if option_type == "call":- delta = exp_qt * norm.cdf(d1)- rho = K * T * exp_rt * norm.cdf(d2) / 100- theta = (- -S * exp_qt * n_prime_d1 * sigma / (2 * np.sqrt(T))- - r * K * exp_rt * norm.cdf(d2)- + q * S * exp_qt * norm.cdf(d1)- ) / 365- else:- delta = exp_qt * (norm.cdf(d1) - 1)- rho = -K * T * exp_rt * norm.cdf(-d2) / 100- theta = (- -S * exp_qt * n_prime_d1 * sigma / (2 * np.sqrt(T))- + r * K * exp_rt * norm.cdf(-d2)- - q * S * exp_qt * norm.cdf(-d1)- ) / 365-- gamma = exp_qt * n_prime_d1 / (S * sigma * np.sqrt(T))- vega = S * exp_qt * n_prime_d1 * np.sqrt(T) / 100-- return {- "delta": round(delta, 6),- "gamma": round(gamma, 6),- "theta": round(theta, 6),- "vega": round(vega, 6),- "rho": round(rho, 6),- }---def implied_volatility(- market_price: float,- S: float,- K: float,- T: float,- r: float,- option_type: Literal["call", "put"],- q: float = 0.0,- tol: float = 1e-6,- max_iter: int = 200,-) -> float:- """Solve implied volatility with Newton-Raphson.-- Args:- market_price: Observed market price- tol: Convergence tolerance- max_iter: Maximum number of iterations-- Returns:- Annualized implied volatility. Returns np.nan on failure.+### 4.1 Black-Scholes Pricing Functions — Import, Do Not Retype- Raises:- ValueError: If the market price is below intrinsic value- """- # Check intrinsic value first.- intrinsic = max(0.0, S - K if option_type == "call" else K - S)- if market_price < intrinsic - 1e-6:- raise ValueError(f"Market price {market_price} is below intrinsic value {intrinsic}")+`bs_price`, `bs_greeks` and `implied_volatility` are implemented once in+`src/quantlib/options.py` and pinned by `tests/quantlib/test_options.py`+(published Hull reference values, put-call parity, Greeks against+finite-difference bumps, implied-vol round-trips). Import them.- # Brenner-Subrahmanyam initial approximation.- sigma = np.sqrt(2 * np.pi / T) * market_price / S- sigma = max(0.001, min(sigma, 5.0))+**Do not retype the formulas from section 2 into your own helper.** A retyped+copy is a different, untested function on every run, and the copies that used to+live here had two live defects: they crashed on a non-positive spot or strike,+and they reported a zero Delta for an expiring in-the-money option.- for _ in range(max_iter):- price = bs_price(S, K, T, r, sigma, option_type, q)- vega = bs_greeks(S, K, T, r, sigma, option_type, q)["vega"] * 100 # restore per-1.0 unit+```python+from src.quantlib.options import bs_greeks, bs_price, implied_volatility- diff = price - market_price- if abs(diff) < tol:- return round(sigma, 6)+price = bs_price(S=100, K=100, T=0.25, r=0.03, sigma=0.20, option_type="call", q=0.0)+greeks = bs_greeks(100, 100, 0.25, 0.03, 0.20, "call") # delta gamma theta vega rho+iv = implied_volatility(market_price=5.0, S=100, K=100, T=0.25, r=0.03, option_type="call")+```- if abs(vega) < 1e-10:- # Vega is near zero, fall back to bisection.- try:- return float(brentq(- lambda v: bs_price(S, K, T, r, v, option_type, q) - market_price,- 1e-4, 10.0, xtol=tol, maxiter=200- ))- except ValueError:- return np.nan+Argument order is `(S, K, T, r, sigma, option_type="call", q=0.0)` for both+pricing functions; `implied_volatility` takes `market_price` first, then+`(S, K, T, r, option_type="call", q=0.0, tol=1e-6, max_iter=200)`.- sigma -= diff / vega- sigma = max(1e-4, min(sigma, 10.0)) # clamp to a reasonable range+Contract worth knowing before you use the numbers:- return np.nan # did not converge-```+| Point | Behaviour |+|---|---|+| Units | Theta per calendar day; Vega and Rho per 1 percentage point; Delta and Gamma per 1.0 of spot. Nothing is rounded |+| `option_type` | Case-insensitive; anything other than call/put raises `ValueError` |+| Degenerate input | `T <= 0`, `sigma <= 0`, `S <= 0` or `K <= 0` returns intrinsic value, and Greeks with the correct ±1/0 point-mass Delta — it does not raise |+| IV lower guard | Raises `ValueError` below the **discounted** forward intrinsic. Using undiscounted `K - S` instead would wrongly reject deep ITM European puts, which really do trade below it |+| IV upper guard | Raises `ValueError` at or above the no-arbitrage ceiling (`S·e^(-qT)` for a call, `K·e^(-rT)` for a put) — no volatility reaches it |+| IV failure | Newton seeded by Brenner-Subrahmanyam, falling back to bisection when Vega collapses; returns `nan` only if neither converges |### 4.2 Multi-Leg Portfolio Payoff Calculation```pythonfrom dataclasses import dataclass+from typing import Literal+import numpy as np+from scipy.optimize import brentq++from src.quantlib.options import bs_price@dataclassclass OptionLeg:@@ -708,6 +589,8 @@ def plot_payoff_plotly(### 4.5 Greeks Profile vs Underlying Price```python+from src.quantlib.options import bs_greeks+def plot_greeks_profile(legs: list[OptionLeg],S_current: float,@@ -846,6 +729,8 @@ Underlying approaches the call strike:## Quick Usage Example```python+from src.quantlib.options import implied_volatility+# Example: Iron Condor payoff diagramlegs = [OptionLeg("put", K=90, direction=-1, premium=1.5, T=0.083, sigma=0.20),@@ -866,5 +751,5 @@ iv = implied_volatility(market_price=5.0, S=100, K=100,T=0.25, r=0.03, option_type="call")-print(f"Implied volatility: {iv:.2%}") # about 0.20+print(f"Implied volatility: {iv:.2%}") # 23.25%```diff --git a/agent/src/skills/performance-attribution/SKILL.md b/agent/src/skills/performance-attribution/SKILL.mdindex 8881ccc94..349e651d9 100644--- a/agent/src/skills/performance-attribution/SKILL.md+++ b/agent/src/skills/performance-attribution/SKILL.md@@ -12,18 +12,10 @@ Decompose portfolio excess returns into explainable sources: sector allocation,## Brinson Attribution Model-### Single-Period Brinson-Fachler Model--```-Total excess return = portfolio return - benchmark return--Decomposed into three parts:-1. Allocation effect: sector-weight deviation × sector benchmark return deviation-2. Selection effect: stock selection within a sector × sector benchmark weight-3. Interaction effect: weight deviation × stock-selection deviation-```+**Do not retype these formulas into throwaway Python.** They are implemented and+tested in `src/quantlib/attribution.py`; import them.-**Mathematical formulas**:+### Single-Period Brinson-Fachler Model```Let w_p,i = portfolio weight of sector i@@ -32,45 +24,117 @@ Let w_p,i = portfolio weight of sector ir_b,i = benchmark return of sector iR_b = total benchmark return-Allocation_i = (w_p,i - w_b,i) × (r_b,i - R_b)-Selection_i = w_b,i × (r_p,i - r_b,i)+Allocation_i = (w_p,i - w_b,i) × (r_b,i - R_b)+Selection_i = w_b,i × (r_p,i - r_b,i)Interaction_i = (w_p,i - w_b,i) × (r_p,i - r_b,i)-Total excess = Σ(Allocation_i) + Σ(Selection_i) + Σ(Interaction_i)+Total active return = Σ(Allocation_i) + Σ(Selection_i) + Σ(Interaction_i)+```++**The decomposition itself has no residual term.** The three effects sum to+`R_p - R_b` identically, for any sector returns whatsoever, provided the+portfolio and benchmark weights carry the same total. `brinson_fachler` enforces+the weight-sum precondition and raises rather than returning a decomposition+that does not tie out.++A residual is therefore never a property of the algebra — but it is a real and+expected property of a *reported* attribution, because the inputs are a+snapshot. Intra-period trading, cash drag, corporate actions and FX translation+all move the actual portfolio return away from the one these weights and sector+returns imply. So:++- residual inside the decomposition, given the inputs → **impossible**; if you+ see one, the arithmetic or the weight convention is wrong;+- residual between the decomposition and the reported fund return → **normal**;+ quantify it and attribute it to its source rather than absorbing it silently+ into selection. This is what the `/attrib` reconciliation gate asks for.++```python+from src.quantlib.attribution import brinson_fachler++result = brinson_fachler(+ portfolio_weights={"Tech": 0.40, "Financials": 0.10, "Energy": 0.30, "Health": 0.20},+ benchmark_weights={"Tech": 0.25, "Financials": 0.30, "Energy": 0.25, "Health": 0.20},+ portfolio_returns={"Tech": 0.12, "Financials": 0.04, "Energy": -0.02, "Health": 0.07},+ benchmark_returns={"Tech": 0.10, "Financials": 0.05, "Energy": -0.01, "Health": 0.06},+)++result.portfolio_return # 0.0600+result.benchmark_return # 0.0495+result.active_return # 0.0105+result.allocation # 0.0045+result.selection # 0.0015+result.interaction # 0.0045+# 0.0045 + 0.0015 + 0.0045 == 0.0105 exactly (residual ~3e-18, machine epsilon)++for effect in result.sectors:+ print(effect.sector, effect.allocation, effect.selection, effect.interaction, effect.total)```+A sector return may be omitted only where the matching weight is zero. A+benchmark sector you did not own therefore shows zero selection and zero+interaction, and the whole effect lands in allocation — you cannot demonstrate+stock-picking skill in something you never held.+### Example Brinson Attribution+Rendered from the call above, so every figure below is reproducible:+```markdown### Brinson Sector Attribution| Sector | Portfolio Weight | Benchmark Weight | Portfolio Return | Benchmark Return | Allocation | Selection | Interaction ||------|---------|---------|---------|---------|---------|---------|---------|-| Food & Beverage | 20% | 10% | 15% | 8% | +0.3% | +0.7% | +0.7% |-| Electronics | 15% | 12% | 5% | 10% | -0.1% | -0.6% | +0.2% |-| Banks | 5% | 20% | 3% | 2% | +0.3% | +0.2% | -0.2% |-| Others | 60% | 58% | 8% | 7% | +0.0% | +0.6% | +0.0% |-| **Total** | 100% | 100% | 9.5% | 6.2% | **+0.5%** | **+0.9%** | **+0.7%** |+| Tech | 40% | 25% | 12% | 10% | +0.7575% | +0.50% | +0.30% |+| Financials | 10% | 30% | 4% | 5% | -0.0100% | -0.30% | +0.20% |+| Energy | 30% | 25% | -2% | -1% | -0.2975% | -0.25% | -0.05% |+| Health | 20% | 20% | 7% | 6% | +0.0000% | +0.20% | +0.00% |+| **Total** | 100% | 100% | 6.00% | 4.95% | **+0.45%** | **+0.15%** | **+0.45%** |-Excess return 3.3% = allocation effect 0.5% + selection effect 0.9% + interaction effect 0.7% + residual 0.2%+Active return 1.05% = allocation 0.45% + selection 0.15% + interaction 0.45%. No residual.```### Multi-Period Attribution (Linked Brinson)+Single-period effects add, but returns compound, so simply summing each period's+effects does **not** reproduce the compounded active return. Take the four-sector+period above and two more like it (the exact three are the `_three_periods`+fixture in `tests/quantlib/test_attribution.py`, so you can run them): summing the+three active returns gives 2.8500%, while the compounded active return is 3.0318%+— an 18.2bp error that grows with the horizon and the return level.++Use **Carino logarithmic linking**, implemented as `carino_link`. It is+residual-free, and its per-period scaling factor depends only on that period's+total portfolio and benchmark return — never on the effects being linked — so+linking is deterministic and cannot be steered by how sectors were bucketed.+(Menchero linking is also residual-free but distributes a correction term derived+from the effects themselves; Carino needs less machinery for the same guarantee.)+```-Directly summing single-period attribution creates residuals (compounding effect). Common approaches:+k = (ln(1 + R_P) - ln(1 + R_B)) / (R_P - R_B) # over the whole horizon+k_t = (ln(1 + R_p,t) - ln(1 + R_b,t)) / (R_p,t - R_b,t) # for period t-Method 1: arithmetic linking (simple sum of each period's attribution)- - Advantage: simple- - Disadvantage: residual remains+linked effect = Σ_t (k_t / k) × effect_{i,t}+```++```python+from src.quantlib.attribution import brinson_fachler, carino_link-Method 2: Carino logarithmic linking- - Advantage: no residual- - Disadvantage: more complex+periods = [brinson_fachler(**month) for month in monthly_inputs]+linked = carino_link(periods)-Practical recommendation: arithmetic linking is enough for monthly attribution; residuals are usually <0.1%+linked.active_return # compounded, not summed+linked.allocation, linked.selection, linked.interaction+linked.scaling_factors # one k_t / k per period, exposed so a report can be audited++for sector in linked.sectors:+ print(sector.sector, sector.total)+# allocation + selection + interaction == linked.active_return exactly```+Arithmetic linking is acceptable **only** when you explicitly report the residual.+Since `carino_link` costs one function call and leaves none, prefer it.+## Factor Attribution### Alpha-Beta Decomposition@@ -252,3 +316,4 @@ Watch the risk of excessive small-cap exposure (`SMB beta=0.25`).5. **Multiple-testing problem**: if you test 100 strategies, about 5 may appear significant by chance (`p=0.05`); use multiple-comparison correction6. **Factor data requirement**: factor attribution requires factor return data, which can be obtained from `tushare` or self-constructed7. **Attribution in backtest reports**: `metrics.csv` already provides basic metrics after a backtest; this skill adds deeper attribution analysis+8. **Brinson is implemented, not improvised**: `src/quantlib/attribution.py` holds the tested single-period and Carino-linked decomposition. Import it. Hand-written attribution code that reports a single-period residual is a bug in that code, not a property of the modeldiff --git a/agent/src/skills/quant-statistics/SKILL.md b/agent/src/skills/quant-statistics/SKILL.mdindex a6e25f3b0..b30abeca8 100644--- a/agent/src/skills/quant-statistics/SKILL.md+++ b/agent/src/skills/quant-statistics/SKILL.md@@ -10,6 +10,20 @@ category: analysisCommon statistical methodology used in quantitative investing, covering time-series testing, volatility modeling, regression diagnostics, and statistical inference. Provides the statistical foundation for strategy development and factor research.+## Implementation++Every test below is already implemented and unit-tested in `src.quantlib.timeseries`. **Import and call it — do not retype these formulas into throwaway code**, which is how sign errors and double-sqrt bugs get into results.++```python+from src.quantlib.timeseries import (+ adf_test, cointegration_test, find_hedge_ratio, compute_half_life,+ granger_test, fit_garch, heteroscedasticity_test, autocorrelation_test,+ vif_test, bootstrap_statistic, bootstrap_sharpe,+)+```++**Optional backends**: `statsmodels` powers everything except the two bootstrap helpers (which are pure numpy); `arch` powers `fit_garch` only. Neither is declared as a dependency of `vibe-trading-ai`, so both are imported lazily inside the functions. Importing the module always works; calling a function whose backend is missing raises an `ImportError` naming the package and the install command (`pip install "statsmodels>=0.14"` / `pip install "arch>=6.0"`). If you hit that error, report it to the user rather than silently substituting a different method.+## Time-Series Tests### 1. ADF Unit-Root Test (Stationarity Test)@@ -17,26 +31,16 @@ Common statistical methodology used in quantitative investing, covering time-ser**Why it matters**: regressing non-stationary series directly can produce spurious regression, making conclusions unreliable.```python-from statsmodels.tsa.stattools import adfuller--def adf_test(series: pd.Series, significance: float = 0.05) -> dict:- """- ADF test: H0 = unit root exists (non-stationary), H1 = stationary-- Args:- series: Time series- significance: Significance level- Returns:- Test result- """- result = adfuller(series.dropna(), autolag='AIC')- return {- 'adf_statistic': result[0],- 'p_value': result[1],- 'lags_used': result[2],- 'is_stationary': result[1] < significance,- 'critical_values': result[4], # 1%, 5%, 10%- }+from src.quantlib.timeseries import adf_test++result = adf_test(prices['close'], significance=0.05)+# {'adf_statistic': -1.23, 'p_value': 0.65, 'lags_used': 4,+# 'is_stationary': False,+# 'critical_values': {'1%': -3.44, '5%': -2.87, '10%': -2.57}}++if not result['is_stationary']:+ returns = np.log(prices['close']).diff().dropna()+ adf_test(returns) # log returns are normally stationary```**Decision rules**:@@ -63,59 +67,41 @@ def adf_test(series: pd.Series, significance: float = 0.05) -> dict:**Purpose**: determine whether two non-stationary series share a long-run equilibrium relationship (the foundation of pair trading / statistical arbitrage).```python-from statsmodels.tsa.stattools import coint--def cointegration_test(y: pd.Series, x: pd.Series) -> dict:- """- Engle-Granger two-step cointegration test- H0: no cointegration relationship-- Args:- y, x: Two price series- Returns:- Test result- """- score, p_value, critical = coint(y, x)- return {- 'test_statistic': score,- 'p_value': p_value,- 'is_cointegrated': p_value < 0.05,- 'critical_values': {'1%': critical[0], '5%': critical[1], '10%': critical[2]},- }+from src.quantlib.timeseries import cointegration_test++result = cointegration_test(prices_a, prices_b, significance=0.05)+# {'test_statistic': -4.52, 'p_value': 0.002, 'is_cointegrated': True,+# 'critical_values': {'1%': -3.90, '5%': -3.34, '10%': -3.05}}```+Both legs must be individually non-stationary (check with `adf_test` first) — cointegration on two already-stationary series is meaningless.++Both legs must also share one index. Two same-length series on *different* indices raise `ValueError` rather than being zipped positionally, because a positional join of, say, an A-share calendar against a US one reports cointegration between days that never coexisted. Reindex or inner-join the two legs yourself before calling.+**Application in pair trading**:```python-import statsmodels.api as sm+from src.quantlib.timeseries import find_hedge_ratio, compute_half_life-def find_hedge_ratio(y: pd.Series, x: pd.Series) -> dict:- """- Compute hedge ratio: y = α + β×x + ε- Spread = y - β×x- """- x_const = sm.add_constant(x)- model = sm.OLS(y, x_const).fit()-- spread = y - model.params[1] * x-- return {- 'hedge_ratio': model.params[1],- 'intercept': model.params[0],- 'spread_mean': spread.mean(),- 'spread_std': spread.std(),- 'half_life': compute_half_life(spread), # mean-reversion speed- }--def compute_half_life(spread: pd.Series) -> float:- """Estimate half-life with OLS regression."""- spread_lag = spread.shift(1)- delta = spread - spread_lag- model = sm.OLS(delta.dropna(), sm.add_constant(spread_lag.dropna())).fit()- half_life = -np.log(2) / model.params[1]- return half_life+result = find_hedge_ratio(prices_a, prices_b)+# {'hedge_ratio': 2.49, 'intercept': 0.40,+# 'spread_mean': 0.40, 'spread_std': 1.73, 'half_life': 16.7}++spread = prices_a - result['hedge_ratio'] * prices_b+z_score = (spread - result['spread_mean']) / result['spread_std']++# half_life is in observation periods (days for daily bars) and is `inf`+# when the spread does not mean-revert. Sanity-check it before trading:+# a half-life longer than your holding horizon means the spread will not+# close in time, however good the cointegration p-value looks.+compute_half_life(spread)```+A perfectly flat leg (a name halted for the whole window) makes the regression+degenerate, so `find_hedge_ratio` and `compute_half_life` raise `ValueError`+rather than return a meaningless β. Treat that as "this pair has no usable data+in this window", not as something to work around.+**Pair-trading signal**:```@@ -133,17 +119,15 @@ z_score = (spread - mean) / std### 3. Granger Causality Test```python-from statsmodels.tsa.stattools import grangercausalitytests--def granger_test(data: pd.DataFrame, x_col: str, y_col: str, max_lag: int = 5):- """- Test whether x Granger-causes y (whether historical x helps predict y).- Note: Granger causality is not true causality, only predictive causality.- """- results = grangercausalitytests(data[[y_col, x_col]].dropna(), maxlag=max_lag)- return {lag: results[lag][0]['ssr_ftest'][1] for lag in range(1, max_lag+1)}+from src.quantlib.timeseries import granger_test++p_by_lag = granger_test(df, x_col='volume', y_col='return', max_lag=5)+# {1: 0.003, 2: 0.011, 3: 0.08, 4: 0.21, 5: 0.33}+# small p at lag k -> past x at that lag helps predict y```+Granger causality is **predictive, not structural**: it says past `x` improves the forecast of `y`, never that `x` causes `y`. A common confounder is that both respond to a third variable. Note also that testing 5 lags is 5 hypothesis tests — one small p-value among them is weak evidence.+## GARCH Volatility Modeling### GARCH(1,1) Model@@ -161,38 +145,22 @@ Parameter meanings:``````python-from arch import arch_model--def fit_garch(returns: pd.Series) -> dict:- """- Fit a GARCH(1,1) model.-- Args:- returns: Daily return series (in percentage form)- Returns:- Model parameters and forecasts- """- model = arch_model(returns * 100, vol='Garch', p=1, q=1,- mean='Constant', dist='normal')- result = model.fit(disp='off')-- # Forecast volatility for the next 5 days- forecast = result.forecast(horizon=5)-- return {- 'omega': result.params['omega'],- 'alpha': result.params['alpha[1]'],- 'beta': result.params['beta[1]'],- 'persistence': result.params['alpha[1]'] + result.params['beta[1]'],- 'long_run_vol': np.sqrt(result.params['omega'] /- (1 - result.params['alpha[1]'] - result.params['beta[1]'])) / 100,- 'current_vol': np.sqrt(result.conditional_volatility[-1]) / 100,- 'forecast_vol_5d': np.sqrt(forecast.variance.values[-1, :]) / 100,- 'aic': result.aic,- 'bic': result.bic,- }+from src.quantlib.timeseries import fit_garch++# `returns` are FRACTIONS (0.01 = 1%); the function rescales to percent itself.+result = fit_garch(returns, horizon=5)+# {'omega': 0.0453, 'alpha': 0.1213, 'beta': 0.8348, 'persistence': 0.9561,+# 'long_run_vol': 0.0102, 'current_vol': 0.0149,+# 'forecast_vol': array([0.0138, 0.0137, 0.0136, 0.0134, 0.0133]),+# 'horizon': 5, 'aic': 10882.39, 'bic': 10907.57}```+The forecast decays from `current_vol` toward `long_run_vol` — that mean reversion is the whole point of the model, and a forecast that does *not* decay signals `persistence` too close to 1.++All volatilities come back as **daily fractions** — multiply by `sqrt(252)` to annualise. `long_run_vol` is `nan` when `persistence >= 1`, which means the model has no finite unconditional variance and its long-horizon forecast is not usable.++Requires the optional `arch` package (`pip install "arch>=6.0"`); the call raises a named `ImportError` if it is absent.+### GARCH Variants| Model | Characteristics | Applicable Scenario |@@ -223,27 +191,17 @@ BTC:### 1. Heteroskedasticity Test```python-from statsmodels.stats.diagnostic import het_white, het_breuschpagan--def heteroscedasticity_test(model_result) -> dict:- """- Test whether residuals are heteroskedastic.- H0: homoskedasticity- """- # White test- white_stat, white_p, _, _ = het_white(model_result.resid, model_result.model.exog)-- # BP test- bp_stat, bp_p, _, _ = het_breuschpagan(model_result.resid, model_result.model.exog)-- return {- 'white_p': white_p,- 'bp_p': bp_p,- 'has_heteroscedasticity': white_p < 0.05 or bp_p < 0.05,- 'fix': 'Use HAC standard errors (Newey-West) or WLS' if white_p < 0.05 else 'No adjustment needed',- }+import statsmodels.api as sm+from src.quantlib.timeseries import heteroscedasticity_test++fitted = sm.OLS(y, sm.add_constant(X)).fit()+result = heteroscedasticity_test(fitted) # pass the FITTED result, not the data+# {'white_p': 0.0001, 'bp_p': 0.0003, 'has_heteroscedasticity': True,+# 'fix': 'Use HAC standard errors (Newey-West) or WLS'}```+`fix` tracks `has_heteroscedasticity`, and the verdict is `white_p < α` **or** `bp_p < α` — either test rejecting is enough to act on. The two disagree fairly often near the threshold (White has less power against a simple linear variance trend), so do not read "White says no" as the answer.+**Heteroskedasticity fixes**:- Use `model.fit(cov_type='HAC', cov_kwds={'maxlags': 5})`- Or use weighted least squares (WLS)@@ -252,49 +210,31 @@ def heteroscedasticity_test(model_result) -> dict:### 2. Autocorrelation Test```python-from statsmodels.stats.diagnostic import acorr_ljungbox-from statsmodels.stats.stattools import durbin_watson--def autocorrelation_test(residuals: pd.Series, lags: int = 10) -> dict:- """- Test whether residuals are autocorrelated.- H0: no autocorrelation- """- # DW test (first-order only)- dw = durbin_watson(residuals)-- # Ljung-Box test (multiple lags)- lb_result = acorr_ljungbox(residuals, lags=lags)-- return {- 'durbin_watson': dw,- 'dw_interpretation': 'positive autocorrelation' if dw < 1.5 else 'no autocorrelation' if dw < 2.5 else 'negative autocorrelation',- 'ljung_box_p': lb_result['lb_pvalue'].values,- 'has_autocorrelation': any(lb_result['lb_pvalue'] < 0.05),- 'fix': 'Use Newey-West standard errors or include lag terms',- }+from src.quantlib.timeseries import autocorrelation_test++result = autocorrelation_test(fitted.resid, lags=10)+# {'durbin_watson': 1.21, 'dw_interpretation': 'positive autocorrelation',+# 'ljung_box_p': array([0.001, 0.002, ...]), # one p-value per lag+# 'has_autocorrelation': True,+# 'fix': 'Use Newey-West standard errors or include lag terms'}```+⚠️ **`has_autocorrelation` is `any(p < significance)` across all `lags` — that is a family of tests, not one.** On pure white noise it fires about **13%** of the time at `lags=10` versus about **2%** at `lags=1` (measured over 120 seeds, n=1500). Treat a lone flag at high `lags` as a prompt to inspect `ljung_box_p` lag by lag, not as a 5%-level rejection.+### 3. Multicollinearity Test```python-from statsmodels.stats.outliers_influence import variance_inflation_factor--def vif_test(X: pd.DataFrame) -> pd.DataFrame:- """- VIF test for multicollinearity- VIF > 10 -> severe collinearity- VIF > 5 -> needs attention- """- vif_data = pd.DataFrame()- vif_data['feature'] = X.columns- vif_data['VIF'] = [variance_inflation_factor(X.values, i) for i in range(X.shape[1])]- vif_data['concern'] = vif_data['VIF'].apply(- lambda x: 'severe' if x > 10 else 'watch' if x > 5 else 'normal'- )- return vif_data+from src.quantlib.timeseries import vif_test++vif_test(factors, severe_threshold=10.0, watch_threshold=5.0)+# feature VIF concern+# 0 value 28.41 severe+# 1 momentum 1.12 normal+# 2 size 6.30 watch```+Include the constant column if your model has one — VIF is otherwise distorted by the un-centred means.+### Regression Diagnostics Checklist```@@ -311,40 +251,16 @@ def vif_test(X: pd.DataFrame) -> pd.DataFrame:### Nonparametric Bootstrap```python-def bootstrap_statistic(data: np.ndarray, statistic_func,- n_bootstrap: int = 10000,- confidence: float = 0.95) -> dict:- """- Estimate a confidence interval for a statistic with Bootstrap.-- Args:- data: Raw data- statistic_func: Statistic function (for example np.mean, np.median)- n_bootstrap: Number of Bootstrap resamples- confidence: Confidence level- Returns:- Point estimate and confidence interval- """- n = len(data)- bootstrap_stats = np.array([- statistic_func(np.random.choice(data, size=n, replace=True))- for _ in range(n_bootstrap)- ])-- alpha = 1 - confidence- lower = np.percentile(bootstrap_stats, alpha/2 * 100)- upper = np.percentile(bootstrap_stats, (1 - alpha/2) * 100)-- return {- 'point_estimate': statistic_func(data),- 'bootstrap_mean': np.mean(bootstrap_stats),- 'bootstrap_std': np.std(bootstrap_stats),- 'ci_lower': lower,- 'ci_upper': upper,- 'confidence': confidence,- }+from src.quantlib.timeseries import bootstrap_statistic++result = bootstrap_statistic(returns.values, np.median,+ n_bootstrap=10000, confidence=0.95, seed=42)+# {'point_estimate': 0.0004, 'bootstrap_mean': 0.0004, 'bootstrap_std': 0.0002,+# 'ci_lower': 0.0001, 'ci_upper': 0.0008, 'confidence': 0.95}```+Pass `seed` whenever the number goes into a report — an unseeded bootstrap gives a slightly different interval on every run, which makes results irreproducible. Needs no optional dependency (pure numpy).+### Bootstrap Applications in Quant| Scenario | Method | Purpose |@@ -355,16 +271,20 @@ def bootstrap_statistic(data: np.ndarray, statistic_func,| Strategy comparison | Paired Bootstrap | Whether strategy A is significantly better than B |```python-def bootstrap_sharpe(returns: pd.Series, n_bootstrap: int = 10000) -> dict:- """Bootstrap confidence interval for the Sharpe ratio."""- def sharpe(r):- return r.mean() / r.std() * np.sqrt(252) if r.std() > 0 else 0-- result = bootstrap_statistic(returns.values, sharpe, n_bootstrap)- result['is_significant'] = result['ci_lower'] > 0 # 95% CI excludes 0- return result+from src.quantlib.timeseries import bootstrap_sharpe++# Takes a RETURN series (fractions), not an equity curve.+result = bootstrap_sharpe(returns, n_bootstrap=10000,+ periods_per_year=252, seed=42)+# {'point_estimate': 1.25, 'ci_lower': 0.62, 'ci_upper': 1.88,+# 'bootstrap_mean': 1.26, 'bootstrap_std': 0.32,+# 'confidence': 0.95, 'is_significant': True}```+`is_significant` means the interval sits entirely above zero. Remember what it does **not** mean: the interval is centred on the *realised* Sharpe, so it quantifies sampling error around this sample, not whether the edge persists out of sample. With only 1000 daily bars the realised Sharpe of a zero-edge strategy already has a standard deviation of `sqrt(252/1000) ≈ 0.50`.++For a backtest **equity curve** use `backtest.validation.bootstrap_sharpe_ci` instead — it differences the curve itself and returns report-shaped keys. The two also use different denominators: `bootstrap_sharpe` divides by the sample standard deviation (`ddof=1`), `bootstrap_sharpe_ci` by the population one (`ddof=0`). On identical data they differ by `sqrt(n / (n-1))` — about 0.2% over a year of daily bars. Report one or the other, never both as if they agreed.+## Hypothesis-Testing Framework### Quick Reference for Common Testsdiff --git a/agent/src/skills/risk-analysis/SKILL.md b/agent/src/skills/risk-analysis/SKILL.mdindex f528f5a8a..98f0fd8cc 100644--- a/agent/src/skills/risk-analysis/SKILL.md+++ b/agent/src/skills/risk-analysis/SKILL.md@@ -10,6 +10,32 @@ category: analysisSystematic risk-measurement methodology covering VaR/CVaR calculation, Monte Carlo simulation, stress-test design, and tail-risk analysis. It provides risk evaluation for backtest results and risk-control constraints for asset allocation.+The measures below are implemented once, with tests, in `src/quantlib/risk.py`. Call them; do not retype the formulas, because a hand-retyped VaR is where the sign convention silently flips.++```python+from src.quantlib.risk import (+ historical_var, parametric_var, historical_cvar,+ max_drawdown_analysis, monte_carlo_gbm, analyze_mc_results, fit_gpd_tail,+)+```++### Sign convention++**A loss is a positive number**, uniformly, across every function in the module:++| Value | Reads as |+|------|------|+| `historical_var(...) == 0.028` | a 2.8% loss |+| `historical_cvar(...) == 0.042` | a 4.2% average loss in the tail |+| `max_drawdown_analysis(...)["max_drawdown"] == 0.325` | a 32.5% peak-to-trough decline |+| `analyze_mc_results(...)["var"] == 0.224` | a 22.4% loss |++Quantities that are *returns* rather than *losses* keep their natural sign and are named `*_return` (`mean_return`, `worst_5pct_return`, `best_5pct_return`), so a bad outcome there is negative. Report VaR to the user with the sign the user expects, but never re-derive it — flip it at the presentation layer only.++`cvar >= var` holds by construction whenever both come from the same sample at the same confidence level. If you ever compute a CVaR below its VaR, the tail mask is wrong.++This is *not* `cvar >= var >= 0`. The magnitudes are never clipped, so a sample whose tail contains no actual loss reports a **negative** loss — a gain. That is deliberate and informative; do not assert non-negativity on a VaR and do not clip it, or you destroy the distinction between "small loss" and "no loss at all".+## Risk Measurement Methods### 1. VaR (Value at Risk)@@ -24,133 +50,99 @@ Systematic risk-measurement methodology covering VaR/CVaR calculation, Monte Car| Parametric (normal) | `VaR = μ - z_α × σ` | Easy to compute | Assumes a normal distribution || Monte Carlo | Simulate N paths and take the quantile | Flexible | Computationally intensive |-#### Historical Simulation Implementation+#### Historical Simulation++Reads the loss straight off the sorted sample, so it inherits whatever fat tails the history actually had. `horizon` scales by the square-root-of-time rule, which is only valid under i.i.d. returns.```python-import numpy as np-import pandas as pd--def historical_var(returns: pd.Series, confidence: float = 0.95, horizon: int = 1) -> float:- """- Args:- returns: Daily return series- confidence: Confidence level, commonly 0.95 or 0.99- horizon: Holding period in days, default 1- Returns:- VaR value (positive means loss)- """- sorted_returns = returns.sort_values()- index = int((1 - confidence) * len(sorted_returns))- var_1d = -sorted_returns.iloc[index]- return var_1d * np.sqrt(horizon) # square-root-of-time rule+historical_var(returns, confidence=0.95) # 1-day 95% VaR+historical_var(returns, confidence=0.99, horizon=10) # 10-day 99% VaR```-#### Parametric Implementation+The quantile is a *non-interpolating lower order statistic*: element `floor((1 - confidence) * n)` of the ascending-sorted returns, negated. The result is therefore always a return that was actually observed, never a blend of two neighbours.++#### Parametric (normal)```python-from scipy.stats import norm--def parametric_var(returns: pd.Series, confidence: float = 0.95, horizon: int = 1) -> float:- mu = returns.mean()- sigma = returns.std()- z = norm.ppf(1 - confidence)- var_1d = -(mu + z * sigma)- return var_1d * np.sqrt(horizon)+parametric_var(returns, confidence=0.95)```+Fits `mu` and the sample `sigma` (ddof=1) and returns `-(mu + z*sigma)` with `z = norm.ppf(1 - confidence)`. Needs at least 2 observations.++**Do not assume the parametric figure is the lower one.** The direction of the gap depends on the confidence level. A fat tail inflates the fitted `sigma`, which pushes the normal quantile *outward* at moderate confidence, where the empirical quantile is still sitting in the well-behaved body. Measured over 300 t(4) samples of 750 daily returns:++| Confidence | Parametric reads **above** historical |+|---|---|+| 90% | 100% of samples |+| 95% | 92.7% |+| 97.5% | 40.3% |+| 99% | 5.3% |++So the familiar "parametric understates risk" result only appears at 99% and deeper. At the 95% default it is normally the *higher* of the two, and that is not a sign your code is wrong. Quote both at 99% when the point is to expose the tail.+### 2. CVaR / ES (Conditional VaR / Expected Shortfall)**Definition**: the average loss beyond the VaR threshold, more conservative than VaR.```python-def historical_cvar(returns: pd.Series, confidence: float = 0.95) -> float:- """CVaR = the mean of all losses beyond VaR."""- var = historical_var(returns, confidence)- tail_losses = returns[returns < -var]- return -tail_losses.mean() if len(tail_losses) > 0 else var+historical_cvar(returns, confidence=0.95)+historical_cvar(returns, confidence=0.99, horizon=10)```+Averages the VaR order statistic together with everything worse than it (inclusive), which is the standard expected shortfall and is what makes `cvar >= var` structural rather than incidental.+**VaR vs CVaR comparison**:| Metric | VaR(95%) | CVaR(95%) | Meaning ||------|----------|-----------|------|-| Typical value | -2.1% | -3.4% | CVaR is usually 1.3-1.8x VaR |+| Typical value | 2.1% | 3.4% | CVaR is usually 1.3-1.8x VaR || Subadditivity | Not satisfied | Satisfied | CVaR can be used for portfolio risk decomposition || Regulation | Basel II | Basel III | Regulatory trend is shifting toward CVaR |### 3. Maximum Drawdown Analysis```python-def max_drawdown_analysis(equity: pd.Series) -> dict:- """- Args:- equity: Net-value series- Returns:- dict: max_drawdown, peak_date, trough_date, recovery_date, duration- """- peak = equity.cummax()- drawdown = (equity - peak) / peak- max_dd = drawdown.min()- trough_idx = drawdown.idxmin()- peak_idx = equity[:trough_idx].idxmax()-- # Recovery date- recovery = equity[trough_idx:][equity[trough_idx:] >= equity[peak_idx]]- recovery_date = recovery.index[0] if len(recovery) > 0 else None-- return {- 'max_drawdown': max_dd,- 'peak_date': peak_idx,- 'trough_date': trough_idx,- 'recovery_date': recovery_date,- 'underwater_days': (trough_idx - peak_idx).days,- 'recovery_days': (recovery_date - trough_idx).days if recovery_date else None- }+dd = max_drawdown_analysis(equity) # equity = a strictly positive net-value Series+dd["max_drawdown"] # 0.325 -> fell 32.5% below its running peak (POSITIVE)+dd["peak_date"], dd["trough_date"], dd["recovery_date"]+dd["recovered"] # False when the series ends still underwater```+Full return keys: `max_drawdown`, `peak_date`, `trough_date`, `recovery_date`, `recovered`, `peak_to_trough_periods`, `trough_to_recovery_periods`, `underwater_days`, `recovery_days`.++- Recovery means reaching the **peak** value again, not merely bouncing off the trough; `recovery_date` is None and `recovered` is False if it never happens.+- `underwater_days` / `recovery_days` are calendar days and require a `DatetimeIndex`; on any other index they come back None and you should use the `*_periods` counts, which are always populated.+- Non-positive equity raises — a drawdown *ratio* is undefined at or below zero. Rebase a signed PnL series to a positive net value first.+### 4. Monte Carlo Simulation#### Geometric Brownian Motion (GBM)```python-def monte_carlo_gbm(S0: float, mu: float, sigma: float,- T: int = 252, n_paths: int = 10000) -> np.ndarray:- """- Args:- S0: Initial price- mu: Annualized return- sigma: Annualized volatility- T: Number of simulation days- n_paths: Number of paths- Returns:- Price matrix of shape (n_paths, T)- """- dt = 1 / 252- Z = np.random.standard_normal((n_paths, T))- log_returns = (mu - 0.5 * sigma**2) * dt + sigma * np.sqrt(dt) * Z- prices = S0 * np.exp(np.cumsum(log_returns, axis=1))- return prices+paths = monte_carlo_gbm(+ s0=100.0, mu=0.10, sigma=0.20, # mu/sigma are ANNUALISED+ n_steps=252, n_paths=10_000,+ seed=42, # keyword-only; required for a reproducible run+)+paths.shape # (10000, 253) -- n_steps + 1 columns+paths[:, 0] # exactly s0 on every path```+**Always pass `seed`.** It is keyword-only so it cannot be supplied by accident, and leaving it None draws fresh OS entropy — the run is then unreproducible and the numbers in your report cannot be regenerated. Use `steps_per_year` if the step is not a 252-day trading day.++Column 0 is the starting price, so `paths[:, -1] / paths[:, 0] - 1` is the total return over the whole simulation. Terminal expectation is `s0 * exp(mu * n_steps / steps_per_year)`; the *median* sits lower, at `s0 * exp((mu - 0.5*sigma**2) * T)`, and that gap is the volatility drag, not a bug.+#### Simulation Result Analysis```python-def analyze_mc_results(paths: np.ndarray, confidence: float = 0.95) -> dict:- final_prices = paths[:, -1]- returns = final_prices / paths[:, 0] - 1-- return {- 'mean_return': np.mean(returns),- 'median_return': np.median(returns),- 'std_return': np.std(returns),- 'var': -np.percentile(returns, (1 - confidence) * 100),- 'cvar': -np.mean(returns[returns < -np.percentile(returns, (1-confidence)*100)]),- 'prob_loss': np.mean(returns < 0),- 'worst_5pct': np.percentile(returns, 5),- 'best_5pct': np.percentile(returns, 95),- }+summary = analyze_mc_results(paths, confidence=0.95)+summary["var"], summary["cvar"] # positive loss magnitudes+summary["mean_return"], summary["prob_loss"]+summary["worst_5pct_return"], summary["best_5pct_return"] # signed returns```+`var` / `cvar` are computed with exactly the same order-statistic convention as `historical_var` / `historical_cvar`, so a simulated VaR and a historical VaR are directly comparable.+## Stress-Testing Framework### Historical Scenario Stress Tests@@ -210,30 +202,20 @@ STRESS_SCENARIOS = {### POT Method (Peaks Over Threshold)```python-from scipy.stats import genpareto--def fit_gpd_tail(returns: pd.Series, threshold_pct: float = 5.0) -> dict:- """- Fit the tail with a generalized Pareto distribution.- Args:- returns: Daily returns- threshold_pct: Threshold percentile (take the worst X%)- """- threshold = np.percentile(returns, threshold_pct)- exceedances = threshold - returns[returns < threshold] # make positive-- # Fit GPD- shape, loc, scale = genpareto.fit(exceedances)-- return {- 'threshold': threshold,- 'n_exceedances': len(exceedances),- 'shape_xi': shape, # ξ>0 fat tail, ξ=0 exponential tail, ξ<0 bounded tail- 'scale_sigma': scale,- 'tail_type': 'fat tail (dangerous)' if shape > 0 else 'thin tail (safer)',- }+fit = fit_gpd_tail(returns, threshold_pct=5.0) # keep the worst 5%+fit["shape_xi"] # ξ>0 fat tail, ξ=0 exponential tail, ξ<0 bounded tail+fit["shape_stderr"] # standard error of ξ -- quote ξ with it, never alone+fit["scale_sigma"] # in units of loss magnitude+fit["tail_type"] # "fat" | "exponential" | "bounded"+fit["threshold"], fit["n_exceedances"], fit["exceedance_rate"]```+Exceedances are non-negative by construction (`threshold - return`, kept only where the return fell below the threshold), so the GPD location is pinned at zero. Letting `loc` float instead lets the optimiser absorb tail mass into a shifted origin and biases `shape_xi`.++**`tail_type` is decided against `shape_stderr`, not against exact zero.** A fitted `shape_xi` is a float and is never exactly `0.0`, so a bare `ξ > 0` test would call a genuinely exponential tail "fat" purely on the sign of estimation noise. `"fat"` therefore means `ξ > 2 × shape_stderr`, `"bounded"` means `ξ < -2 × shape_stderr`, and anything in between is `"exponential"` — indistinguishable from zero at this sample size. Measured over 200 refits, that 2σ band labels a truly exponential tail `"exponential"` 96.5% of the time while still catching `ξ = +0.40` and `ξ = -0.35` 100% of the time. A `shape_xi` of 0.03 with a `shape_stderr` of 0.02 is not evidence of a fat tail; get more exceedances before you call it one.++Threshold choice is the real judgement call: too high and there is nothing left to fit (fewer than 2 exceedances raises), too low and the EVT limit theorem no longer applies, so the fitted shape stops meaning anything. Check that `shape_xi` is stable across a few nearby `threshold_pct` values before quoting it.+### Tail-Risk Metrics| Metric | Calculation | Meaning |@@ -269,6 +251,8 @@ Optional:## Output Format+Note the sign flip: the module returns losses as positive numbers, while the report below prints them the way a reader expects to see them (`max_drawdown 0.325` → `-32.5%`). Flip once, here at the presentation layer, and never inside a calculation.+```markdown## Risk Analysis Report@@ -306,9 +290,10 @@ Optional:## Notes1. **VaR is not the maximum loss**: VaR only says "with 95% probability, losses will not exceed X"; the remaining 5% can be far worse-2. **Normality assumption is dangerous**: financial returns are almost always fat-tailed, so parametric VaR underestimates risk+2. **Normality assumption is dangerous**: financial returns are almost always fat-tailed, so parametric VaR underestimates risk **deep in the tail (99% and beyond)**. At 90–95% it usually reads *higher* than the historical figure, because the fat tail inflates the fitted sigma — see the table under "Parametric (normal)". Never cite a 95% parametric VaR as evidence that the normal fit is conservative3. **History does not equal the future**: historical simulation fails when structural breaks occur (for example, the first negative oil price)4. **Correlation is unstable**: correlation matrices observed in normal markets can collapse in crises (correlations trend toward 1)-5. **Monte Carlo seed**: set a random seed for reproducibility, and use at least 10,000 paths for stability+5. **Monte Carlo seed**: always pass `seed=` to `monte_carlo_gbm` and quote it in the report, so the numbers can be regenerated; use at least 10,000 paths for stability6. **Holding-period scaling**: the square-root-of-time rule only applies under i.i.d. returns; it becomes inaccurate under autocorrelation7. **Risk in backtests**: `metrics.csv` already includes `max_drawdown` and `sharpe`; this skill provides deeper analysis+8. **Sign discipline**: every measure here returns a loss as a positive number. Do not re-derive a measure inline to "get the sign you want" — call the function and flip once when printingdiff --git a/agent/src/tools/options_pricing_tool.py b/agent/src/tools/options_pricing_tool.pyindex 0dbc128b9..e8e8779c6 100644--- a/agent/src/tools/options_pricing_tool.py+++ b/agent/src/tools/options_pricing_tool.py@@ -6,10 +6,8 @@ import jsonimport mathfrom typing import Any-import numpy as np-from scipy.stats import norm-from src.agent.tools import BaseTool+from src.quantlib.options import bs_greeks, bs_pricedef _validate_inputs(@@ -52,6 +50,10 @@ def _bs_price_and_greeks() -> dict:"""Compute Black-Scholes price and Greeks.+ Thin adapter over :mod:`src.quantlib.options`, which owns the one+ implementation of this formula in the repo. This function's only jobs are+ to merge price and Greeks into a single dict and to round for display.+Args:spot: Current underlying price.strike: Strike price.@@ -61,46 +63,14 @@ def _bs_price_and_greeks(option_type: "call" or "put".Returns:- Dict containing price, delta, gamma, theta, vega.+ Dict containing price, delta, gamma, theta, vega and rho, each rounded+ to six decimal places."""- if T <= 0 or sigma <= 0:- if option_type == "call":- price = max(spot - strike, 0.0)- delta = 1.0 if spot > strike else 0.0- else:- price = max(strike - spot, 0.0)- delta = -1.0 if spot < strike else 0.0- return {"price": price, "delta": delta, "gamma": 0.0, "theta": 0.0, "vega": 0.0}-- sqrt_T = np.sqrt(T)- d1 = (np.log(spot / strike) + (r + sigma**2 / 2) * T) / (sigma * sqrt_T)- d2 = d1 - sigma * sqrt_T- nd1_pdf = float(norm.pdf(d1))-- if option_type == "call":- price = float(spot * norm.cdf(d1) - strike * np.exp(-r * T) * norm.cdf(d2))- delta = float(norm.cdf(d1))- else:- price = float(strike * np.exp(-r * T) * norm.cdf(-d2) - spot * norm.cdf(-d1))- delta = float(norm.cdf(d1) - 1.0)-- gamma = float(nd1_pdf / (spot * sigma * sqrt_T))-- theta_common = -(spot * nd1_pdf * sigma) / (2 * sqrt_T)- if option_type == "call":- theta = theta_common - r * strike * np.exp(-r * T) * norm.cdf(d2)- else:- theta = theta_common + r * strike * np.exp(-r * T) * norm.cdf(-d2)- theta = float(theta / 365.0)-- vega = float(spot * nd1_pdf * sqrt_T / 100.0)-+ price = bs_price(spot, strike, T, r, sigma, option_type)+ greeks = bs_greeks(spot, strike, T, r, sigma, option_type)return {"price": round(price, 6),- "delta": round(delta, 6),- "gamma": round(gamma, 6),- "theta": round(theta, 6),- "vega": round(vega, 6),+ **{name: round(value, 6) for name, value in greeks.items()},}diff --git a/agent/tests/quantlib/__init__.py b/agent/tests/quantlib/__init__.pynew file mode 100644index 000000000..04c2840da--- /dev/null+++ b/agent/tests/quantlib/__init__.py@@ -0,0 +1 @@+"""Tests for the quantlib financial-mathematics primitives."""diff --git a/agent/tests/quantlib/test_attribution.py b/agent/tests/quantlib/test_attribution.pynew file mode 100644index 000000000..7ce9821f0--- /dev/null+++ b/agent/tests/quantlib/test_attribution.py@@ -0,0 +1,346 @@+"""Tests for Brinson-Fachler attribution and Carino multi-period linking.++The four-sector fixture below is worked out by hand in the test itself: every+expected effect is written as the literal arithmetic from the model definition, so+a regression in the implementation cannot be absorbed by reusing the+implementation's own reasoning.+"""++from __future__ import annotations++import math++import pytest++from src.quantlib.attribution import (+ BrinsonResult,+ brinson_fachler,+ carino_factor,+ carino_link,+)++# Hand-built four-sector period.+# R_p = .40*.12 + .10*.04 + .30*-.02 + .20*.07 = .048 + .004 - .006 + .014 = 0.060+# R_b = .25*.10 + .30*.05 + .25*-.01 + .20*.06 = .025 + .015 - .0025 + .012 = 0.0495+# active = 0.0105+PORTFOLIO_WEIGHTS = {"Tech": 0.40, "Financials": 0.10, "Energy": 0.30, "Health": 0.20}+BENCHMARK_WEIGHTS = {"Tech": 0.25, "Financials": 0.30, "Energy": 0.25, "Health": 0.20}+PORTFOLIO_RETURNS = {"Tech": 0.12, "Financials": 0.04, "Energy": -0.02, "Health": 0.07}+BENCHMARK_RETURNS = {"Tech": 0.10, "Financials": 0.05, "Energy": -0.01, "Health": 0.06}++EXACT = 1e-12+++def _fixture() -> BrinsonResult:+ """Return the hand-built four-sector single-period attribution.++ Returns:+ The :class:`BrinsonResult` for the module-level fixture.+ """+ return brinson_fachler(PORTFOLIO_WEIGHTS, BENCHMARK_WEIGHTS, PORTFOLIO_RETURNS, BENCHMARK_RETURNS)+++def test_totals_match_hand_computed_returns():+ """Portfolio, benchmark and active returns match the arithmetic above."""+ result = _fixture()+ assert result.portfolio_return == pytest.approx(0.060, abs=EXACT)+ assert result.benchmark_return == pytest.approx(0.0495, abs=EXACT)+ assert result.active_return == pytest.approx(0.0105, abs=EXACT)+++def test_per_sector_effects_match_hand_computation():+ """Every sector's three effects equal the hand-evaluated formulas."""+ result = _fixture()+ by_sector = {effect.sector: effect for effect in result.sectors}+ benchmark_total = 0.0495++ expected = {+ # (w_p - w_b), (r_b - R_b), (r_p - r_b), w_b+ "Tech": (0.40 - 0.25, 0.10 - benchmark_total, 0.12 - 0.10, 0.25),+ "Financials": (0.10 - 0.30, 0.05 - benchmark_total, 0.04 - 0.05, 0.30),+ "Energy": (0.30 - 0.25, -0.01 - benchmark_total, -0.02 - -0.01, 0.25),+ "Health": (0.20 - 0.20, 0.06 - benchmark_total, 0.07 - 0.06, 0.20),+ }+ for sector, (active_weight, benchmark_excess, selection_excess, w_b) in expected.items():+ effect = by_sector[sector]+ assert effect.allocation == pytest.approx(active_weight * benchmark_excess, abs=EXACT)+ assert effect.selection == pytest.approx(w_b * selection_excess, abs=EXACT)+ assert effect.interaction == pytest.approx(active_weight * selection_excess, abs=EXACT)+++def test_aggregate_effects_match_hand_computation():+ """The three aggregate effects equal the independently summed values."""+ result = _fixture()+ # Allocation: .15*.0505 + -.20*.0005 + .05*-.0595 + 0 = .007575 - .0001 - .002975 = 0.0045+ assert result.allocation == pytest.approx(0.0045, abs=EXACT)+ # Selection: .25*.02 + .30*-.01 + .25*-.01 + .20*.01 = .005 - .003 - .0025 + .002 = 0.0015+ assert result.selection == pytest.approx(0.0015, abs=EXACT)+ # Interaction: .15*.02 + -.20*-.01 + .05*-.01 + 0 = .003 + .002 - .0005 = 0.0045+ assert result.interaction == pytest.approx(0.0045, abs=EXACT)+++def test_single_period_effects_tie_out_exactly():+ """HARD REQUIREMENT: allocation + selection + interaction == active return to 1e-12."""+ result = _fixture()+ residual = result.allocation + result.selection + result.interaction - result.active_return+ assert abs(residual) < EXACT, f"attribution does not tie out; residual={residual!r}"+ assert abs(result.total_effect - result.active_return) < EXACT+++def test_sector_totals_tie_out_exactly():+ """Summing the per-sector totals also reproduces the active return."""+ result = _fixture()+ summed = math.fsum(effect.total for effect in result.sectors)+ assert abs(summed - result.active_return) < EXACT+++ "w_p,w_b,r_p,r_b",+ [+ # Ordinary long-only book.+ (+ {"A": 0.5, "B": 0.3, "C": 0.2},+ {"A": 0.2, "B": 0.5, "C": 0.3},+ {"A": 0.11, "B": -0.04, "C": 0.07},+ {"A": 0.08, "B": 0.01, "C": 0.05},+ ),+ # Single sector: allocation and interaction must vanish, selection carries it.+ ({"A": 1.0}, {"A": 1.0}, {"A": 0.25}, {"A": 0.10}),+ # A short leg, so weights are not confined to [0, 1].+ (+ {"A": 0.7, "B": -0.2, "C": 0.5},+ {"A": 0.3, "B": 0.4, "C": 0.3},+ {"A": 0.03, "B": 0.09, "C": -0.15},+ {"A": 0.06, "B": 0.02, "C": -0.11},+ ),+ # Large negative returns, to exercise sign handling.+ (+ {"A": 0.6, "B": 0.4},+ {"A": 0.45, "B": 0.55},+ {"A": -0.30, "B": -0.12},+ {"A": -0.22, "B": -0.19},+ ),+ ],+)+def test_tie_out_holds_for_arbitrary_inputs(w_p, w_b, r_p, r_b):+ """The identity is structural: it holds for any weights that sum alike, shorts included."""+ result = brinson_fachler(w_p, w_b, r_p, r_b)+ assert abs(result.total_effect - result.active_return) < EXACT+++def test_portfolio_identical_to_benchmark_produces_zero_effects():+ """A portfolio equal to the benchmark earns zero allocation, selection and interaction."""+ result = brinson_fachler(+ BENCHMARK_WEIGHTS,+ BENCHMARK_WEIGHTS,+ BENCHMARK_RETURNS,+ BENCHMARK_RETURNS,+ )+ assert result.active_return == pytest.approx(0.0, abs=EXACT)+ assert result.allocation == pytest.approx(0.0, abs=EXACT)+ assert result.selection == pytest.approx(0.0, abs=EXACT)+ assert result.interaction == pytest.approx(0.0, abs=EXACT)+ for effect in result.sectors:+ assert effect.allocation == pytest.approx(0.0, abs=EXACT)+ assert effect.selection == pytest.approx(0.0, abs=EXACT)+ assert effect.interaction == pytest.approx(0.0, abs=EXACT)+++def test_same_weights_isolates_selection():+ """Matching the benchmark weights leaves allocation and interaction at zero."""+ result = brinson_fachler(BENCHMARK_WEIGHTS, BENCHMARK_WEIGHTS, PORTFOLIO_RETURNS, BENCHMARK_RETURNS)+ assert result.allocation == pytest.approx(0.0, abs=EXACT)+ assert result.interaction == pytest.approx(0.0, abs=EXACT)+ assert result.selection == pytest.approx(result.active_return, abs=EXACT)+++def test_same_returns_isolates_allocation():+ """Holding benchmark returns leaves selection and interaction at zero."""+ result = brinson_fachler(PORTFOLIO_WEIGHTS, BENCHMARK_WEIGHTS, BENCHMARK_RETURNS, BENCHMARK_RETURNS)+ assert result.selection == pytest.approx(0.0, abs=EXACT)+ assert result.interaction == pytest.approx(0.0, abs=EXACT)+ assert result.allocation == pytest.approx(result.active_return, abs=EXACT)+++def test_mismatched_weight_sums_are_rejected():+ """Unequal weight totals break the identity, so they must raise rather than mislead."""+ with pytest.raises(ValueError, match="same total"):+ brinson_fachler({"A": 0.9}, {"A": 1.0}, {"A": 0.05}, {"A": 0.04})+++def test_weight_sum_tolerance_is_the_boundary_it_claims_to_be():+ """The tolerance gates on the weight-sum gap, strictly, in both directions."""+ args = ({"A": 0.5, "B": 0.5}, {"A": 0.5, "B": 0.4999}, {"A": 0.08, "B": 0.02}, {"A": 0.06, "B": 0.03})+ inside = brinson_fachler(*args, weight_sum_tolerance=1e-3)+ assert abs(inside.total_effect - inside.active_return) < 1e-4+ with pytest.raises(ValueError, match="same total"):+ brinson_fachler(*args, weight_sum_tolerance=1e-5)+++def test_loosened_tolerance_leaks_exactly_the_documented_residual():+ """A weight-sum gap dW leaves a residual of -R_b * dW, as the docstring states.++ This is the cost of relaxing the precondition, and it is a real number in basis+ points rather than machine noise, so it is pinned rather than left to be+ rediscovered by whoever loosens the tolerance next.+ """+ portfolio = {"A": 0.6, "B": 0.4}+ benchmark = {"A": 0.5, "B": 0.49}+ result = brinson_fachler(+ portfolio,+ benchmark,+ {"A": 0.08, "B": 0.02},+ {"A": 0.06, "B": 0.03},+ weight_sum_tolerance=0.02,+ )+ weight_gap = math.fsum(portfolio.values()) - math.fsum(benchmark.values())+ residual = result.total_effect - result.active_return+ assert residual == pytest.approx(-result.benchmark_return * weight_gap, abs=EXACT)+ # ~4.5bp: large enough to corrupt a report, which is why the default is 1e-9.+ assert abs(residual) > 1e-4+++def test_missing_return_for_a_held_sector_is_rejected():+ """A sector held with real weight must supply its return."""+ with pytest.raises(ValueError, match="no portfolio return"):+ brinson_fachler({"A": 0.5, "B": 0.5}, {"A": 0.5, "B": 0.5}, {"A": 0.05}, {"A": 0.04, "B": 0.02})+++def test_benchmark_only_sector_charges_allocation_and_still_ties_out():+ """Not owning a benchmark sector is pure allocation, and the total still ties out."""+ result = brinson_fachler(+ {"A": 1.0, "B": 0.0},+ {"A": 0.6, "B": 0.4},+ {"A": 0.10},+ {"A": 0.10, "B": -0.05},+ )+ missed = next(effect for effect in result.sectors if effect.sector == "B")+ assert missed.selection == pytest.approx(0.0, abs=EXACT)+ assert missed.interaction == pytest.approx(0.0, abs=EXACT)+ assert missed.allocation != 0.0+ assert abs(result.total_effect - result.active_return) < EXACT+++def test_empty_input_is_rejected():+ """An attribution over no sectors is meaningless."""+ with pytest.raises(ValueError, match="at least one sector"):+ brinson_fachler({}, {}, {}, {})+++# --------------------------------------------------------------------------+# Carino multi-period linking+# --------------------------------------------------------------------------+++def _three_periods() -> list[BrinsonResult]:+ """Return three single-period attributions with deliberately different signs.++ Returns:+ Three :class:`BrinsonResult` objects in chronological order.+ """+ return [+ _fixture(),+ brinson_fachler(+ {"Tech": 0.20, "Financials": 0.35, "Energy": 0.25, "Health": 0.20},+ BENCHMARK_WEIGHTS,+ {"Tech": -0.06, "Financials": 0.02, "Energy": 0.09, "Health": -0.03},+ {"Tech": -0.04, "Financials": 0.03, "Energy": 0.05, "Health": -0.02},+ ),+ brinson_fachler(+ {"Tech": 0.30, "Financials": 0.20, "Energy": 0.15, "Health": 0.35},+ BENCHMARK_WEIGHTS,+ {"Tech": 0.05, "Financials": -0.01, "Energy": 0.04, "Health": 0.08},+ {"Tech": 0.06, "Financials": 0.01, "Energy": 0.02, "Health": 0.05},+ ),+ ]+++def test_carino_factor_limit_when_returns_coincide():+ """With equal returns the factor collapses to its analytic limit 1/(1+R)."""+ assert carino_factor(0.07, 0.07) == pytest.approx(1.0 / 1.07, abs=EXACT)+++def test_carino_factor_is_continuous_at_the_limit():+ """The closed form and the limit agree as the two returns converge."""+ near = carino_factor(0.07 + 1e-7, 0.07)+ assert near == pytest.approx(1.0 / 1.07, abs=1e-7)+++def test_carino_factor_matches_its_definition():+ """Away from the limit the factor is the plain difference of logarithms."""+ expected = (math.log(1.10) - math.log(1.04)) / (0.10 - 0.04)+ assert carino_factor(0.10, 0.04) == pytest.approx(expected, abs=EXACT)+++def test_carino_factor_rejects_total_loss():+ """Returns at or below -100% have no logarithm."""+ with pytest.raises(ValueError, match="above -100%"):+ carino_factor(-1.0, 0.02)+++def test_linked_returns_compound():+ """Linked totals are the compounded, not summed, period returns."""+ periods = _three_periods()+ linked = carino_link(periods)+ expected_portfolio = math.prod(1.0 + period.portfolio_return for period in periods) - 1.0+ expected_benchmark = math.prod(1.0 + period.benchmark_return for period in periods) - 1.0+ assert linked.portfolio_return == pytest.approx(expected_portfolio, abs=EXACT)+ assert linked.benchmark_return == pytest.approx(expected_benchmark, abs=EXACT)+ assert linked.active_return == pytest.approx(expected_portfolio - expected_benchmark, abs=EXACT)+++def test_linked_effects_sum_to_multi_period_active_return():+ """The headline requirement: linked effects tie out to the compounded active return."""+ linked = carino_link(_three_periods())+ residual = linked.allocation + linked.selection + linked.interaction - linked.active_return+ assert abs(residual) < EXACT, f"linked attribution does not tie out; residual={residual!r}"+++def test_linked_sector_totals_tie_out():+ """Summing the linked per-sector totals also reproduces the compounded active return."""+ linked = carino_link(_three_periods())+ summed = math.fsum(sector.total for sector in linked.sectors)+ assert abs(summed - linked.active_return) < EXACT+++def test_naive_summation_leaves_a_residual_that_carino_removes():+ """Carino is not cosmetic: plain addition genuinely misses the compounded target."""+ periods = _three_periods()+ linked = carino_link(periods)+ naive = math.fsum(period.active_return for period in periods)+ assert abs(naive - linked.active_return) > EXACT+ assert abs(linked.total_effect - linked.active_return) < EXACT+++def test_single_period_link_is_the_identity():+ """Linking one period must not disturb its effects."""+ period = _fixture()+ linked = carino_link([period])+ assert linked.scaling_factors == pytest.approx((1.0,), abs=EXACT)+ assert linked.allocation == pytest.approx(period.allocation, abs=EXACT)+ assert linked.selection == pytest.approx(period.selection, abs=EXACT)+ assert linked.interaction == pytest.approx(period.interaction, abs=EXACT)+++def test_linking_identical_portfolio_and_benchmark_yields_zero():+ """Zero active return in every period links to zero overall."""+ flat = brinson_fachler(BENCHMARK_WEIGHTS, BENCHMARK_WEIGHTS, BENCHMARK_RETURNS, BENCHMARK_RETURNS)+ linked = carino_link([flat, flat, flat])+ assert linked.active_return == pytest.approx(0.0, abs=EXACT)+ assert linked.allocation == pytest.approx(0.0, abs=EXACT)+ assert linked.selection == pytest.approx(0.0, abs=EXACT)+ assert linked.interaction == pytest.approx(0.0, abs=EXACT)+++def test_link_reports_one_scaling_factor_per_period():+ """Scaling factors are exposed so a report can be audited."""+ periods = _three_periods()+ linked = carino_link(periods)+ assert len(linked.scaling_factors) == len(periods)+ assert all(factor > 0.0 for factor in linked.scaling_factors)+++def test_empty_period_list_is_rejected():+ """Linking nothing is an error, not an empty result."""+ with pytest.raises(ValueError, match="at least one period"):+ carino_link([])diff --git a/agent/tests/quantlib/test_credit.py b/agent/tests/quantlib/test_credit.pynew file mode 100644index 000000000..91bc92dc1--- /dev/null+++ b/agent/tests/quantlib/test_credit.py@@ -0,0 +1,498 @@+"""Tests for src.quantlib.credit.++Note on the Altman references: what is pinned here are the *published+coefficients and cut-offs* of the three variants (Altman 1968 Z, Z' for private+firms, Z'' for non-manufacturers), with the arithmetic of each term written out+term by term so the expected value is derivable by eye rather than copied from+the implementation. No firm-level worked example is asserted, because none was+available from a source that could be checked here.+"""++import math++import numpy as np+import pandas as pd+import pytest+from scipy.stats import norm++from src.quantlib.credit import (+ ALTMAN_MODELS,+ ZONE_LABELS_ZH,+ AltmanZScore,+ altman_z_score,+ credit_spread_analysis,+ distance_to_default,+ edf_reference_band,+ kmv_default_point,+ kmv_distance_to_default,+ merton_asset_solve,+ merton_model,+ spread_term_structure,+)++# One balance sheet, reused so the three variants can be compared like for like.+FIRM = dict(+ working_capital=200.0, # X1 = 0.20+ retained_earnings=300.0, # X2 = 0.30+ ebit=150.0, # X3 = 0.15+ equity_value=900.0, # X4 = 1.50+ total_liabilities=600.0,+ total_assets=1000.0,+ revenue=1200.0, # X5 = 1.20+)+++# --------------------------------------------------------------------------+# Altman Z-Score -- all three published variants+# --------------------------------------------------------------------------+++def test_original_variant_uses_the_1968_coefficients():+ result = altman_z_score(**FIRM, model="original")+ expected = (+ 1.2 * 0.20 + 1.4 * 0.30 + 3.3 * 0.15 + 0.6 * 1.50 + 1.0 * 1.20+ ) # 0.24 + 0.42 + 0.495 + 0.90 + 1.20 = 3.255+ assert expected == pytest.approx(3.255)+ assert result.z_score == pytest.approx(expected)+ assert (result.safe_threshold, result.distress_threshold) == (2.99, 1.81)+ assert result.zone == "safe"+ assert result.label_zh == ZONE_LABELS_ZH["safe"]+++def test_prime_variant_uses_the_private_firm_coefficients():+ result = altman_z_score(**FIRM, model="prime")+ expected = (+ 0.717 * 0.20 + 0.847 * 0.30 + 3.107 * 0.15 + 0.420 * 1.50 + 0.998 * 1.20+ ) # 0.1434 + 0.2541 + 0.46605 + 0.63 + 1.1976 = 2.69115+ assert expected == pytest.approx(2.69115)+ assert result.z_score == pytest.approx(expected)+ assert (result.safe_threshold, result.distress_threshold) == (2.90, 1.23)+ # 1.23 < 2.69115 < 2.90 -- the same firm that is safe on Z sits in Z''s grey+ # zone, which is the whole point of recalibrating for private firms.+ assert result.zone == "grey"+++def test_double_prime_variant_drops_x5_entirely():+ result = altman_z_score(+ **{k: v for k, v in FIRM.items() if k != "revenue"}, model="double_prime"+ )+ expected = 6.56 * 0.20 + 3.26 * 0.30 + 6.72 * 0.15 + 1.05 * 1.50+ # 1.312 + 0.978 + 1.008 + 1.575 = 4.873+ assert expected == pytest.approx(4.873)+ assert result.z_score == pytest.approx(expected)+ assert (result.safe_threshold, result.distress_threshold) == (2.60, 1.10)+ assert result.zone == "safe"+ assert result.components["x5"] is None+++def test_double_prime_ignores_revenue_even_when_supplied():+ with_revenue = altman_z_score(**FIRM, model="double_prime")+ without = altman_z_score(+ **{k: v for k, v in FIRM.items() if k != "revenue"}, model="double_prime"+ )+ assert with_revenue.z_score == pytest.approx(without.z_score)+++def test_components_are_the_five_ratios():+ result = altman_z_score(**FIRM, model="original")+ assert result.components == pytest.approx(+ {"x1": 0.20, "x2": 0.30, "x3": 0.15, "x4": 1.50, "x5": 1.20}+ )++[email protected]("model", list(ALTMAN_MODELS))+def test_zone_boundaries_follow_the_published_cutoffs(model):+ spec = ALTMAN_MODELS[model]+ # X4 is the only ratio in every variant, so drive the score through it alone.+ weight = spec.coefficients[3]+ assets = 1000.0+ liabilities = 600.0++ def score_at(target_z):+ equity = target_z / weight * liabilities+ return altman_z_score(+ working_capital=0.0,+ retained_earnings=0.0,+ ebit=0.0,+ equity_value=equity,+ total_liabilities=liabilities,+ total_assets=assets,+ revenue=0.0,+ model=model,+ )++ # The cut-offs are published to two decimals; these nudges locate them to+ # 1e-6. Landing exactly on a threshold is not asserted, because building a+ # score that is bitwise equal to it is not achievable in floating point.+ nudge = 1e-6+ assert score_at(spec.safe_threshold + nudge).zone == "safe"+ assert score_at(spec.safe_threshold - nudge).zone == "grey"+ assert score_at(spec.distress_threshold + nudge).zone == "grey"+ assert score_at(spec.distress_threshold - nudge).zone == "distress"+ mid = (spec.safe_threshold + spec.distress_threshold) / 2+ assert score_at(mid).zone == "grey"+ assert score_at(mid).label_zh == ZONE_LABELS_ZH["grey"]+++def test_result_is_frozen():+ result = altman_z_score(**FIRM)+ assert isinstance(result, AltmanZScore)+ with pytest.raises(Exception):+ result.z_score = 0.0 # type: ignore[misc]+++def test_altman_rejects_an_unknown_model():+ with pytest.raises(ValueError, match="unknown model"):+ altman_z_score(**FIRM, model="z_triple_prime")+++def test_altman_rejects_zero_denominators():+ with pytest.raises(ValueError, match="total_assets"):+ altman_z_score(**{**FIRM, "total_assets": 0.0})+ with pytest.raises(ValueError, match="total_liabilities"):+ altman_z_score(**{**FIRM, "total_liabilities": 0.0})+++def test_altman_requires_revenue_for_the_variants_that_use_x5():+ for model in ("original", "prime"):+ with pytest.raises(ValueError, match="needs revenue"):+ altman_z_score(+ **{k: v for k, v in FIRM.items() if k != "revenue"}, model=model+ )+++# --------------------------------------------------------------------------+# Merton / KMV+# --------------------------------------------------------------------------++BASE_MERTON = dict(+ equity_value=100.0, equity_vol=0.40, debt_face=100.0, risk_free=0.03, horizon=1.0+)+++def test_asset_solve_satisfies_both_equations_it_was_solving():+ equity, vol, debt, rate, horizon = 100.0, 0.40, 100.0, 0.03, 1.0+ asset_value, asset_vol = merton_asset_solve(equity, vol, debt, rate, horizon)++ d1 = (+ math.log(asset_value / debt) + (rate + 0.5 * asset_vol**2) * horizon+ ) / (asset_vol * math.sqrt(horizon))+ d2 = d1 - asset_vol * math.sqrt(horizon)++ call = asset_value * norm.cdf(d1) - debt * math.exp(-rate * horizon) * norm.cdf(d2)+ assert call == pytest.approx(equity, rel=1e-9)+ assert norm.cdf(d1) * asset_vol * asset_value == pytest.approx(+ vol * equity, rel=1e-9+ )++[email protected]("equity,equity_vol,debt,rate,horizon", [+ # Thin-equity, low-asset-vol issuers: the implied sigma_V lands near 1e-3 or+ # below, which is where a step-tolerance-limited root finder stops early.+ (0.5, 2.00, 500.0, 0.03, 0.25),+ (2.0, 0.80, 1000.0, 0.02, 5.00),+ (1.0, 0.25, 1000.0, 0.00, 5.00),+ (1.0, 0.10, 10000.0, 0.00, 10.00),+ (1.0, 1.50, 10000.0, 0.03, 10.00),+])+def test_asset_solve_converges_for_thin_equity_high_leverage_issuers(+ equity, equity_vol, debt, rate, horizon+):+ # These solve cleanly -- the root exists and is reachable -- so refusing them+ # would silently blank out the distressed end of the book, which is the end+ # Merton is actually used on.+ asset_value, asset_vol = merton_asset_solve(+ equity, equity_vol, debt, rate, horizon+ )+ d1 = (math.log(asset_value / debt) + (rate + 0.5 * asset_vol**2) * horizon) / (+ asset_vol * math.sqrt(horizon)+ )+ d2 = d1 - asset_vol * math.sqrt(horizon)+ call = asset_value * norm.cdf(d1) - debt * math.exp(-rate * horizon) * norm.cdf(d2)+ assert call == pytest.approx(equity, rel=1e-8)+ assert norm.cdf(d1) * asset_vol * asset_value == pytest.approx(+ equity_vol * equity, rel=1e-8+ )+ assert asset_value > equity+ assert 0.0 < asset_vol < equity_vol+++def test_asset_value_exceeds_equity_and_asset_vol_is_below_equity_vol():+ result = merton_model(**BASE_MERTON)+ assert result.asset_value > BASE_MERTON["equity_value"]+ assert 0.0 < result.asset_vol < BASE_MERTON["equity_vol"]+++def test_asset_solve_rejects_non_positive_inputs():+ for bad in ("equity_value", "equity_vol", "debt_face", "horizon"):+ with pytest.raises(ValueError, match="must all be positive"):+ merton_asset_solve(**{**BASE_MERTON, bad: 0.0})+++def test_distance_to_default_falls_monotonically_as_leverage_rises():+ dds = [+ merton_model(**{**BASE_MERTON, "debt_face": face}).distance_to_default+ for face in (40.0, 60.0, 80.0, 100.0, 140.0, 200.0, 300.0)+ ]+ assert all(later < earlier for earlier, later in zip(dds, dds[1:])), dds+++def test_distance_to_default_falls_monotonically_as_volatility_rises():+ dds = [+ merton_model(**{**BASE_MERTON, "equity_vol": vol}).distance_to_default+ for vol in (0.10, 0.20, 0.30, 0.45, 0.60, 0.80, 1.20)+ ]+ assert all(later < earlier for earlier, later in zip(dds, dds[1:])), dds+++def test_default_probability_and_spread_rise_with_leverage():+ low = merton_model(**{**BASE_MERTON, "debt_face": 60.0})+ high = merton_model(**{**BASE_MERTON, "debt_face": 200.0})+ assert high.default_probability > low.default_probability+ assert high.credit_spread > low.credit_spread > 0.0+++def test_default_probability_and_spread_rise_with_volatility():+ calm = merton_model(**{**BASE_MERTON, "equity_vol": 0.15})+ wild = merton_model(**{**BASE_MERTON, "equity_vol": 0.90})+ assert wild.default_probability > calm.default_probability+ assert wild.credit_spread > calm.credit_spread+++def test_default_probability_is_the_normal_tail_at_minus_d2():+ result = merton_model(**BASE_MERTON)+ assert result.default_probability == pytest.approx(norm.cdf(-result.d2))+ assert result.distance_to_default == pytest.approx(result.d2)+++def test_credit_spread_bp_is_the_spread_in_basis_points():+ result = merton_model(**BASE_MERTON)+ assert result.credit_spread_bp == pytest.approx(result.credit_spread * 1e4)+++def test_debt_value_plus_equity_equals_asset_value():+ result = merton_model(**BASE_MERTON)+ assert result.debt_value + BASE_MERTON["equity_value"] == pytest.approx(+ result.asset_value, rel=1e-9+ )+++def test_a_higher_asset_drift_pushes_distance_to_default_up():+ risk_neutral = merton_model(**BASE_MERTON)+ real_world = merton_model(**BASE_MERTON, asset_drift=0.12)+ assert real_world.distance_to_default > risk_neutral.distance_to_default+ # The drift only enters the distance to default, never the pricing legs.+ assert real_world.d2 == pytest.approx(risk_neutral.d2)+ assert real_world.credit_spread == pytest.approx(risk_neutral.credit_spread)+++def test_distance_to_default_matches_its_closed_form():+ assert distance_to_default(200.0, 0.25, 100.0, 2.0, drift=0.06) == pytest.approx(+ (math.log(2.0) + (0.06 - 0.5 * 0.25**2) * 2.0) / (0.25 * math.sqrt(2.0))+ )+++def test_distance_to_default_rejects_non_positive_inputs():+ with pytest.raises(ValueError, match="must all be positive"):+ distance_to_default(0.0, 0.25, 100.0, 1.0)+ with pytest.raises(ValueError, match="must all be positive"):+ distance_to_default(200.0, 0.25, 100.0, 0.0)+++def test_kmv_default_point_takes_all_short_and_half_the_long_book():+ assert kmv_default_point(100.0, 200.0) == pytest.approx(200.0)+ assert kmv_default_point(100.0, 200.0, long_term_weight=0.0) == pytest.approx(100.0)+ assert kmv_default_point(100.0, 200.0, long_term_weight=1.0) == pytest.approx(300.0)+++def test_kmv_default_point_validates_its_inputs():+ with pytest.raises(ValueError, match="non-negative"):+ kmv_default_point(-1.0, 200.0)+ with pytest.raises(ValueError, match=r"must lie in \[0, 1\]"):+ kmv_default_point(100.0, 200.0, long_term_weight=1.5)+++def test_kmv_distance_to_default_is_the_linear_gap_not_the_log_one():+ linear = kmv_distance_to_default(1000.0, 0.25, 200.0)+ assert linear == pytest.approx((1000.0 - 200.0) / (1000.0 * 0.25))+ # It is deliberately a different quantity from the Merton/lognormal version.+ assert linear != pytest.approx(distance_to_default(1000.0, 0.25, 200.0, 1.0))+++def test_kmv_distance_to_default_goes_negative_below_the_default_point():+ assert kmv_distance_to_default(100.0, 0.25, 150.0) < 0.0+++def test_kmv_distance_to_default_rejects_non_positive_inputs():+ with pytest.raises(ValueError, match="must be positive"):+ kmv_distance_to_default(0.0, 0.25, 100.0)++[email protected]("dd,expected", [+ (6.0, (0.0, 0.001)),+ (4.01, (0.0, 0.001)),+ (3.0, (0.001, 0.01)),+ (2.5, (0.001, 0.01)),+ (1.5, (0.01, 0.05)),+ (0.5, (0.05, math.inf)),+ (-2.0, (0.05, math.inf)),+])+def test_edf_reference_bands_follow_the_published_table(dd, expected):+ assert edf_reference_band(dd) == expected+++def test_edf_reference_band_rejects_a_non_finite_input():+ with pytest.raises(ValueError, match="must be finite"):+ edf_reference_band(float("nan"))+++# --------------------------------------------------------------------------+# spread analytics+# --------------------------------------------------------------------------+++def spread_inputs():+ index = pd.date_range("2024-01-01", periods=80, freq="D")+ bond = pd.Series(np.linspace(3.00, 3.79, 80), index=index)+ risk_free = pd.Series(np.full(80, 2.50), index=index)+ return bond, risk_free+++def test_credit_spread_analysis_columns_and_first_level(spread_inputs):+ bond, risk_free = spread_inputs+ out = credit_spread_analysis(bond, risk_free, window=20)++ assert list(out.columns) == [+ "spread_bp",+ "rolling_mean_bp",+ "rolling_std_bp",+ "z_score",+ "historical_percentile",+ "change_1p_bp",+ "change_lookback_bp",+ "signal",+ ]+ assert out.index.equals(bond.index)+ # 3.00% - 2.50% = 0.50% = 50bp.+ assert out["spread_bp"].iloc[0] == pytest.approx(50.0)+ assert out["change_1p_bp"].iloc[1] == pytest.approx(1.0)+ assert out["change_lookback_bp"].iloc[21] == pytest.approx(21.0)+++def test_the_three_input_units_are_consistent_with_each_other(spread_inputs):+ bond, risk_free = spread_inputs+ percent = credit_spread_analysis(bond, risk_free, window=20)["spread_bp"]+ decimal = credit_spread_analysis(+ bond / 100, risk_free / 100, window=20, input_unit="decimal"+ )["spread_bp"]+ basis = credit_spread_analysis(+ bond * 100, risk_free * 100, window=20, input_unit="bp"+ )["spread_bp"]+ pd.testing.assert_series_equal(percent, decimal)+ pd.testing.assert_series_equal(percent, basis)+++def test_signals_fire_on_the_z_score_threshold():+ index = pd.date_range("2024-01-01", periods=40, freq="D")+ values = np.full(40, 3.0)+ values[-1] = 9.0 # a violent widening at the end+ bond = pd.Series(values, index=index)+ risk_free = pd.Series(np.full(40, 2.0), index=index)++ out = credit_spread_analysis(bond, risk_free, window=10, signal_z=1.5)+ assert out["signal"].iloc[-1] == "cheap"+ assert out["z_score"].iloc[-1] > 1.5+ assert set(out["signal"].iloc[10:-1]) == {"neutral"}+++def test_a_tighter_signal_threshold_flags_more_rows():+ index = pd.date_range("2024-01-01", periods=60, freq="D")+ rng = np.random.default_rng(20260806)+ bond = pd.Series(3.0 + rng.normal(0, 0.1, 60), index=index)+ risk_free = pd.Series(np.full(60, 2.0), index=index)++ loose = credit_spread_analysis(bond, risk_free, window=15, signal_z=2.5)+ tight = credit_spread_analysis(bond, risk_free, window=15, signal_z=0.5)+ assert (tight["signal"] != "neutral").sum() > (loose["signal"] != "neutral").sum()+++def test_historical_percentile_is_whole_sample_and_therefore_look_ahead():+ # Pinned as a known property, not endorsed: the column is inherited from the+ # markdown template and the docstring warns it must not drive a backtest.+ # The proof is that one row's value moves when only LATER rows are added.+ index = pd.date_range("2024-01-01", periods=100, freq="D")+ bond = pd.Series(np.arange(100.0) + 300.0, index=index)+ risk_free = pd.Series(np.full(100, 200.0), index=index)++ hundred = credit_spread_analysis(bond, risk_free, window=10)+ fifty = credit_spread_analysis(bond.iloc[:50], risk_free.iloc[:50], window=10)++ assert hundred["historical_percentile"].iloc[0] == pytest.approx(0.01)+ assert fifty["historical_percentile"].iloc[0] == pytest.approx(0.02)+ # Everything else on that row is computed from the past alone.+ assert hundred["spread_bp"].iloc[0] == pytest.approx(fifty["spread_bp"].iloc[0])+ pd.testing.assert_series_equal(+ hundred["z_score"].iloc[:50], fifty["z_score"], check_freq=False+ )+ assert list(hundred["signal"].iloc[:50]) == list(fifty["signal"])+++def test_credit_spread_analysis_rejects_a_mismatched_index():+ a = pd.Series([1.0, 2.0], index=pd.date_range("2024-01-01", periods=2))+ b = pd.Series([1.0, 2.0], index=pd.date_range("2024-02-01", periods=2))+ with pytest.raises(ValueError, match="must share one index"):+ credit_spread_analysis(a, b)+++def test_credit_spread_analysis_validates_windows_and_units():+ index = pd.date_range("2024-01-01", periods=5)+ a = pd.Series(np.arange(5.0), index=index)+ with pytest.raises(ValueError, match="must be positive"):+ credit_spread_analysis(a, a, window=0)+ with pytest.raises(ValueError, match="unknown input_unit"):+ credit_spread_analysis(a, a, input_unit="ratio")+++def test_spread_term_structure_grid():+ issuers = {+ "AAA-LGFV": {1: 0.025, 3: 0.028, 5: 0.032},+ "AA-LGFV": {1: 0.032, 3: 0.041, 5: 0.055},+ }+ curve = {1: 0.020, 3: 0.022, 5: 0.025}+ out = spread_term_structure(issuers, curve)++ assert list(out.index) == ["AAA-LGFV", "AA-LGFV"]+ assert list(out.columns) == ["1Y_spread_bp", "3Y_spread_bp", "5Y_spread_bp"]+ assert out.loc["AAA-LGFV", "1Y_spread_bp"] == pytest.approx(50.0)+ assert out.loc["AA-LGFV", "5Y_spread_bp"] == pytest.approx(300.0)+++def test_spread_term_structure_honours_the_input_unit():+ decimal = spread_term_structure({"x": {1: 0.025}}, {1: 0.020})+ percent = spread_term_structure({"x": {1: 2.5}}, {1: 2.0}, input_unit="percent")+ assert decimal.loc["x", "1Y_spread_bp"] == pytest.approx(50.0)+ assert percent.loc["x", "1Y_spread_bp"] == pytest.approx(50.0)+++def test_spread_term_structure_leaves_an_unquoted_tenor_as_nan():+ out = spread_term_structure({"x": {1: 0.025, 7: 0.040}}, {1: 0.020})+ assert out.loc["x", "1Y_spread_bp"] == pytest.approx(50.0)+ assert math.isnan(out.loc["x", "7Y_spread_bp"])+++def test_spread_term_structure_rounding_is_controllable():+ issuers = {"x": {1: 0.0250123}}+ assert spread_term_structure(issuers, {1: 0.02}).loc["x", "1Y_spread_bp"] == (+ pytest.approx(50.1)+ )+ assert spread_term_structure(issuers, {1: 0.02}, decimals=None).loc[+ "x", "1Y_spread_bp"+ ] == pytest.approx(50.123)+++def test_spread_term_structure_validates_its_inputs():+ with pytest.raises(ValueError, match="at least one entry"):+ spread_term_structure({}, {1: 0.02})+ with pytest.raises(ValueError, match="unknown input_unit"):+ spread_term_structure({"x": {1: 0.025}}, {1: 0.02}, input_unit="ratio")diff --git a/agent/tests/quantlib/test_fixedincome.py b/agent/tests/quantlib/test_fixedincome.pynew file mode 100644index 000000000..135787aac--- /dev/null+++ b/agent/tests/quantlib/test_fixedincome.py@@ -0,0 +1,450 @@+"""Tests for src.quantlib.fixedincome.++Every sensitivity is checked against a finite-difference reprice of the pricing+function itself, so a change to `bond_price` cannot leave duration/convexity+quietly stale.+"""++import datetime as dt++import numpy as np+import pytest++from src.quantlib.fixedincome import (+ COMPOUNDING_CONVENTIONS,+ CurveFit,+ accrued_interest,+ bond_cashflows,+ bond_price,+ convexity,+ dv01,+ effective_duration,+ fit_yield_curve,+ macaulay_duration,+ modified_duration,+ nelson_siegel,+ svensson,+ year_fraction,+ ytm_solve,+)++BUMP_1BP = 1e-4+++# --------------------------------------------------------------------------+# bond_price+# --------------------------------------------------------------------------++[email protected]("freq", [1, 2, 4, 12])[email protected]("n_periods", [1, 5, 20])[email protected]("rate", [0.02, 0.05, 0.11])+def test_bond_prices_at_par_when_coupon_equals_ytm(freq, n_periods, rate):+ assert bond_price(100.0, rate, rate, n_periods, freq) == pytest.approx(100.0)+++def test_markdown_worked_example_is_preserved():+ # The value printed in credit-analysis/SKILL.md for a 5y 5% bond at 4%.+ assert bond_price(100, 0.05, 0.04, 5) == pytest.approx(104.4518, abs=5e-5)+++def test_premium_and_discount_ordering():+ assert bond_price(100, 0.06, 0.04, 10) > 100.0+ assert bond_price(100, 0.02, 0.04, 10) < 100.0+++def test_zero_yield_returns_undiscounted_cashflows():+ _, amounts = bond_cashflows(100, 0.05, 6, freq=2)+ assert bond_price(100, 0.05, 0.0, 6, freq=2) == pytest.approx(amounts.sum())+++def test_continuous_compounding_discounts_harder_than_discrete():+ discrete = bond_price(100, 0.05, 0.04, 10, 2, compounding="discrete")+ continuous = bond_price(100, 0.05, 0.04, 10, 2, compounding="continuous")+ assert continuous < discrete+++def test_unknown_compounding_rejected():+ with pytest.raises(ValueError, match="unknown compounding"):+ bond_price(100, 0.05, 0.04, 5, compounding="annual-ish")++[email protected]("bad", [0, -3])+def test_invalid_schedule_rejected(bad):+ with pytest.raises(ValueError):+ bond_price(100, 0.05, 0.04, bad)+ with pytest.raises(ValueError):+ bond_price(100, 0.05, 0.04, 5, freq=bad)+++# --------------------------------------------------------------------------+# ytm_solve+# --------------------------------------------------------------------------++[email protected]("compounding", COMPOUNDING_CONVENTIONS)[email protected]("coupon,ytm,n,freq", [+ (0.05, 0.04, 5, 1),+ (0.03, 0.065, 20, 2),+ (0.00, 0.05, 10, 1),+ (0.08, 0.005, 7, 4),+])+def test_price_ytm_round_trip(coupon, ytm, n, freq, compounding):+ price = bond_price(100, coupon, ytm, n, freq, compounding)+ assert ytm_solve(price, 100, coupon, n, freq, compounding) == pytest.approx(+ ytm, abs=1e-10+ )+++def test_ytm_solve_raises_when_price_unreachable():+ with pytest.raises(ValueError, match="no yield in"):+ ytm_solve(1e9, 100, 0.05, 5)+++def test_ytm_solve_rejects_inverted_bracket():+ with pytest.raises(ValueError, match="bracket must be increasing"):+ ytm_solve(100, 100, 0.05, 5, bracket=(1.0, 0.0))+++# --------------------------------------------------------------------------+# duration / convexity / DV01 -- all against a reprice+# --------------------------------------------------------------------------+++def test_zero_coupon_macaulay_duration_equals_maturity():+ assert macaulay_duration(100, 0.0, 0.05, 10, freq=1) == pytest.approx(10.0)+ assert macaulay_duration(100, 0.0, 0.05, 20, freq=2) == pytest.approx(10.0)+++def test_macaulay_duration_is_below_maturity_for_a_coupon_bond():+ assert macaulay_duration(100, 0.05, 0.04, 10) < 10.0++[email protected]("compounding", COMPOUNDING_CONVENTIONS)[email protected]("coupon,ytm,n,freq", [+ (0.05, 0.04, 5, 1),+ (0.03, 0.06, 20, 2),+ (0.00, 0.05, 10, 1),+])+def test_modified_duration_matches_central_difference(coupon, ytm, n, freq, compounding):+ def price(y):+ return bond_price(100, coupon, y, n, freq, compounding)++ numeric = (price(ytm - BUMP_1BP) - price(ytm + BUMP_1BP)) / (+ 2 * BUMP_1BP * price(ytm)+ )+ analytic = modified_duration(100, coupon, ytm, n, freq, compounding)+ # A central difference is third-order accurate, so at a 1bp half-width the+ # residual truncation error lands around 1e-6 relative for a 30y bond.+ assert analytic == pytest.approx(numeric, rel=1e-5)+++def test_modified_duration_equals_macaulay_under_continuous_compounding():+ args = (100, 0.05, 0.04, 10, 2, "continuous")+ assert modified_duration(*args) == pytest.approx(macaulay_duration(*args))+++def test_modified_duration_is_macaulay_over_one_plus_periodic_yield():+ d_mac = macaulay_duration(100, 0.05, 0.04, 10, 2)+ assert modified_duration(100, 0.05, 0.04, 10, 2) == pytest.approx(+ d_mac / (1 + 0.04 / 2)+ )++[email protected]("coupon,ytm,n,freq", [+ (0.05, 0.04, 5, 1),+ (0.03, 0.06, 20, 2),+ (0.00, 0.05, 30, 1),+])+def test_dv01_matches_a_one_basis_point_reprice(coupon, ytm, n, freq):+ par_amount = 1_000_000.0+ base = bond_price(100, coupon, ytm, n, freq)+ bumped = bond_price(100, coupon, ytm + BUMP_1BP, n, freq)+ repriced = (base - bumped) * par_amount / 100.0++ analytic = dv01(100, coupon, ytm, n, freq, par_amount)+ assert analytic == pytest.approx(repriced, rel=3e-3)+ assert analytic > repriced # duration alone ignores positive convexity++ # Almost all of that gap is the convexity term, so duration, convexity and+ # the reprice have to be mutually consistent to close it. What is left over+ # is the third-order term, worth ~1e-3 of the gap at a 1bp bump on 30y.+ cx = convexity(100, coupon, ytm, n, freq)+ expected_gap = 0.5 * cx * BUMP_1BP**2 * base * par_amount / 100.0+ assert analytic - repriced == pytest.approx(expected_gap, rel=3e-3)+++def test_dv01_matches_a_symmetric_reprice_much_more_tightly():+ coupon, ytm, n, freq = 0.05, 0.04, 5, 1+ down = bond_price(100, coupon, ytm - BUMP_1BP, n, freq)+ up = bond_price(100, coupon, ytm + BUMP_1BP, n, freq)+ repriced = (down - up) / 2 * 1_000_000.0 / 100.0+ assert dv01(100, coupon, ytm, n, freq) == pytest.approx(repriced, rel=1e-6)+++def test_dv01_scales_linearly_in_par_amount():+ one = dv01(100, 0.05, 0.04, 5, par_amount=1_000_000.0)+ ten = dv01(100, 0.05, 0.04, 5, par_amount=10_000_000.0)+ assert ten == pytest.approx(10 * one)+++def test_dv01_rejects_zero_face():+ with pytest.raises(ValueError, match="face must be non-zero"):+ dv01(0, 0.05, 0.04, 5)++[email protected]("compounding", COMPOUNDING_CONVENTIONS)[email protected]("coupon,ytm,n,freq", [+ (0.05, 0.04, 5, 1),+ (0.03, 0.06, 20, 2),+ (0.00, 0.05, 10, 1),+])+def test_convexity_is_positive_and_matches_second_difference(+ coupon, ytm, n, freq, compounding+):+ def price(y):+ return bond_price(100, coupon, y, n, freq, compounding)++ h = 1e-4+ numeric = (price(ytm + h) - 2 * price(ytm) + price(ytm - h)) / (h**2 * price(ytm))+ analytic = convexity(100, coupon, ytm, n, freq, compounding)+ assert analytic > 0.0+ assert analytic == pytest.approx(numeric, rel=1e-5)+++def test_continuous_zero_coupon_convexity_is_maturity_squared():+ assert convexity(100, 0.0, 0.04, 10, 1, "continuous") == pytest.approx(100.0)+++def test_convexity_grows_with_maturity():+ short = convexity(100, 0.05, 0.04, 3)+ long = convexity(100, 0.05, 0.04, 25)+ assert long > short > 0.0+++def test_second_order_expansion_beats_duration_alone_on_a_large_shock():+ coupon, ytm, n = 0.05, 0.04, 20+ shock = 0.01+ base = bond_price(100, coupon, ytm, n)+ actual = bond_price(100, coupon, ytm + shock, n)++ d_mod = modified_duration(100, coupon, ytm, n)+ cx = convexity(100, coupon, ytm, n)+ first_order = base * (1 - d_mod * shock)+ second_order = base * (1 - d_mod * shock + 0.5 * cx * shock**2)++ assert abs(second_order - actual) < abs(first_order - actual)+++# --------------------------------------------------------------------------+# effective_duration+# --------------------------------------------------------------------------+++def test_effective_duration_matches_analytic_duration_for_a_bullet_bond():+ def reprice(y):+ return bond_price(100, 0.05, y, 10, 2)++ assert effective_duration(reprice, 0.04) == pytest.approx(+ modified_duration(100, 0.05, 0.04, 10, 2), rel=1e-5+ )+++def test_effective_duration_rejects_a_non_positive_bump():+ with pytest.raises(ValueError, match="bump must be positive"):+ effective_duration(lambda y: 100.0, 0.04, bump=0.0)+++def test_effective_duration_rejects_a_zero_base_price():+ with pytest.raises(ValueError, match="base price is zero"):+ effective_duration(lambda y: 0.0, 0.04)+++# --------------------------------------------------------------------------+# day count / accrued interest+# --------------------------------------------------------------------------+++def test_act_365f_and_act_360_use_their_stated_bases():+ start, end = dt.date(2023, 1, 1), dt.date(2023, 7, 1)+ days = (end - start).days+ assert year_fraction(start, end, "ACT/365F") == pytest.approx(days / 365)+ assert year_fraction(start, end, "ACT/360") == pytest.approx(days / 360)+++def test_30_360_treats_every_month_as_thirty_days():+ assert year_fraction(dt.date(2024, 1, 31), dt.date(2024, 7, 31), "30/360") == (+ pytest.approx(0.5)+ )+ assert year_fraction(dt.date(2024, 1, 1), dt.date(2025, 1, 1), "30/360") == (+ pytest.approx(1.0)+ )+++def test_30_360_us_and_eurobond_differ_when_only_the_end_leg_is_the_31st():+ start, end = dt.date(2024, 1, 15), dt.date(2024, 3, 31)+ # US basis leaves D2 = 31 because D1 was not clipped to 30; 30E/360 clips it.+ assert year_fraction(start, end, "30/360") == pytest.approx((60 + 16) / 360)+ assert year_fraction(start, end, "30E/360") == pytest.approx((60 + 15) / 360)+++def test_act_act_uses_a_366_day_basis_inside_a_leap_year():+ assert year_fraction(+ dt.date(2024, 1, 1), dt.date(2025, 1, 1), "ACT/ACT"+ ) == pytest.approx(1.0)+ assert year_fraction(+ dt.date(2024, 1, 1), dt.date(2024, 3, 1), "ACT/ACT"+ ) == pytest.approx(60 / 366)+++def test_year_fraction_is_antisymmetric():+ a, b = dt.date(2024, 3, 1), dt.date(2024, 9, 1)+ assert year_fraction(b, a) == pytest.approx(-year_fraction(a, b))+++def test_unknown_day_count_rejected():+ with pytest.raises(ValueError, match="unknown day_count"):+ year_fraction(dt.date(2024, 1, 1), dt.date(2024, 2, 1), "ACT/ACT-ICMA")+++def test_accrued_interest_is_zero_on_a_coupon_date_and_full_at_the_next():+ last, nxt = dt.date(2024, 1, 15), dt.date(2024, 7, 15)+ assert accrued_interest(100, 0.05, 2, last, last, nxt) == pytest.approx(0.0)+ assert accrued_interest(100, 0.05, 2, last, nxt, nxt) == pytest.approx(2.5)+++def test_accrued_interest_is_linear_in_elapsed_time_under_30_360():+ last, mid, nxt = dt.date(2024, 1, 15), dt.date(2024, 4, 15), dt.date(2024, 7, 15)+ assert accrued_interest(+ 100, 0.05, 2, last, mid, nxt, day_count="30/360"+ ) == pytest.approx(1.25)+++def test_accrued_interest_rejects_settlement_outside_the_period():+ last, nxt = dt.date(2024, 1, 15), dt.date(2024, 7, 15)+ with pytest.raises(ValueError, match="settlement must fall inside"):+ accrued_interest(100, 0.05, 2, last, dt.date(2024, 8, 1), nxt)+++def test_accrued_interest_rejects_unordered_coupon_dates():+ with pytest.raises(ValueError, match="last_coupon must precede next_coupon"):+ accrued_interest(+ 100, 0.05, 2, dt.date(2024, 7, 15), dt.date(2024, 7, 15), dt.date(2024, 1, 15)+ )+++# --------------------------------------------------------------------------+# curve models+# --------------------------------------------------------------------------+++def test_nelson_siegel_limits():+ beta0, beta1, beta2, lam = 0.045, -0.02, 0.03, 2.5+ # tau -> 0 is the instantaneous short rate beta0 + beta1.+ assert nelson_siegel(0.0, beta0, beta1, beta2, lam) == pytest.approx(beta0 + beta1)+ assert nelson_siegel(1e-9, beta0, beta1, beta2, lam) == pytest.approx(+ beta0 + beta1, abs=1e-8+ )+ # tau -> infinity decays to the level factor.+ assert nelson_siegel(1e6, beta0, beta1, beta2, lam) == pytest.approx(beta0, abs=1e-5)+++def test_nelson_siegel_returns_a_float_for_scalar_input_and_an_array_otherwise():+ assert isinstance(nelson_siegel(5.0, 0.04, -0.01, 0.01, 2.0), float)+ out = nelson_siegel([1.0, 5.0], 0.04, -0.01, 0.01, 2.0)+ assert isinstance(out, np.ndarray) and out.shape == (2,)+++def test_svensson_reduces_to_nelson_siegel_when_the_second_hump_is_flat():+ tau = np.array([0.5, 1.0, 3.0, 10.0])+ assert np.allclose(+ svensson(tau, 0.04, -0.02, 0.01, 0.0, 1.5, 6.0),+ nelson_siegel(tau, 0.04, -0.02, 0.01, 1.5),+ )+++def test_curve_models_reject_a_non_positive_decay():+ with pytest.raises(ValueError, match="decay parameter must be positive"):+ nelson_siegel(1.0, 0.04, -0.01, 0.01, 0.0)+ with pytest.raises(ValueError, match="decay parameter must be positive"):+ svensson(1.0, 0.04, -0.01, 0.01, 0.0, 1.5, -1.0)+++def test_curve_models_reject_negative_maturities():+ with pytest.raises(ValueError, match="maturities must be non-negative"):+ nelson_siegel([-1.0, 2.0], 0.04, -0.01, 0.01, 2.0)+++TENORS = np.array([0.25, 0.5, 1.0, 2.0, 3.0, 5.0, 7.0, 10.0, 20.0, 30.0])+OFF_GRID = np.array([0.75, 4.0, 8.5, 15.0, 25.0])+++def test_fit_recovers_a_nelson_siegel_curve_it_generated():+ truth = (0.045, -0.02, 0.03, 2.5)+ fit = fit_yield_curve(TENORS, nelson_siegel(TENORS, *truth), model="nelson_siegel")++ assert fit.model == "nelson_siegel"+ assert fit.rmse < 1e-10+ assert len(fit.params) == 4+ assert fit.params == pytest.approx(truth, rel=1e-6)+ assert np.allclose(fit(TENORS), nelson_siegel(TENORS, *truth), atol=1e-10)+ assert np.allclose(fit(OFF_GRID), nelson_siegel(OFF_GRID, *truth), atol=1e-10)+++def test_fit_recovers_a_svensson_curve_it_generated():+ truth = (0.05, -0.03, 0.04, -0.02, 1.2, 8.0)+ fit = fit_yield_curve(TENORS, svensson(TENORS, *truth), model="svensson")++ assert fit.model == "svensson"+ assert fit.rmse < 1e-10+ assert len(fit.params) == 6+ # Curve values are the identifiable object; the parameterisation is not+ # unique, so the curve is what is asserted here.+ assert np.allclose(fit(TENORS), svensson(TENORS, *truth), atol=1e-10)+ assert np.allclose(fit(OFF_GRID), svensson(OFF_GRID, *truth), atol=1e-10)+++def test_svensson_fit_is_at_least_as_good_as_nelson_siegel_on_the_same_data():+ truth = (0.05, -0.03, 0.04, -0.02, 1.2, 8.0)+ observed = svensson(TENORS, *truth)+ ns = fit_yield_curve(TENORS, observed, model="nelson_siegel")+ sv = fit_yield_curve(TENORS, observed, model="svensson")+ assert sv.rmse <= ns.rmse+++def test_fit_is_robust_to_noise_and_stays_close_to_the_generating_curve():+ truth = (0.045, -0.02, 0.03, 2.5)+ clean = nelson_siegel(TENORS, *truth)+ noisy = clean + np.random.default_rng(20260806).normal(0.0, 2e-4, TENORS.size)+ fit = fit_yield_curve(TENORS, noisy, model="nelson_siegel")+ assert np.max(np.abs(fit(TENORS) - clean)) < 5e-4+++def test_curve_fit_is_frozen_and_callable():+ fit = fit_yield_curve(TENORS, nelson_siegel(TENORS, 0.04, -0.01, 0.01, 2.0),+ model="nelson_siegel")+ assert isinstance(fit, CurveFit)+ with pytest.raises(Exception):+ fit.rmse = 0.5 # type: ignore[misc]+++def test_curve_fit_rejects_an_unknown_stored_model():+ with pytest.raises(ValueError, match="unknown curve model"):+ CurveFit(model="cubic-spline", params=(0.0,))(1.0)+++def test_fit_yield_curve_rejects_an_unknown_model():+ with pytest.raises(ValueError, match="unknown model"):+ fit_yield_curve(TENORS, nelson_siegel(TENORS, 0.04, -0.01, 0.01, 2.0), "cubic")+++def test_fit_yield_curve_rejects_mismatched_or_thin_inputs():+ with pytest.raises(ValueError, match="same length"):+ fit_yield_curve([1.0, 2.0, 3.0], [0.01, 0.02])+ with pytest.raises(ValueError, match="only 3 observations"):+ fit_yield_curve([1.0, 2.0, 3.0], [0.01, 0.02, 0.03], model="nelson_siegel")+++def test_fit_yield_curve_rejects_non_positive_maturities():+ with pytest.raises(ValueError, match="strictly positive"):+ fit_yield_curve(np.zeros(10), np.zeros(10), model="nelson_siegel")diff --git a/agent/tests/quantlib/test_impact.py b/agent/tests/quantlib/test_impact.pynew file mode 100644index 000000000..c03b492de--- /dev/null+++ b/agent/tests/quantlib/test_impact.py@@ -0,0 +1,247 @@+"""Tests for the market-impact and slippage models.++Two properties matter more than any single number and are asserted for all three+price models: impact is monotone in order size, and it vanishes at zero size.+"""++from __future__ import annotations++import itertools+import math++import pandas as pd+import pytest++from src.quantlib.impact import (+ DEFAULT_DELAY_BARS,+ DEFAULT_LINEAR_IMPACT_COEFF,+ DEFAULT_SLIPPAGE_BPS,+ DEFAULT_SQRT_IMPACT_ETA,+ delayed_execution,+ fixed_slippage,+ linear_impact,+ sqrt_impact,+)++PRICE = 100.0+ADV = 1_000_000.0+VOLATILITY = 0.02++#: The three price models reduced to a common (price, direction, size) signature.+SIZED_MODELS = {+ "linear": lambda size, direction: linear_impact(PRICE, direction, size, ADV),+ "sqrt": lambda size, direction: sqrt_impact(PRICE, direction, size, ADV, VOLATILITY),+}+++def test_fixed_slippage_matches_its_definition():+ """5bp on a price of 100 is exactly 0.05."""+ assert fixed_slippage(PRICE, 1, bps=5.0) == pytest.approx(100.05, abs=1e-12)+ assert fixed_slippage(PRICE, -1, bps=5.0) == pytest.approx(99.95, abs=1e-12)+++def test_defaults_are_wired_to_the_module_constants():+ """Each default argument really is its constant, not a re-typed literal."""+ assert fixed_slippage(PRICE, 1) == fixed_slippage(PRICE, 1, bps=DEFAULT_SLIPPAGE_BPS)+ assert linear_impact(PRICE, 1, 100_000.0, ADV) == linear_impact(+ PRICE, 1, 100_000.0, ADV, impact_coeff=DEFAULT_LINEAR_IMPACT_COEFF+ )+ assert sqrt_impact(PRICE, 1, 100_000.0, ADV, VOLATILITY) == sqrt_impact(+ PRICE, 1, 100_000.0, ADV, VOLATILITY, eta=DEFAULT_SQRT_IMPACT_ETA+ )+++def test_default_constants_hold_the_values_the_skill_documents():+ """Pin the published numbers.++ ``skills/execution-model/SKILL.md`` tells readers that ``bps`` defaults to 5.0,+ ``impact_coeff`` to 0.1, ``eta`` to 0.5 and ``delay_bars`` to 1. Comparing a+ default against its own constant cannot catch a change to that constant, so the+ values are asserted literally here -- otherwise a silent edit would leave the+ suite green and the documentation wrong.+ """+ assert DEFAULT_SLIPPAGE_BPS == 5.0+ assert DEFAULT_LINEAR_IMPACT_COEFF == 0.1+ assert DEFAULT_SQRT_IMPACT_ETA == 0.5+ assert DEFAULT_DELAY_BARS == 1+++def test_fixed_slippage_charges_regardless_of_size():+ """Unlike the sized models, the fixed model has no zero-impact limit.++ The module docstring used to claim every price model returns the untouched+ price at zero size. It does not hold for this one, which takes no size at all.+ """+ assert fixed_slippage(PRICE, 1) - PRICE == pytest.approx(PRICE * DEFAULT_SLIPPAGE_BPS / 10_000.0, abs=1e-12)+ with pytest.raises(TypeError):+ fixed_slippage(PRICE, 1, 5.0, 0.0) # no size parameter exists to pass+++def test_fixed_slippage_zero_bps_is_free():+ """Zero basis points leaves the price untouched."""+ assert fixed_slippage(PRICE, 1, bps=0.0) == PRICE+ assert fixed_slippage(PRICE, -1, bps=0.0) == PRICE+++def test_linear_impact_matches_its_definition():+ """10% participation at coeff 0.1 is a 1% price move."""+ assert linear_impact(PRICE, 1, 100_000.0, ADV, impact_coeff=0.1) == pytest.approx(101.0, abs=1e-12)+ assert linear_impact(PRICE, -1, 100_000.0, ADV, impact_coeff=0.1) == pytest.approx(99.0, abs=1e-12)+++def test_sqrt_impact_matches_its_definition():+ """eta * sigma * sqrt(participation) = 0.5 * 0.02 * sqrt(0.25) = 0.005."""+ price = sqrt_impact(PRICE, 1, 250_000.0, ADV, VOLATILITY, eta=0.5)+ assert price == pytest.approx(PRICE * (1.0 + 0.5 * 0.02 * math.sqrt(0.25)), abs=1e-12)+ assert price == pytest.approx(100.5, abs=1e-12)++[email protected]("name", sorted(SIZED_MODELS))[email protected]("direction", [1, -1])+def test_zero_size_limit_is_zero_impact(name, direction):+ """A zero-size order moves the price not at all."""+ assert SIZED_MODELS[name](0.0, direction) == pytest.approx(PRICE, abs=1e-12)++[email protected]("name", sorted(SIZED_MODELS))+def test_impact_is_monotone_in_size_when_buying(name):+ """Buying more pushes the fill price strictly higher."""+ model = SIZED_MODELS[name]+ sizes = [0.0, 1_000.0, 10_000.0, 100_000.0, 250_000.0, 500_000.0]+ prices = [model(size, 1) for size in sizes]+ assert all(later > earlier for earlier, later in itertools.pairwise(prices))++[email protected]("name", sorted(SIZED_MODELS))+def test_impact_is_monotone_in_size_when_selling(name):+ """Selling more pushes the fill price strictly lower."""+ model = SIZED_MODELS[name]+ sizes = [0.0, 1_000.0, 10_000.0, 100_000.0, 250_000.0, 500_000.0]+ prices = [model(size, -1) for size in sizes]+ assert all(later < earlier for earlier, later in itertools.pairwise(prices))++[email protected]("name", sorted(SIZED_MODELS))[email protected]("direction", [1, -1])+def test_impact_always_works_against_the_trader(name, direction):+ """Buys never fill below the reference price, sells never fill above it."""+ filled = SIZED_MODELS[name](200_000.0, direction)+ assert (filled - PRICE) * direction > 0.0+++def test_sqrt_marginal_impact_decays_but_linear_marginal_impact_does_not():+ """The square-root model's whole point: each extra share costs less than the last."""+ step = 100_000.0+ sqrt_first = sqrt_impact(PRICE, 1, step, ADV, VOLATILITY) - PRICE+ sqrt_second = sqrt_impact(PRICE, 1, 2 * step, ADV, VOLATILITY) - sqrt_impact(PRICE, 1, step, ADV, VOLATILITY)+ assert sqrt_second < sqrt_first++ linear_first = linear_impact(PRICE, 1, step, ADV) - PRICE+ linear_second = linear_impact(PRICE, 1, 2 * step, ADV) - linear_impact(PRICE, 1, step, ADV)+ assert linear_second == pytest.approx(linear_first, abs=1e-12)+++def test_impact_scales_with_its_coefficients():+ """Doubling the coefficient doubles the impact for both sized models."""+ base = linear_impact(PRICE, 1, 100_000.0, ADV, impact_coeff=0.1) - PRICE+ assert linear_impact(PRICE, 1, 100_000.0, ADV, impact_coeff=0.2) - PRICE == pytest.approx(2 * base, abs=1e-12)++ sqrt_base = sqrt_impact(PRICE, 1, 100_000.0, ADV, VOLATILITY, eta=0.4) - PRICE+ doubled = sqrt_impact(PRICE, 1, 100_000.0, ADV, VOLATILITY, eta=0.8) - PRICE+ assert doubled == pytest.approx(2 * sqrt_base, abs=1e-12)+++def test_zero_volatility_means_no_sqrt_impact():+ """With no volatility the square-root model charges nothing."""+ assert sqrt_impact(PRICE, 1, 500_000.0, ADV, 0.0) == pytest.approx(PRICE, abs=1e-12)++[email protected]("direction", [0, 2, -2, 0.5, "buy", None])+def test_bad_direction_is_rejected(direction):+ """Direction multiplies the impact, so anything but 1 or -1 must raise."""+ with pytest.raises(ValueError, match="direction"):+ fixed_slippage(PRICE, direction)+++def test_numerically_equal_direction_is_accepted():+ """1.0 and True equal 1, so the membership test accepts them; that is intended."""+ assert fixed_slippage(PRICE, 1.0) == fixed_slippage(PRICE, 1)+ assert fixed_slippage(PRICE, True) == fixed_slippage(PRICE, 1)++[email protected]("price", [0.0, -1.0])+def test_non_positive_price_is_rejected(price):+ """A non-positive reference price is nonsense for every model."""+ with pytest.raises(ValueError, match="price"):+ fixed_slippage(price, 1)+ with pytest.raises(ValueError, match="price"):+ linear_impact(price, 1, 1_000.0, ADV)+ with pytest.raises(ValueError, match="price"):+ sqrt_impact(price, 1, 1_000.0, ADV, VOLATILITY)+++def test_zero_adv_is_rejected_rather_than_dividing_by_zero():+ """An instrument that does not trade has no defined participation rate."""+ with pytest.raises(ValueError, match="adv"):+ linear_impact(PRICE, 1, 1_000.0, 0.0)+ with pytest.raises(ValueError, match="adv"):+ sqrt_impact(PRICE, 1, 1_000.0, 0.0, VOLATILITY)+++def test_negative_size_is_rejected():+ """Side is carried by direction, so a negative size is a caller bug."""+ with pytest.raises(ValueError, match="volume_traded"):+ linear_impact(PRICE, 1, -1_000.0, ADV)+ with pytest.raises(ValueError, match="volume_traded"):+ sqrt_impact(PRICE, 1, -1_000.0, ADV, VOLATILITY)+++def test_negative_coefficients_are_rejected():+ """A negative coefficient would pay the trader for trading."""+ with pytest.raises(ValueError, match="bps"):+ fixed_slippage(PRICE, 1, bps=-1.0)+ with pytest.raises(ValueError, match="impact_coeff"):+ linear_impact(PRICE, 1, 1_000.0, ADV, impact_coeff=-0.1)+ with pytest.raises(ValueError, match="eta"):+ sqrt_impact(PRICE, 1, 1_000.0, ADV, VOLATILITY, eta=-0.5)+ with pytest.raises(ValueError, match="volatility"):+ sqrt_impact(PRICE, 1, 1_000.0, ADV, -0.02)+++def test_delayed_execution_shifts_the_signal_forward():+ """A one-bar delay moves each value to the next bar and blanks the first."""+ signal = pd.Series([1.0, 0.0, -1.0, 1.0])+ delayed = delayed_execution(signal, delay_bars=1)+ assert math.isnan(delayed.iloc[0])+ assert list(delayed.iloc[1:]) == [1.0, 0.0, -1.0]+++def test_delayed_execution_default_is_t_plus_one():+ """The default lag is one bar, matching the China A-share T+1 rule."""+ signal = pd.Series([1.0, 2.0, 3.0])+ pd.testing.assert_series_equal(delayed_execution(signal), delayed_execution(signal, delay_bars=1))+++def test_zero_delay_returns_an_equal_signal():+ """Zero delay is same-bar execution and changes nothing."""+ signal = pd.Series([1.0, 0.0, -1.0])+ pd.testing.assert_series_equal(delayed_execution(signal, delay_bars=0), signal)+++def test_delayed_execution_preserves_the_index():+ """The index must survive so the signal still aligns with its price frame."""+ index = pd.date_range("2024-01-01", periods=4, freq="D")+ signal = pd.Series([1.0, 0.0, -1.0, 1.0], index=index)+ pd.testing.assert_index_equal(delayed_execution(signal).index, index)+++def test_negative_delay_is_rejected_as_lookahead_bias():+ """A negative shift pulls future signal into the past; that must never be silent."""+ with pytest.raises(ValueError, match="look-ahead"):+ delayed_execution(pd.Series([1.0, 2.0]), delay_bars=-1)+++def test_delayed_execution_rejects_a_non_series():+ """A DataFrame or list would shift with different semantics, so reject it."""+ with pytest.raises(TypeError, match="pandas Series"):+ delayed_execution([1.0, 2.0, 3.0])diff --git a/agent/tests/quantlib/test_options.py b/agent/tests/quantlib/test_options.pynew file mode 100644index 000000000..2b030ef6c--- /dev/null+++ b/agent/tests/quantlib/test_options.py@@ -0,0 +1,391 @@+"""Pin the Black-Scholes primitives in ``src.quantlib.options``.++Three independent kinds of check, because each catches what the others miss:++ * Published reference values (Hull, *Options, Futures and Other+ Derivatives*). These catch a formula that is self-consistently wrong.+ * Structural identities -- put-call parity, and Greeks against central+ finite-difference bumps of the price function. These catch a Greek that+ disagrees with the price it is supposed to differentiate, including unit+ errors in theta (per day) and vega/rho (per percentage point).+ * Round-trips and edges -- price to implied vol and back, degenerate inputs,+ deep in/out of the money, and the last day before expiry.+"""++from __future__ import annotations++import math++import pytest++from src.quantlib.options import bs_greeks, bs_price, implied_volatility++# 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}+# Hull, Example 19.1: the worked example the Greek chapter tabulates.+_HULL_19_1 = {"S": 49.0, "K": 50.0, "T": 0.3846, "r": 0.05, "sigma": 0.20}+++class TestPublishedReferenceValues:+ """Prices and Greeks against textbook-published numbers."""++ def test_hull_15_6_call_and_put_prices(self) -> None:+ # Hull publishes c = 4.76 and p = 0.81.+ assert bs_price(**_HULL_15_6, option_type="call") == pytest.approx(4.76, abs=5e-3)+ assert bs_price(**_HULL_15_6, option_type="put") == pytest.approx(0.81, abs=5e-3)++ def test_hull_19_1_price(self) -> None:+ # Hull publishes a call value of 2.40.+ assert bs_price(**_HULL_19_1, option_type="call") == pytest.approx(2.40, abs=5e-3)++ @pytest.mark.parametrize(+ "greek, published, scale",+ [+ # Hull tabulates delta 0.522, gamma 0.066 in native units...+ ("delta", 0.522, 1.0),+ ("gamma", 0.066, 1.0),+ # ...and theta -4.31/year, vega 12.1 and rho 8.91 per 1.0 of the+ # input, whereas this module reports theta per calendar day and+ # vega/rho per percentage point.+ ("theta", -4.31, 365.0),+ ("vega", 12.1, 100.0),+ ("rho", 8.91, 100.0),+ ],+ )+ def test_hull_19_1_greeks(self, greek: str, published: float, scale: float) -> None:+ got = bs_greeks(**_HULL_19_1, option_type="call")[greek] * scale+ assert got == pytest.approx(published, abs=5e-3 * max(abs(published), 1.0))++ def test_at_the_money_one_year_reference(self) -> None:+ # The standard S=K=100, T=1, r=5%, sigma=20% case.+ assert bs_price(100, 100, 1.0, 0.05, 0.2, "call") == pytest.approx(10.450584, abs=1e-6)+ assert bs_price(100, 100, 1.0, 0.05, 0.2, "put") == pytest.approx(5.573526, abs=1e-6)+++class TestPutCallParity:+ """``C - P == S*exp(-qT) - K*exp(-rT)`` must hold exactly."""++ @pytest.mark.parametrize(+ "S, K, T, r, sigma, q",+ [+ (100.0, 100.0, 1.0, 0.05, 0.20, 0.0),+ (100.0, 80.0, 0.25, 0.03, 0.45, 0.0),+ (100.0, 130.0, 2.0, 0.01, 0.15, 0.0),+ (100.0, 100.0, 1.0, 0.05, 0.20, 0.03),+ (250.0, 200.0, 0.5, 0.04, 0.60, 0.02),+ (7.5, 10.0, 0.75, 0.00, 0.30, 0.05),+ ],+ )+ def test_parity_holds(self, S, K, T, r, sigma, q) -> None:+ call = bs_price(S, K, T, r, sigma, "call", q)+ put = bs_price(S, K, T, r, sigma, "put", q)+ assert call - put == pytest.approx(+ S * math.exp(-q * T) - K * math.exp(-r * T), abs=1e-9+ )++ def test_parity_holds_for_the_greeks_too(self) -> None:+ # Gamma and vega are identical for call and put; deltas differ by+ # exactly exp(-qT); rho differs by K*T*exp(-rT)/100.+ args = {"S": 100.0, "K": 105.0, "T": 0.6, "r": 0.04, "sigma": 0.25, "q": 0.02}+ call = bs_greeks(**args, option_type="call")+ put = bs_greeks(**args, option_type="put")+ assert call["gamma"] == pytest.approx(put["gamma"], rel=1e-12)+ assert call["vega"] == pytest.approx(put["vega"], rel=1e-12)+ assert call["delta"] - put["delta"] == pytest.approx(+ math.exp(-args["q"] * args["T"]), abs=1e-12+ )+ assert call["rho"] - put["rho"] == pytest.approx(+ args["K"] * args["T"] * math.exp(-args["r"] * args["T"]) / 100.0, abs=1e-12+ )+++class TestGreeksAgainstFiniteDifferences:+ """Every Greek must be the derivative of the price function it claims."""++ _CASES = [+ (100.0, 100.0, 1.00, 0.05, 0.20, 0.00, "call"),+ (100.0, 100.0, 1.00, 0.05, 0.20, 0.00, "put"),+ (100.0, 120.0, 0.50, 0.03, 0.35, 0.02, "call"),+ (100.0, 80.0, 0.25, 0.04, 0.45, 0.01, "put"),+ (100.0, 100.0, 0.05, 0.02, 0.15, 0.00, "call"),+ ]++ @pytest.mark.parametrize("S, K, T, r, sigma, q, kind", _CASES)+ def test_delta_and_gamma(self, S, K, T, r, sigma, q, kind) -> None:+ h = 1e-4 * S+ up = bs_price(S + h, K, T, r, sigma, kind, q)+ mid = bs_price(S, K, T, r, sigma, kind, q)+ down = bs_price(S - h, K, T, r, sigma, kind, q)+ greeks = bs_greeks(S, K, T, r, sigma, kind, q)+ assert greeks["delta"] == pytest.approx((up - down) / (2 * h), rel=1e-5)+ assert greeks["gamma"] == pytest.approx((up - 2 * mid + down) / h**2, rel=1e-3)++ @pytest.mark.parametrize("S, K, T, r, sigma, q, kind", _CASES)+ def test_vega_is_per_percentage_point(self, S, K, T, r, sigma, q, kind) -> None:+ h = 1e-5+ d_price = (+ bs_price(S, K, T, r, sigma + h, kind, q)+ - bs_price(S, K, T, r, sigma - h, kind, q)+ ) / (2 * h)+ assert bs_greeks(S, K, T, r, sigma, kind, q)["vega"] == pytest.approx(+ d_price / 100.0, rel=1e-5+ )++ @pytest.mark.parametrize("S, K, T, r, sigma, q, kind", _CASES)+ def test_theta_is_negative_dprice_dT_per_calendar_day(+ self, S, K, T, r, sigma, q, kind+ ) -> None:+ h = 1e-5+ d_price = (+ bs_price(S, K, T + h, r, sigma, kind, q)+ - bs_price(S, K, T - h, r, sigma, kind, q)+ ) / (2 * h)+ assert bs_greeks(S, K, T, r, sigma, kind, q)["theta"] == pytest.approx(+ -d_price / 365.0, rel=1e-5+ )++ @pytest.mark.parametrize("S, K, T, r, sigma, q, kind", _CASES)+ def test_rho_is_per_percentage_point(self, S, K, T, r, sigma, q, kind) -> None:+ h = 1e-6+ d_price = (+ bs_price(S, K, T, r + h, sigma, kind, q)+ - bs_price(S, K, T, r - h, sigma, kind, q)+ ) / (2 * h)+ assert bs_greeks(S, K, T, r, sigma, kind, q)["rho"] == pytest.approx(+ d_price / 100.0, rel=1e-4+ )+++class TestImpliedVolatility:+ """Price -> implied vol -> price must return the original price."""++ @pytest.mark.parametrize(+ "S, K, T, r, sigma, q, kind",+ [+ (100.0, 100.0, 1.00, 0.05, 0.20, 0.00, "call"),+ (100.0, 100.0, 1.00, 0.05, 0.20, 0.00, "put"),+ (100.0, 130.0, 0.50, 0.03, 0.45, 0.00, "call"),+ (100.0, 70.0, 0.25, 0.03, 0.55, 0.00, "put"),+ (100.0, 100.0, 2.00, 0.02, 0.08, 0.03, "call"),+ (100.0, 95.0, 0.10, 0.04, 1.20, 0.01, "put"),+ (3000.0, 3100.0, 0.75, 0.045, 0.18, 0.015, "call"),+ ],+ )+ def test_round_trip(self, S, K, T, r, sigma, q, kind) -> None:+ price = bs_price(S, K, T, r, sigma, kind, q)+ implied = implied_volatility(price, S, K, T, r, kind, q)+ assert implied == pytest.approx(sigma, abs=1e-4)+ assert bs_price(S, K, T, r, implied, kind, q) == pytest.approx(price, abs=1e-6)++ def test_deep_out_of_the_money_round_trip(self) -> None:+ # The Brenner-Subrahmanyam seed lands at sigma 0.00113 for this quote,+ # where vega underflows to 0.0, so Newton breaks on the first step and+ # the bisection branch carries the whole solve. The vol itself must come+ # back, not merely a vol that reprices to the same number.+ price = bs_price(100.0, 150.0, 0.25, 0.03, 0.30, "call")+ assert price > 1e-3 # resolvable: far above the 1e-6 price tolerance+ implied = implied_volatility(price, 100.0, 150.0, 0.25, 0.03, "call")+ assert implied == pytest.approx(0.30, abs=1e-4)++ @pytest.mark.parametrize(+ "S, K, T, sigma, label",+ [+ (100.0, 200.0, 0.05, 0.25, "out of the money, price 1.2e-35"),+ (200.0, 100.0, 0.05, 0.25, "in the money, price flat to 1e-16"),+ ],+ )+ def test_unidentifiable_vol_is_refused_rather_than_guessed(+ self, S: float, K: float, T: float, sigma: float, label: str+ ) -> None:+ """A quote that carries no vol information must return nan, not a number.++ Where the price is flat in ``sigma`` to machine precision, every vol in+ a wide band satisfies ``tol``, so "converged" means only that the search+ stopped somewhere. Returning that endpoint reports a 140% error as a+ solved volatility (true 0.25, returned 0.60 for the in-the-money case).+ The solver checks vega at the candidate and refuses instead.+ """+ r = 0.03+ price = bs_price(S, K, T, r, sigma, "call")+ implied = implied_volatility(price, S, K, T, r, "call")+ assert math.isnan(implied)++ def test_identifiability_threshold_tracks_the_requested_tolerance(self) -> None:+ """The refusal scales with ``tol``; it is not an absolute vega floor.++ Loosening the tolerance widens the band of volatilities that reprice+ within it, so the same quote goes from identifiable to unidentifiable.+ This quote has vega 1.85e-3 per unit sigma, which puts the flip at+ tol = 1.85e-5: solvable at 1e-6, refused at 1e-2.+ """+ S, K, T, r, sigma = 100.0, 135.0, 0.08, 0.03, 0.25+ price = bs_price(S, K, T, r, sigma, "call")+ tight = implied_volatility(price, S, K, T, r, "call", tol=1e-6)+ assert tight == pytest.approx(sigma, abs=1e-4)+ assert math.isnan(implied_volatility(price, S, K, T, r, "call", tol=1e-2))+++ def test_near_expiry_round_trip(self) -> None:+ one_day = 1.0 / 365.0+ price = bs_price(100.0, 100.5, one_day, 0.03, 0.30, "call")+ implied = implied_volatility(price, 100.0, 100.5, one_day, 0.03, "call")+ assert implied == pytest.approx(0.30, abs=1e-3)++ def test_below_intrinsic_raises(self) -> None:+ # A call cannot trade below its discounted forward intrinsic.+ with pytest.raises(ValueError, match="below intrinsic"):+ implied_volatility(2.0, 120.0, 100.0, 1.0, 0.05, "call")++ def test_put_below_undiscounted_intrinsic_is_accepted(self) -> None:+ # A deep in-the-money European put legitimately trades below K - S.+ # Guarding on the undiscounted intrinsic would reject this real price.+ S, K, T, r = 90.0, 100.0, 1.0, 0.10+ price = bs_price(S, K, T, r, 0.05, "put")+ assert price < K - S # below undiscounted intrinsic, and still valid+ assert implied_volatility(price, S, K, T, r, "put") == pytest.approx(+ 0.05, abs=1e-4+ )++ def test_above_no_arbitrage_ceiling_raises(self) -> None:+ # No volatility takes a call above the present value of the spot.+ with pytest.raises(ValueError, match="ceiling"):+ implied_volatility(101.0, 100.0, 90.0, 1.0, 0.05, "call")++ def test_unconverged_solve_returns_nan_not_a_scipy_exception(self) -> None:+ # brentq raises RuntimeError when it exhausts its own iteration budget.+ # The documented contract for "no volatility found" is nan; a scipy+ # exception type must not leak out of the implementation.+ result = implied_volatility(+ bs_price(100.0, 150.0, 0.25, 0.03, 0.30, "call"),+ 100.0, 150.0, 0.25, 0.03, "call", tol=1e-14, max_iter=1,+ )+ assert math.isnan(result)++ @pytest.mark.parametrize("bad_T", [0.0, -0.5])+ def test_non_positive_expiry_raises(self, bad_T: float) -> None:+ with pytest.raises(ValueError, match="T must be > 0"):+ implied_volatility(5.0, 100.0, 100.0, bad_T, 0.05, "call")++ def test_non_positive_spot_or_strike_raises(self) -> None:+ with pytest.raises(ValueError, match="must be > 0"):+ implied_volatility(5.0, 0.0, 100.0, 1.0, 0.05, "call")+ with pytest.raises(ValueError, match="must be > 0"):+ implied_volatility(5.0, 100.0, -1.0, 1.0, 0.05, "call")+++class TestEdgeCases:+ """Degenerate inputs, and the deep/near-expiry tails."""++ @pytest.mark.parametrize(+ "T, sigma, S, K",+ [(0.0, 0.2, 100.0, 90.0), (-1.0, 0.2, 100.0, 90.0), (1.0, 0.0, 100.0, 90.0),+ (1.0, -0.2, 100.0, 90.0), (1.0, 0.2, 0.0, 90.0), (1.0, 0.2, 100.0, 0.0)],+ )+ def test_degenerate_inputs_return_intrinsic(self, T, sigma, S, K) -> None:+ assert bs_price(S, K, T, 0.05, sigma, "call") == max(S - K, 0.0)+ assert bs_price(S, K, T, 0.05, sigma, "put") == max(K - S, 0.0)++ def test_expiring_in_the_money_option_keeps_unit_delta(self) -> None:+ # The regression the skill's copy had: reporting delta 0 for an option+ # that is certain to be exercised.+ itm_call = bs_greeks(120.0, 100.0, 0.0, 0.05, 0.2, "call")+ assert itm_call["delta"] == 1.0+ itm_put = bs_greeks(80.0, 100.0, 0.0, 0.05, 0.2, "put")+ assert itm_put["delta"] == -1.0+ for degenerate in (itm_call, itm_put):+ assert degenerate["gamma"] == 0.0+ assert degenerate["theta"] == 0.0+ assert degenerate["vega"] == 0.0+ assert degenerate["rho"] == 0.0++ def test_expiring_out_of_the_money_option_has_zero_delta(self) -> None:+ assert bs_greeks(80.0, 100.0, 0.0, 0.05, 0.2, "call")["delta"] == 0.0+ assert bs_greeks(120.0, 100.0, 0.0, 0.05, 0.2, "put")["delta"] == 0.0++ def test_deep_in_the_money_call_approaches_discounted_forward(self) -> None:+ S, K, T, r, sigma = 100.0, 1.0, 1.0, 0.05, 0.20+ price = bs_price(S, K, T, r, sigma, "call")+ assert price == pytest.approx(S - K * math.exp(-r * T), abs=1e-6)+ assert bs_greeks(S, K, T, r, sigma, "call")["delta"] == pytest.approx(1.0, abs=1e-6)++ def test_deep_out_of_the_money_call_is_worthless_but_non_negative(self) -> None:+ price = bs_price(100.0, 1000.0, 0.1, 0.05, 0.20, "call")+ assert 0.0 <= price < 1e-6+ assert bs_greeks(100.0, 1000.0, 0.1, 0.05, 0.20, "call")["delta"] < 1e-6++ def test_near_expiry_converges_to_intrinsic(self) -> None:+ tiny_T = 1e-8+ assert bs_price(110.0, 100.0, tiny_T, 0.05, 0.2, "call") == pytest.approx(+ 10.0, abs=1e-5+ )+ assert bs_price(90.0, 100.0, tiny_T, 0.05, 0.2, "call") == pytest.approx(+ 0.0, abs=1e-5+ )++ def test_price_is_monotone_in_volatility(self) -> None:+ prices = [bs_price(100.0, 105.0, 0.5, 0.03, s, "call") for s in+ (0.05, 0.10, 0.20, 0.40, 0.80)]+ assert prices == sorted(prices)++ @pytest.mark.parametrize("alias", ["CALL", " Call ", "put", "PUT"])+ def test_option_type_is_case_insensitive(self, alias: str) -> None:+ 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", ""])+ 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)+ with pytest.raises(ValueError, match="option_type"):+ bs_greeks(100.0, 100.0, 1.0, 0.05, 0.2, bad)+++def test_engine_and_quantlib_are_the_same_object() -> None:+ """The engine must not carry a second copy of this math."""+ from backtest.engines import options_portfolio++ assert options_portfolio.bs_price is bs_price+ assert options_portfolio.bs_greeks is bs_greeks+++class TestEngineFoldsOptionTypeTheSameWay:+ """Pricing and settlement must not disagree about a leg typed ``"Call"``.++ ``bs_price`` folds case; ``OptionPosition.intrinsic_value`` compares the+ stored string. If the position keeps the raw string, a leg typed ``"Call"``+ is priced as a call at open and settled as a put at expiry, which fabricates+ P&L out of nothing.+ """++ @pytest.mark.parametrize("alias", ["call", "Call", "CALL", " call "])+ def test_stored_type_is_folded(self, alias: str) -> None:+ from backtest.engines.options_portfolio import OptionPosition++ pos = OptionPosition(alias, 100.0, "2026-01-01", 1, 5.0, "2025-10-01", "X")+ assert pos.option_type == "call"++ @pytest.mark.parametrize("alias", ["call", "Call", "CALL"])+ def test_price_and_settlement_agree(self, alias: str) -> None:+ from backtest.engines.options_portfolio import OptionPosition++ pos = OptionPosition(alias, 100.0, "2026-01-01", 1, 5.0, "2025-10-01", "X")+ # Spot above the strike: a call settles at 30, a put at 0.+ assert bs_price(130.0, 100.0, 0.25, 0.03, 0.20, alias) > 29.0+ assert pos.intrinsic_value(130.0) == 30.0++ def test_matching_is_case_insensitive(self) -> None:+ from backtest.engines.options_portfolio import (+ OptionPosition, _find_matching_position, normalise_option_type,+ )++ pos = OptionPosition("Call", 100.0, "2026-01-01", 1, 5.0, "2025-10-01", "X")+ for alias in ("call", "Call", "CALL"):+ assert _find_matching_position(+ [pos], "X", normalise_option_type(alias), 100.0, "2026-01-01"+ ) is pos++ def test_unknown_type_is_rejected_at_construction(self) -> None:+ from backtest.engines.options_portfolio import OptionPosition++ with pytest.raises(ValueError, match="option_type"):+ OptionPosition("c", 100.0, "2026-01-01", 1, 5.0, "2025-10-01", "X")diff --git a/agent/tests/quantlib/test_risk.py b/agent/tests/quantlib/test_risk.pynew file mode 100644index 000000000..b3fd55977--- /dev/null+++ b/agent/tests/quantlib/test_risk.py@@ -0,0 +1,523 @@+"""Tests for src.quantlib.risk.++The sign convention (a loss is a positive number) is asserted directly rather+than assumed, because a flipped sign in this family of functions is silent: the+number still looks plausible, it is just the wrong one.+"""++import numpy as np+import pandas as pd+import pytest+from scipy.stats import genpareto, norm++from src.quantlib.risk import (+ analyze_mc_results,+ fit_gpd_tail,+ historical_cvar,+ historical_var,+ max_drawdown_analysis,+ monte_carlo_gbm,+ parametric_var,+)++# 20 observations, already ascending: -0.10, -0.09, ..., 0.09.+# The 95% VaR order statistic is index floor(0.05 * 20) = 1, i.e. -0.09.+FIXED_RETURNS = np.round(np.arange(-0.10, 0.10, 0.01), 10)+++def test_fixture_is_the_array_the_hand_computations_assume():+ assert FIXED_RETURNS.size == 20+ assert FIXED_RETURNS[0] == pytest.approx(-0.10)+ assert FIXED_RETURNS[1] == pytest.approx(-0.09)+ assert FIXED_RETURNS[-1] == pytest.approx(0.09)+++# --------------------------------------------------------------------------+# historical_var -- hand-computed order statistic+# --------------------------------------------------------------------------+++def test_historical_var_is_the_hand_computed_order_statistic():+ # index floor((1 - 0.95) * 20) = 1 -> second smallest = -0.09 -> loss 0.09+ assert historical_var(FIXED_RETURNS, confidence=0.95) == pytest.approx(0.09)+++def test_historical_var_at_99_takes_the_worst_observation():+ # index floor(0.01 * 20) = 0 -> smallest = -0.10 -> loss 0.10+ assert historical_var(FIXED_RETURNS, confidence=0.99) == pytest.approx(0.10)+++def test_historical_var_is_insensitive_to_input_order_and_container():+ shuffled = np.random.default_rng(0).permutation(FIXED_RETURNS)+ expected = historical_var(FIXED_RETURNS, confidence=0.95)+ assert historical_var(shuffled, confidence=0.95) == pytest.approx(expected)+ assert historical_var(pd.Series(FIXED_RETURNS), confidence=0.95) == pytest.approx(expected)+ assert historical_var(list(FIXED_RETURNS), confidence=0.95) == pytest.approx(expected)+++def test_historical_var_scales_with_square_root_of_time():+ one_day = historical_var(FIXED_RETURNS, confidence=0.95)+ assert historical_var(FIXED_RETURNS, confidence=0.95, horizon=4) == pytest.approx(2 * one_day)+++def test_historical_var_ignores_nan():+ with_nan = np.concatenate([FIXED_RETURNS, [np.nan, np.inf, -np.inf]])+ assert historical_var(with_nan, confidence=0.95) == pytest.approx(0.09)+++# --------------------------------------------------------------------------+# parametric_var -- closed-form normal quantile+# --------------------------------------------------------------------------++[email protected]("confidence", [0.90, 0.95, 0.99])+def test_parametric_var_matches_the_closed_form_normal_quantile(confidence):+ mu = float(FIXED_RETURNS.mean())+ sigma = float(FIXED_RETURNS.std(ddof=1))+ expected = -(mu + norm.ppf(1 - confidence) * sigma)+ assert parametric_var(FIXED_RETURNS, confidence=confidence) == pytest.approx(expected, rel=1e-12)+++def test_parametric_var_on_a_known_mean_and_sigma():+ # A two-point sample: mean 0, and sample std (ddof=1) = sqrt(2) * 0.01,+ # because the ddof=1 denominator is n - 1 = 1, not n.+ returns = np.array([-0.01, 0.01])+ sigma = 0.01 * np.sqrt(2)+ assert float(returns.std(ddof=1)) == pytest.approx(sigma, rel=1e-12)+ expected = -norm.ppf(0.05) * sigma # mu = 0+ assert parametric_var(returns, confidence=0.95) == pytest.approx(expected, rel=1e-12)+++def test_parametric_var_scales_with_square_root_of_time():+ one_day = parametric_var(FIXED_RETURNS)+ assert parametric_var(FIXED_RETURNS, horizon=9) == pytest.approx(3 * one_day)+++def test_parametric_var_is_not_uniformly_below_historical_var():+ """The 'normal fit always understates risk' folklore is false at 95%.++ A fat tail inflates the fitted sigma, which pushes the normal quantile+ outward at moderate confidence while the empirical quantile is still in the+ body. The understatement only appears deep in the tail. Pinned here because+ both the module docstring and SKILL.md previously stated it as absolute.+ """+ above = {c: 0 for c in (0.90, 0.95, 0.99)}+ trials = 120+ for seed in range(trials):+ returns = np.random.default_rng(seed).standard_t(4, 750) * 0.011 - 0.0004+ for confidence in above:+ above[confidence] += parametric_var(returns, confidence) >= historical_var(+ returns, confidence+ )+ assert above[0.90] == trials # parametric is ALWAYS the higher one here+ assert above[0.95] / trials > 0.85 # and usually higher at the 95% default+ assert above[0.99] / trials < 0.15 # only deep in the tail does it understate+++def test_parametric_var_needs_two_observations():+ with pytest.raises(ValueError, match="at least 2 observations"):+ parametric_var([0.01])+++# --------------------------------------------------------------------------+# Sign convention -- a loss is positive+# --------------------------------------------------------------------------+++def test_var_of_a_losing_series_is_positive():+ losses = np.linspace(-0.20, -0.01, 50) # every observation is a loss+ assert historical_var(losses) > 0+ assert parametric_var(losses) > 0+ assert historical_cvar(losses) > 0+++def test_var_of_a_uniformly_profitable_series_is_negative():+ # Sign convention is not clipped: no loss in the tail reports a negative+ # "loss", i.e. a gain. Asserting this pins the direction of the convention.+ gains = np.linspace(0.01, 0.20, 50)+ assert historical_var(gains) < 0+ assert parametric_var(gains) < 0+ assert historical_cvar(gains) < 0+++def test_the_documented_invariant_is_cvar_ge_var_and_not_var_ge_zero():+ # The module docstring used to claim `cvar >= var >= 0` "by construction".+ # The right half is false and the left half is the one worth relying on:+ # ordering always holds, non-negativity does not.+ gains = np.linspace(0.01, 0.20, 50)+ assert historical_cvar(gains) >= historical_var(gains)+ assert historical_var(gains) < 0.0 # refutes `var >= 0`+ summary = analyze_mc_results(_paths_with_terminal_returns(gains))+ assert summary["cvar"] >= summary["var"]+ assert summary["var"] < 0.0+++def test_max_drawdown_is_reported_as_a_positive_fraction():+ equity = pd.Series([100.0, 50.0, 60.0])+ assert max_drawdown_analysis(equity)["max_drawdown"] == pytest.approx(0.5)+++def test_a_bigger_loss_is_a_bigger_number_for_every_measure():+ mild = FIXED_RETURNS+ severe = FIXED_RETURNS * 2.0+ assert historical_var(severe) > historical_var(mild)+ assert parametric_var(severe) > parametric_var(mild)+ assert historical_cvar(severe) > historical_cvar(mild)+++# --------------------------------------------------------------------------+# historical_cvar -- hand-computed, and cvar >= var always+# --------------------------------------------------------------------------+++def test_historical_cvar_is_the_hand_computed_tail_mean():+ # Tail at 95% is everything at or below the VaR order statistic (-0.09),+ # i.e. {-0.10, -0.09}; mean -0.095 -> loss 0.095.+ assert historical_cvar(FIXED_RETURNS, confidence=0.95) == pytest.approx(0.095)+++def test_historical_cvar_at_99_is_the_single_worst_observation():+ assert historical_cvar(FIXED_RETURNS, confidence=0.99) == pytest.approx(0.10)++[email protected]("confidence", [0.80, 0.90, 0.95, 0.975, 0.99])[email protected]("seed", range(8))+def test_cvar_is_never_below_var(confidence, seed):+ rng = np.random.default_rng(seed)+ # Skewed, fat-tailed draws -- the regime where a naive tail mask breaks.+ returns = rng.standard_t(df=3, size=500) * 0.01 - 0.002+ var = historical_var(returns, confidence=confidence)+ cvar = historical_cvar(returns, confidence=confidence)+ assert cvar >= var+++def test_cvar_is_never_below_var_on_the_fixed_array():+ for confidence in (0.5, 0.8, 0.9, 0.95, 0.99):+ assert historical_cvar(FIXED_RETURNS, confidence) >= historical_var(FIXED_RETURNS, confidence)+++# --------------------------------------------------------------------------+# Input validation shared by the VaR family+# --------------------------------------------------------------------------++[email protected]("fn", [historical_var, parametric_var, historical_cvar])[email protected]("confidence", [0.0, 1.0, -0.1, 1.5])+def test_confidence_must_be_a_strict_probability(fn, confidence):+ with pytest.raises(ValueError, match="confidence"):+ fn(FIXED_RETURNS, confidence=confidence)++[email protected]("fn", [historical_var, parametric_var, historical_cvar])+def test_horizon_must_be_at_least_one(fn):+ with pytest.raises(ValueError, match="horizon"):+ fn(FIXED_RETURNS, horizon=0)++[email protected]("fn", [historical_var, parametric_var, historical_cvar])+def test_empty_input_is_rejected(fn):+ with pytest.raises(ValueError, match="no finite observation"):+ fn([np.nan, np.nan])+++# --------------------------------------------------------------------------+# max_drawdown_analysis -- hand-built path, known peak / trough / recovery+# --------------------------------------------------------------------------+++def _dated(values):+ """Attach consecutive calendar days starting 2024-01-01 to a value list."""+ return pd.Series(values, index=pd.date_range("2024-01-01", periods=len(values), freq="D"))+++def test_max_drawdown_finds_the_hand_built_peak_trough_and_recovery():+ # 01-01 01-02 01-03 01-04 01-05 01-06+ # value 100 110 120 90 100 121+ # peak 100 110 120 120 120 121+ # dd 0 0 0 -0.25 -0.1667 0+ equity = _dated([100.0, 110.0, 120.0, 90.0, 100.0, 121.0])+ result = max_drawdown_analysis(equity)++ assert result["max_drawdown"] == pytest.approx(0.25)+ assert result["peak_date"] == pd.Timestamp("2024-01-03")+ assert result["trough_date"] == pd.Timestamp("2024-01-04")+ assert result["recovery_date"] == pd.Timestamp("2024-01-06")+ assert result["recovered"] is True+ assert result["peak_to_trough_periods"] == 1+ assert result["trough_to_recovery_periods"] == 2+ assert result["underwater_days"] == 1+ assert result["recovery_days"] == 2+++def test_max_drawdown_recovery_needs_the_peak_value_not_a_partial_bounce():+ # Bounces to 119.99, one cent short of the 120 peak -> still underwater.+ equity = _dated([100.0, 120.0, 90.0, 119.99])+ result = max_drawdown_analysis(equity)+ assert result["max_drawdown"] == pytest.approx(0.25)+ assert result["recovery_date"] is None+ assert result["recovered"] is False+ assert result["trough_to_recovery_periods"] is None+ assert result["recovery_days"] is None+++def test_max_drawdown_picks_the_deepest_of_two_drawdowns():+ # First drawdown 100 -> 80 (20%), second 130 -> 91 (30%).+ equity = _dated([100.0, 80.0, 100.0, 130.0, 91.0, 140.0])+ result = max_drawdown_analysis(equity)+ assert result["max_drawdown"] == pytest.approx(0.30)+ assert result["peak_date"] == pd.Timestamp("2024-01-04")+ assert result["trough_date"] == pd.Timestamp("2024-01-05")+ assert result["recovery_date"] == pd.Timestamp("2024-01-06")+++def test_max_drawdown_of_a_monotonically_rising_curve_is_zero():+ result = max_drawdown_analysis(_dated([100.0, 101.0, 102.0]))+ assert result["max_drawdown"] == pytest.approx(0.0)+ assert result["recovered"] is True+ assert result["recovery_days"] == 0+++def test_max_drawdown_without_a_datetime_index_omits_calendar_days():+ result = max_drawdown_analysis([100.0, 120.0, 90.0, 130.0])+ assert result["max_drawdown"] == pytest.approx(0.25)+ assert result["peak_date"] == 1+ assert result["trough_date"] == 2+ assert result["recovery_date"] == 3+ assert result["underwater_days"] is None+ assert result["recovery_days"] is None+ assert result["peak_to_trough_periods"] == 1+++def test_max_drawdown_drops_nan_and_keeps_the_surviving_index_labels():+ equity = _dated([100.0, np.nan, 120.0, 90.0, 130.0])+ result = max_drawdown_analysis(equity)+ assert result["max_drawdown"] == pytest.approx(0.25)+ assert result["peak_date"] == pd.Timestamp("2024-01-03")+ assert result["trough_date"] == pd.Timestamp("2024-01-04")+ assert result["recovery_date"] == pd.Timestamp("2024-01-05")+ # Period counts are in surviving observations; calendar days use the index.+ assert result["peak_to_trough_periods"] == 1+ assert result["underwater_days"] == 1+++def test_max_drawdown_rejects_an_all_nan_series():+ with pytest.raises(ValueError, match="no finite observation"):+ max_drawdown_analysis([np.nan, np.nan])+++def test_max_drawdown_rejects_non_positive_equity():+ with pytest.raises(ValueError, match="strictly positive"):+ max_drawdown_analysis([100.0, 0.0, 50.0])+++# --------------------------------------------------------------------------+# monte_carlo_gbm -- reproducibility and drift+# --------------------------------------------------------------------------+++def test_gbm_is_reproducible_under_a_fixed_seed():+ a = monte_carlo_gbm(100.0, 0.08, 0.20, n_steps=30, n_paths=200, seed=42)+ b = monte_carlo_gbm(100.0, 0.08, 0.20, n_steps=30, n_paths=200, seed=42)+ assert np.array_equal(a, b)+++def test_gbm_differs_under_a_different_seed():+ a = monte_carlo_gbm(100.0, 0.08, 0.20, n_steps=30, n_paths=200, seed=42)+ c = monte_carlo_gbm(100.0, 0.08, 0.20, n_steps=30, n_paths=200, seed=43)+ assert not np.array_equal(a, c)+++def test_gbm_shape_starts_at_s0():+ paths = monte_carlo_gbm(50.0, 0.05, 0.15, n_steps=10, n_paths=7, seed=1)+ assert paths.shape == (7, 11)+ assert np.all(paths[:, 0] == 50.0)+ assert np.all(paths > 0)+++def test_gbm_with_zero_volatility_is_the_deterministic_drift_path():+ s0, mu, n_steps = 100.0, 0.10, 252+ paths = monte_carlo_gbm(s0, mu, 0.0, n_steps=n_steps, n_paths=3, seed=0)+ expected_terminal = s0 * np.exp((mu - 0.0) * n_steps / 252)+ assert paths[:, -1] == pytest.approx(expected_terminal, rel=1e-12)+++def test_gbm_mean_terminal_price_drifts_as_expected_over_many_paths():+ s0, mu, sigma, n_steps, n_paths = 100.0, 0.10, 0.20, 63, 60_000+ paths = monte_carlo_gbm(s0, mu, sigma, n_steps=n_steps, n_paths=n_paths, seed=2026)+ # E[S_T] = S0 * exp(mu * T) with T in years.+ years = n_steps / 252+ expected = s0 * np.exp(mu * years)+ observed = float(paths[:, -1].mean())+ # Monte Carlo standard error of the mean, times 4 -> a ~1-in-16k false alarm.+ stderr = expected * np.sqrt(np.exp(sigma**2 * years) - 1) / np.sqrt(n_paths)+ assert abs(observed - expected) < 4 * stderr+++def test_gbm_median_terminal_price_follows_the_log_drift():+ s0, mu, sigma, n_steps, n_paths = 100.0, 0.10, 0.20, 252, 40_000+ paths = monte_carlo_gbm(s0, mu, sigma, n_steps=n_steps, n_paths=n_paths, seed=7)+ expected_median = s0 * np.exp((mu - 0.5 * sigma**2) * n_steps / 252)+ assert float(np.median(paths[:, -1])) == pytest.approx(expected_median, rel=0.02)+++ "kwargs, match",+ [+ ({"s0": 0.0}, "s0"),+ ({"sigma": -0.1}, "sigma"),+ ({"n_steps": 0}, "n_steps"),+ ({"n_paths": 0}, "n_paths"),+ ({"steps_per_year": 0}, "steps_per_year"),+ ],+)+def test_gbm_rejects_impossible_parameters(kwargs, match):+ args = {"s0": 100.0, "mu": 0.05, "sigma": 0.2, "n_steps": 10, "n_paths": 5}+ args.update(kwargs)+ with pytest.raises(ValueError, match=match):+ monte_carlo_gbm(**args, seed=0)+++# --------------------------------------------------------------------------+# analyze_mc_results+# --------------------------------------------------------------------------+++def _paths_with_terminal_returns(returns):+ """Build a two-column price matrix whose terminal returns are exactly `returns`."""+ returns = np.asarray(returns, dtype=float)+ return np.column_stack([np.ones_like(returns), 1.0 + returns])+++def test_analyze_mc_results_reuses_the_var_convention():+ summary = analyze_mc_results(_paths_with_terminal_returns(FIXED_RETURNS), confidence=0.95)+ assert summary["var"] == pytest.approx(0.09)+ assert summary["cvar"] == pytest.approx(0.095)+ assert summary["cvar"] >= summary["var"]+ assert summary["mean_return"] == pytest.approx(FIXED_RETURNS.mean())+ assert summary["median_return"] == pytest.approx(np.median(FIXED_RETURNS))+ assert summary["prob_loss"] == pytest.approx(0.5) # 10 of 20 are negative+ # Signed return percentiles, linear interpolation: -0.10 + 0.95 * 0.01.+ assert summary["worst_5pct_return"] == pytest.approx(-0.0905)+ assert summary["best_5pct_return"] == pytest.approx(0.0805)+++def test_analyze_mc_results_tail_mask_is_not_fooled_by_an_all_negative_sample():+ # The classic bug is comparing returns against +VaR instead of -VaR, which+ # on an all-loss sample selects nearly every path and understates the tail.+ returns = np.linspace(-0.50, -0.01, 100)+ summary = analyze_mc_results(_paths_with_terminal_returns(returns), confidence=0.95)+ assert summary["prob_loss"] == pytest.approx(1.0)+ assert summary["cvar"] >= summary["var"] > 0+ # Tail of 5 worst of 100: index floor(0.05 * 100) = 5 -> 6 observations.+ assert summary["cvar"] == pytest.approx(-np.sort(returns)[:6].mean())+++def test_analyze_mc_results_on_a_simulated_run():+ paths = monte_carlo_gbm(100.0, 0.10, 0.20, n_steps=252, n_paths=20_000, seed=11)+ summary = analyze_mc_results(paths, confidence=0.95)+ assert summary["mean_return"] == pytest.approx(np.exp(0.10) - 1, rel=0.05)+ assert summary["cvar"] >= summary["var"] > 0+ assert 0.0 < summary["prob_loss"] < 1.0+ assert summary["worst_5pct_return"] < summary["median_return"] < summary["best_5pct_return"]+++def test_analyze_mc_results_rejects_a_one_column_matrix():+ with pytest.raises(ValueError, match=">= 2 columns"):+ analyze_mc_results(np.ones((5, 1)))+++# --------------------------------------------------------------------------+# fit_gpd_tail -- recover a generated shape parameter+# --------------------------------------------------------------------------+++def _series_with_gpd_left_tail(shape, scale, n_tail, seed):+ """Return a series whose worst 5% are exactly GPD(shape, scale) losses.++ The body sits just above zero and the tail just below it, so the 5th+ percentile lands at the boundary and the exceedances recovered by+ fit_gpd_tail are the generated GPD draws.+ """+ rng = np.random.default_rng(seed)+ losses = genpareto.rvs(shape, loc=0.0, scale=scale, size=n_tail, random_state=rng)+ body = rng.uniform(1e-9, 0.05, size=n_tail * 19) # tail is 5% of the total+ return np.concatenate([-losses, body])++[email protected]("true_shape", [0.30, 0.10, -0.20])+def test_fit_gpd_tail_recovers_the_generated_shape(true_shape):+ returns = _series_with_gpd_left_tail(true_shape, scale=0.02, n_tail=4000, seed=5)+ fit = fit_gpd_tail(returns, threshold_pct=5.0)+ assert fit["shape_xi"] == pytest.approx(true_shape, abs=0.06)+ assert fit["scale_sigma"] == pytest.approx(0.02, rel=0.15)+ assert fit["n_exceedances"] == 4000+ assert fit["exceedance_rate"] == pytest.approx(0.05, abs=0.001)+++def test_fit_gpd_tail_labels_a_fat_tail():+ returns = _series_with_gpd_left_tail(0.40, scale=0.02, n_tail=3000, seed=9)+ assert fit_gpd_tail(returns)["tail_type"] == "fat"+++def test_fit_gpd_tail_labels_a_bounded_tail():+ returns = _series_with_gpd_left_tail(-0.35, scale=0.02, n_tail=3000, seed=9)+ assert fit_gpd_tail(returns)["tail_type"] == "bounded"+++def test_fit_gpd_tail_labels_a_true_exponential_tail_exponential():+ # Regression: classifying on `shape > 0.0` made "exponential" unreachable,+ # because a float MLE is never exactly zero. A true exponential tail was+ # then labelled "fat" (i.e. dangerous) on the sign of estimation noise.+ labels = []+ for seed in range(12):+ rng = np.random.default_rng(100 + seed)+ losses = rng.exponential(0.02, size=2000) # GPD with shape exactly 0+ body = rng.uniform(1e-9, 0.05, size=2000 * 19)+ labels.append(fit_gpd_tail(np.concatenate([-losses, body]))["tail_type"])+ # Measured coverage of the 2-sigma band on this generator is 96.5% over 200+ # refits; 11 of 12 is the conservative assertion for a 12-refit sample.+ assert labels.count("exponential") >= 11, labels+++def test_fit_gpd_tail_reports_a_shape_stderr_matching_the_refit_spread():+ # The classification band must be a real standard error, not a magic+ # constant: refit the same shape 12 times and compare the spread.+ shapes, reported = [], []+ for seed in range(12):+ rng = np.random.default_rng(200 + seed)+ losses = genpareto.rvs(0.20, loc=0.0, scale=0.02, size=2000, random_state=rng)+ body = rng.uniform(1e-9, 0.05, size=2000 * 19)+ fit = fit_gpd_tail(np.concatenate([-losses, body]))+ shapes.append(fit["shape_xi"])+ reported.append(fit["shape_stderr"])+ assert float(np.std(shapes)) == pytest.approx(float(np.mean(reported)), rel=0.35)+ # And the closed form it claims to be.+ assert reported[0] == pytest.approx(abs(1.0 + shapes[0]) / np.sqrt(2000), rel=1e-12)+++def test_fit_gpd_tail_still_calls_an_unambiguous_shape_by_its_name():+ # The band must not swallow shapes that are many standard errors from zero.+ fat = fit_gpd_tail(_series_with_gpd_left_tail(0.40, scale=0.02, n_tail=3000, seed=9))+ bounded = fit_gpd_tail(_series_with_gpd_left_tail(-0.35, scale=0.02, n_tail=3000, seed=9))+ assert fat["tail_type"] == "fat"+ assert bounded["tail_type"] == "bounded"+ assert fat["shape_xi"] > 5 * fat["shape_stderr"]+ assert bounded["shape_xi"] < -5 * bounded["shape_stderr"]+++def test_fit_gpd_tail_threshold_is_the_requested_percentile():+ returns = np.linspace(-0.10, 0.10, 1001)+ fit = fit_gpd_tail(returns, threshold_pct=10.0)+ assert fit["threshold"] == pytest.approx(np.percentile(returns, 10.0))+ assert fit["n_exceedances"] == 100+++def test_fit_gpd_tail_rejects_a_threshold_with_too_few_exceedances():+ with pytest.raises(ValueError, match="at least 2 exceedances"):+ fit_gpd_tail(np.linspace(-0.1, 0.1, 20), threshold_pct=1.0)++[email protected]("threshold_pct", [0.0, 100.0, -5.0, 120.0])+def test_fit_gpd_tail_rejects_an_out_of_range_threshold(threshold_pct):+ with pytest.raises(ValueError, match="threshold_pct"):+ fit_gpd_tail(FIXED_RETURNS, threshold_pct=threshold_pct)diff --git a/agent/tests/quantlib/test_timeseries.py b/agent/tests/quantlib/test_timeseries.pynew file mode 100644index 000000000..3e31a5c9e--- /dev/null+++ b/agent/tests/quantlib/test_timeseries.py@@ -0,0 +1,664 @@+"""Tests for src.quantlib.timeseries.++Every test builds its data from a seeded generator with a known ground truth, so+an assertion failure means the estimator moved, not that the market did. The+null-hypothesis cases are parametrised across eight seeds rather than run on one+hand-picked seed, so a lucky draw cannot make them pass.+"""++from __future__ import annotations++import numpy as np+import pandas as pd+import pytest++from src.quantlib.timeseries import (+ adf_test,+ autocorrelation_test,+ bootstrap_sharpe,+ bootstrap_statistic,+ cointegration_test,+ compute_half_life,+ find_hedge_ratio,+ fit_garch,+ granger_test,+ heteroscedasticity_test,+ vif_test,+)++pytestmark = pytest.mark.unit++NULL_CASE_SEEDS = [0, 1, 2, 3, 4, 5, 6, 7]+++def ar1(phi: float, n: int, seed: int, sigma: float = 1.0) -> np.ndarray:+ """Generate a mean-zero AR(1) series, the discrete analogue of an OU process.++ Args:+ phi: Persistence coefficient; |phi| < 1 gives a stationary series.+ n: Number of observations.+ seed: Seed for the random generator.+ sigma: Standard deviation of the innovations.++ Returns:+ The generated series as a 1-D numpy array.+ """+ rng = np.random.default_rng(seed)+ shocks = rng.standard_normal(n) * sigma+ out = np.empty(n)+ out[0] = shocks[0]+ for i in range(1, n):+ out[i] = phi * out[i - 1] + shocks[i]+ return out+++def random_walk(n: int, seed: int) -> np.ndarray:+ """Generate a driftless random walk (a unit-root, non-stationary series).++ Args:+ n: Number of observations.+ seed: Seed for the random generator.++ Returns:+ The cumulative-sum series as a 1-D numpy array.+ """+ return np.cumsum(np.random.default_rng(seed).standard_normal(n))+++# ─── ADF ───+++def test_adf_rejects_unit_root_on_stationary_series():+ result = adf_test(pd.Series(ar1(phi=0.5, n=1500, seed=0)))++ assert result["is_stationary"] is True+ assert result["p_value"] < 0.01+ assert result["adf_statistic"] < result["critical_values"]["1%"]++[email protected]("seed", NULL_CASE_SEEDS)+def test_adf_fails_to_reject_on_random_walk(seed):+ result = adf_test(pd.Series(random_walk(1500, seed)))++ assert result["is_stationary"] is False+ assert result["p_value"] > 0.05+++def test_adf_significance_level_is_configurable():+ walk = pd.Series(random_walk(1500, seed=7)) # p ≈ 0.0625, straddles the two levels++ assert adf_test(walk, significance=0.05)["is_stationary"] is False+ assert adf_test(walk, significance=0.10)["is_stationary"] is True+++def test_adf_return_shape():+ result = adf_test(pd.Series(ar1(0.5, 500, seed=1)))++ assert set(result) == {"adf_statistic", "p_value", "lags_used", "is_stationary", "critical_values"}+ assert set(result["critical_values"]) == {"1%", "5%", "10%"}+ assert isinstance(result["lags_used"], int)+++def test_adf_rejects_too_short_a_series():+ with pytest.raises(ValueError, match="at least 2"):+ adf_test(pd.Series([1.0]))+++# ─── Cointegration ───+++def test_cointegration_found_on_constructed_pair():+ # y and x are both I(1) random walks, but y - 2.5x is a stationary AR(1),+ # so the pair is cointegrated by construction.+ x = random_walk(1500, seed=10)+ y = 2.5 * x + 1.0 + ar1(phi=0.9, n=1500, seed=11)++ result = cointegration_test(pd.Series(y), pd.Series(x))++ assert result["is_cointegrated"] is True+ assert result["p_value"] < 0.01++[email protected]("seed", NULL_CASE_SEEDS)+def test_cointegration_not_found_on_independent_walks(seed):+ rng = np.random.default_rng(seed)+ a = np.cumsum(rng.standard_normal(1500))+ b = np.cumsum(rng.standard_normal(1500))++ result = cointegration_test(pd.Series(a), pd.Series(b))++ assert result["is_cointegrated"] is False+ assert result["p_value"] > 0.05+++def test_cointegration_return_shape():+ x = random_walk(400, seed=12)+ result = cointegration_test(pd.Series(2.0 * x + ar1(0.5, 400, 13)), pd.Series(x))++ assert set(result) == {"test_statistic", "p_value", "is_cointegrated", "critical_values"}+ assert set(result["critical_values"]) == {"1%", "5%", "10%"}+++def test_cointegration_rejects_mismatched_lengths():+ with pytest.raises(ValueError, match="equal-length"):+ cointegration_test(pd.Series(np.arange(10.0)), pd.Series(np.arange(11.0)))+++def test_cointegration_refuses_to_join_two_different_indices_positionally():+ # Two same-length legs on disjoint indices used to be zipped positionally,+ # which reports a spurious cointegration on data that never overlapped. The+ # pair workflow runs this and find_hedge_ratio on the same two legs, so both+ # must enforce the same contract.+ a = pd.Series(random_walk(200, seed=14), index=pd.RangeIndex(0, 200))+ b = pd.Series(random_walk(200, seed=15), index=pd.RangeIndex(500, 700))++ with pytest.raises(ValueError, match="sharing one index"):+ cointegration_test(a, b)+ with pytest.raises(ValueError, match="sharing one index"):+ find_hedge_ratio(a, b)+++def test_cointegration_still_accepts_a_shared_non_default_index():+ dates = pd.date_range("2020-01-01", periods=400, freq="D")+ x = random_walk(400, seed=16)+ y = 2.0 * x + ar1(0.5, 400, 17)++ result = cointegration_test(pd.Series(y, index=dates), pd.Series(x, index=dates))++ assert result["is_cointegrated"] is True+ # And matches the plain positional call on the same numbers.+ assert result["test_statistic"] == pytest.approx(+ cointegration_test(pd.Series(y), pd.Series(x))["test_statistic"]+ )+++# ─── Hedge ratio and half-life ───+++def test_find_hedge_ratio_recovers_known_beta():+ true_beta, true_alpha = 2.5, 1.0+ x = random_walk(3000, seed=20)+ y = true_alpha + true_beta * x + ar1(phi=0.9, n=3000, seed=21)++ result = find_hedge_ratio(pd.Series(y), pd.Series(x))++ assert result["hedge_ratio"] == pytest.approx(true_beta, abs=0.05)+ assert result["intercept"] == pytest.approx(true_alpha, abs=0.5)+ # spread = y - beta*x is the OLS residual plus the intercept, so its mean+ # sits at alpha and its dispersion is the AR(1) noise, not the walk's.+ assert result["spread_std"] < 10.0+ assert result["half_life"] > 0+++def test_find_hedge_ratio_matches_the_closed_form_ols():+ # Independent reference, not a statsmodels round-trip: the simple-regression+ # slope is cov(x, y) / var(x) and the intercept is ybar - beta * xbar.+ x = random_walk(600, seed=24)+ y = 1.7 + 3.1 * x + ar1(0.4, 600, 25)++ result = find_hedge_ratio(pd.Series(y), pd.Series(x))++ beta = np.cov(x, y, ddof=1)[0, 1] / np.var(x, ddof=1)+ assert result["hedge_ratio"] == pytest.approx(beta, rel=1e-12)+ assert result["intercept"] == pytest.approx(y.mean() - beta * x.mean(), rel=1e-10)+ assert result["spread_std"] == pytest.approx((y - beta * x).std(ddof=1), rel=1e-12)+++def test_find_hedge_ratio_return_shape():+ x = random_walk(500, seed=22)+ result = find_hedge_ratio(pd.Series(1.5 * x + ar1(0.5, 500, 23)), pd.Series(x))++ assert set(result) == {"hedge_ratio", "intercept", "spread_mean", "spread_std", "half_life"}+ assert all(isinstance(v, float) for v in result.values())+++def test_compute_half_life_recovers_ou_process():+ # For an AR(1) with coefficient phi the continuous-time half-life is+ # -ln(2)/ln(phi); the delta-regression estimator targets -ln(2)/(phi-1),+ # which differs by ~5% at phi=0.9. Tolerance spans both conventions.+ phi = 0.9+ expected = -np.log(2) / np.log(phi)++ estimated = compute_half_life(pd.Series(ar1(phi=phi, n=20000, seed=30)))++ assert estimated == pytest.approx(expected, rel=0.15)+++def test_compute_half_life_is_infinite_for_a_random_walk():+ # A random walk never reverts; the estimated reversion coefficient hovers+ # around zero, and a non-negative one means "no reversion", not "instant".+ values = [compute_half_life(pd.Series(random_walk(2000, seed))) for seed in NULL_CASE_SEEDS]++ assert all(v > 100 for v in values), values+++def test_compute_half_life_aligns_around_interior_nans():+ # Dropping levels and deltas independently would mis-pair rows after a gap.+ series = pd.Series(ar1(phi=0.9, n=800, seed=31))+ series.iloc[400] = np.nan++ assert compute_half_life(series) == pytest.approx(-np.log(2) / np.log(0.9), rel=0.35)+++def test_compute_half_life_rejects_too_short_a_series():+ with pytest.raises(ValueError, match="at least 3"):+ compute_half_life(pd.Series([1.0, 2.0]))+++def test_degenerate_flat_regressors_raise_instead_of_leaking_an_index_error():+ # `sm.add_constant` defaults to has_constant='skip', so a already-constant+ # column leaves the design one column wide and the slope lookup used to blow+ # up with a bare `IndexError: index 1 is out of bounds`. Both entry points+ # must refuse the input by contract instead.+ with pytest.raises(ValueError, match="constant"):+ compute_half_life(pd.Series(np.full(50, 2.0)))+ with pytest.raises(ValueError, match="constant"):+ find_hedge_ratio(pd.Series(ar1(0.5, 50, seed=32)), pd.Series(np.full(50, 3.0)))+++# ─── Granger ───+++def test_granger_detects_a_lagged_driver():+ rng = np.random.default_rng(40)+ n = 600+ x = rng.standard_normal(n)+ y = np.roll(x, 1) * 0.8 + rng.standard_normal(n) * 0.3+ frame = pd.DataFrame({"y": y[1:], "x": x[1:]})++ result = granger_test(frame, x_col="x", y_col="y", max_lag=3)++ assert set(result) == {1, 2, 3}+ assert result[1] < 0.01+++def test_granger_finds_nothing_between_independent_noise():+ rng = np.random.default_rng(41)+ frame = pd.DataFrame({"y": rng.standard_normal(600), "x": rng.standard_normal(600)})++ result = granger_test(frame, x_col="x", y_col="y", max_lag=3)++ assert all(p > 0.05 for p in result.values()), result+++def test_granger_stays_silent_on_stdout(capsys):+ # statsmodels >= 0.14 prints its whole test table unconditionally.+ rng = np.random.default_rng(42)+ frame = pd.DataFrame({"y": rng.standard_normal(200), "x": rng.standard_normal(200)})++ granger_test(frame, x_col="x", y_col="y", max_lag=2)++ assert capsys.readouterr().out == ""+++def test_granger_rejects_a_missing_column():+ frame = pd.DataFrame({"y": [1.0, 2.0, 3.0]})+ with pytest.raises(KeyError, match="not in data"):+ granger_test(frame, x_col="absent", y_col="y")+++# ─── Regression diagnostics ───+++def test_heteroscedasticity_detected_when_variance_scales_with_x():+ sm = pytest.importorskip("statsmodels.api")+ rng = np.random.default_rng(50)+ x = np.linspace(1, 10, 500)+ y = 2 * x + rng.standard_normal(500) * x # noise grows with x+ fitted = sm.OLS(y, sm.add_constant(x)).fit()++ result = heteroscedasticity_test(fitted)++ assert result["has_heteroscedasticity"] is True+ assert result["white_p"] < 0.05+ assert "HAC" in result["fix"]+++def test_heteroscedasticity_absent_under_constant_variance():+ sm = pytest.importorskip("statsmodels.api")+ rng = np.random.default_rng(51)+ x = np.linspace(1, 10, 500)+ fitted = sm.OLS(2 * x + rng.standard_normal(500), sm.add_constant(x)).fit()++ result = heteroscedasticity_test(fitted)++ assert result["has_heteroscedasticity"] is False+ assert result["fix"] == "No adjustment needed"+++def test_heteroscedasticity_advice_never_contradicts_the_verdict():+ # Keying `fix` off white_p alone -- as the skill's markdown did -- returns+ # "No adjustment needed" next to has_heteroscedasticity=True whenever only+ # the BP test rejects. Seed 157 below is exactly that case: white_p 0.0572,+ # bp_p 0.0196. Scan a band of seeds so the pairing is asserted, not the seed.+ sm = pytest.importorskip("statsmodels.api")+ saw_bp_only = False+ for seed in range(200):+ rng = np.random.default_rng(seed)+ x = np.linspace(1, 10, 120)+ y = 2 * x + rng.standard_normal(120) * (1 + 0.35 * x)+ result = heteroscedasticity_test(sm.OLS(y, sm.add_constant(x)).fit())++ expected = "Use HAC" if result["has_heteroscedasticity"] else "No adjustment needed"+ assert result["fix"].startswith(expected), (seed, result)+ saw_bp_only |= result["bp_p"] < 0.05 <= result["white_p"]++ assert saw_bp_only, "no BP-only rejection in 200 seeds; the regression is not being exercised"+++def test_autocorrelation_detected_in_ar1_residuals():+ result = autocorrelation_test(pd.Series(ar1(phi=0.8, n=1000, seed=60)), lags=10)++ assert result["has_autocorrelation"] is True+ assert result["durbin_watson"] < 1.5+ assert result["dw_interpretation"] == "positive autocorrelation"+ assert len(result["ljung_box_p"]) == 10+++def test_autocorrelation_absent_in_white_noise():+ # `has_autocorrelation` is any-of-`lags`, so on white noise it fires on a+ # minority of seeds by construction (see the calibration test below).+ # Assert the rate across seeds instead of picking one lucky path.+ flagged = 0+ for seed in range(40):+ noise = pd.Series(np.random.default_rng(3000 + seed).standard_normal(2000))+ result = autocorrelation_test(noise, lags=10)+ flagged += result["has_autocorrelation"]+ assert 1.5 <= result["durbin_watson"] < 2.5+ assert result["dw_interpretation"] == "no autocorrelation"++ assert flagged <= 12, f"{flagged}/40 white-noise paths flagged; expected roughly 5"+++def test_ljung_box_any_lag_rule_inflates_the_false_positive_rate():+ # Characterisation, not aspiration: the promoted `any(p < significance)`+ # rule runs `lags` hypothesis tests at once, so its family-wise error rate+ # sits well above the nominal level. Callers must know this before reading+ # a single flag as a 5%-level rejection.+ lag1_flags = lag10_flags = 0+ for seed in range(120):+ noise = pd.Series(np.random.default_rng(5000 + seed).standard_normal(1500))+ lag1_flags += autocorrelation_test(noise, lags=1)["has_autocorrelation"]+ lag10_flags += autocorrelation_test(noise, lags=10)["has_autocorrelation"]++ assert lag1_flags <= 15, f"lag-1 false positives {lag1_flags}/120 should sit near the nominal 5%"+ assert lag10_flags > lag1_flags, (lag1_flags, lag10_flags)+++def test_autocorrelation_flags_alternating_series_as_negative():+ alternating = pd.Series(np.tile([1.0, -1.0], 200) + np.random.default_rng(62).standard_normal(400) * 0.1)++ assert autocorrelation_test(alternating, lags=5)["dw_interpretation"] == "negative autocorrelation"+++def test_vif_flags_a_collinear_column():+ rng = np.random.default_rng(70)+ a = rng.standard_normal(500)+ frame = pd.DataFrame({"a": a, "b": a + rng.standard_normal(500) * 0.01, "c": rng.standard_normal(500)})++ result = vif_test(frame)++ assert list(result.columns) == ["feature", "VIF", "concern"]+ assert list(result["feature"]) == ["a", "b", "c"]+ by_feature = dict(zip(result["feature"], result["concern"]))+ assert by_feature["a"] == "severe"+ assert by_feature["b"] == "severe"+ assert by_feature["c"] == "normal"+++def test_vif_thresholds_are_configurable():+ rng = np.random.default_rng(71)+ frame = pd.DataFrame({"a": rng.standard_normal(300), "b": rng.standard_normal(300)})++ # Independent columns have VIF ≈ 1; a threshold below 1 must flag them.+ relaxed = vif_test(frame, severe_threshold=0.5, watch_threshold=0.1)++ assert set(relaxed["concern"]) == {"severe"}+ assert set(vif_test(frame)["concern"]) == {"normal"}+++def test_vif_thresholds_are_strict_inequalities():+ # A VIF landing exactly on the threshold is NOT flagged. Pinned because the+ # docstring previously said "at or above", which is the opposite rule.+ rng = np.random.default_rng(72)+ frame = pd.DataFrame({"a": rng.standard_normal(300), "b": rng.standard_normal(300)})+ exact = float(vif_test(frame)["VIF"].iloc[0])++ on_threshold = vif_test(frame, severe_threshold=exact, watch_threshold=exact)+ assert on_threshold["concern"].iloc[0] == "normal"+ assert vif_test(frame, severe_threshold=exact / 2, watch_threshold=exact / 4)["concern"].iloc[0] == "severe"+++def test_vif_rejects_an_empty_frame():+ with pytest.raises(ValueError, match="at least one column"):+ vif_test(pd.DataFrame())+++# ─── Bootstrap ───+++def test_bootstrap_ci_covers_the_true_mean():+ true_mean = 0.5+ data = np.random.default_rng(80).standard_normal(500) + true_mean++ result = bootstrap_statistic(data, np.mean, n_bootstrap=2000, confidence=0.95, seed=1)++ assert result["ci_lower"] < true_mean < result["ci_upper"]+ assert result["point_estimate"] == pytest.approx(float(np.mean(data)))+ assert result["bootstrap_mean"] == pytest.approx(result["point_estimate"], abs=0.02)+ assert result["confidence"] == 0.95+++def test_bootstrap_ci_coverage_is_near_nominal():+ # A 95% interval should cover the truth on the large majority of draws. The+ # floor is loose enough not to be flaky, tight enough to catch a broken CI.+ true_mean = 0.5+ covered = 0+ for seed in range(40):+ data = np.random.default_rng(100 + seed).standard_normal(200) + true_mean+ result = bootstrap_statistic(data, np.mean, n_bootstrap=300, seed=seed)+ covered += result["ci_lower"] < true_mean < result["ci_upper"]++ assert covered >= 34, f"only {covered}/40 intervals covered the true mean"+++def test_bootstrap_interval_widens_with_confidence():+ data = np.random.default_rng(81).standard_normal(300)++ narrow = bootstrap_statistic(data, np.mean, n_bootstrap=500, confidence=0.80, seed=2)+ wide = bootstrap_statistic(data, np.mean, n_bootstrap=500, confidence=0.99, seed=2)++ assert (wide["ci_upper"] - wide["ci_lower"]) > (narrow["ci_upper"] - narrow["ci_lower"])+++def test_bootstrap_is_reproducible_with_a_seed():+ data = np.random.default_rng(82).standard_normal(200)++ first = bootstrap_statistic(data, np.mean, n_bootstrap=200, seed=7)+ second = bootstrap_statistic(data, np.mean, n_bootstrap=200, seed=7)++ assert first == second+++ "kwargs, message",+ [+ ({"n_bootstrap": 0}, "n_bootstrap >= 1"),+ ({"confidence": 1.0}, "confidence in"),+ ({"confidence": 0.0}, "confidence in"),+ ],+)+def test_bootstrap_rejects_bad_arguments(kwargs, message):+ with pytest.raises(ValueError, match=message):+ bootstrap_statistic(np.arange(10.0), np.mean, **kwargs)+++def test_bootstrap_rejects_an_empty_sample():+ with pytest.raises(ValueError, match="non-empty"):+ bootstrap_statistic(np.array([]), np.mean)+++def test_bootstrap_sharpe_flags_a_real_edge_as_significant():+ # Daily mean 0.001 with sd 0.01 is an annualised Sharpe of ~1.6 over 4+ # years of bars -- comfortably distinguishable from zero.+ returns = pd.Series(np.random.default_rng(90).standard_normal(1000) * 0.01 + 0.001)++ result = bootstrap_sharpe(returns, n_bootstrap=1000, seed=3)++ assert result["is_significant"] is True+ assert result["ci_lower"] > 0+ assert result["point_estimate"] == pytest.approx(1.6, abs=0.6)+++def test_bootstrap_sharpe_calls_pure_noise_insignificant():+ # The realised Sharpe of 1000 zero-mean draws has sd sqrt(252/1000) ≈ 0.50,+ # so a single noise path can genuinely show Sharpe ≈ 1.0 (seed 91 does).+ # Seed 3021 draws a realised Sharpe of ~0.008, which must straddle zero.+ returns = pd.Series(np.random.default_rng(3021).standard_normal(1000) * 0.01)++ result = bootstrap_sharpe(returns, n_bootstrap=1000, seed=4)++ assert result["is_significant"] is False+ assert result["ci_lower"] < 0 < result["ci_upper"]+++def test_bootstrap_sharpe_false_positive_rate_stays_near_nominal():+ flagged = 0+ for seed in range(40):+ returns = pd.Series(np.random.default_rng(3000 + seed).standard_normal(1000) * 0.01)+ flagged += bootstrap_sharpe(returns, n_bootstrap=300, seed=seed)["is_significant"]++ assert flagged <= 5, f"{flagged}/40 pure-noise paths called significant at 95%"+++def test_bootstrap_sharpe_annualisation_is_configurable():+ returns = pd.Series(np.random.default_rng(92).standard_normal(600) * 0.01 + 0.001)++ daily = bootstrap_sharpe(returns, n_bootstrap=200, periods_per_year=252, seed=5)+ monthly = bootstrap_sharpe(returns, n_bootstrap=200, periods_per_year=12, seed=5)++ assert daily["point_estimate"] == pytest.approx(monthly["point_estimate"] * np.sqrt(252 / 12))+++def test_bootstrap_sharpe_uses_the_sample_standard_deviation():+ # The skill's markdown fed `returns.values` to a numpy `.std()`, i.e. ddof=0,+ # and `backtest.validation._sharpe` still does. This function deliberately+ # uses ddof=1. Pin the convention and the size of the resulting divergence so+ # nobody "reconciles" the two by accident.+ returns = pd.Series(np.random.default_rng(94).standard_normal(252) * 0.01 + 0.001)+ values = returns.to_numpy()++ point = bootstrap_sharpe(returns, n_bootstrap=50, seed=8)["point_estimate"]++ ddof1 = values.mean() / values.std(ddof=1) * np.sqrt(252)+ ddof0 = values.mean() / values.std(ddof=0) * np.sqrt(252)+ assert point == pytest.approx(ddof1, rel=1e-12)+ assert point != pytest.approx(ddof0, rel=1e-6)+ assert ddof0 / ddof1 == pytest.approx(np.sqrt(252 / 251), rel=1e-12)+++def test_bootstrap_sharpe_return_shape():+ returns = pd.Series(np.random.default_rng(93).standard_normal(200) * 0.01)++ result = bootstrap_sharpe(returns, n_bootstrap=100, seed=6)++ assert set(result) == {+ "point_estimate",+ "bootstrap_mean",+ "bootstrap_std",+ "ci_lower",+ "ci_upper",+ "confidence",+ "is_significant",+ }+++# ─── GARCH (optional 'arch' backend) ───+++def test_fit_garch_recovers_volatility_clustering():+ pytest.importorskip("arch", reason="the optional 'arch' package is not installed")++ # Simulate GARCH(1,1) with known parameters, in percent units.+ omega, alpha, beta = 0.05, 0.10, 0.85+ rng = np.random.default_rng(200)+ n = 4000+ var = np.empty(n)+ eps = np.empty(n)+ var[0] = omega / (1 - alpha - beta)+ for i in range(n):+ if i > 0:+ var[i] = omega + alpha * eps[i - 1] ** 2 + beta * var[i - 1]+ eps[i] = np.sqrt(var[i]) * rng.standard_normal()+ returns = pd.Series(eps / 100) # fit_garch rescales by 100 internally++ result = fit_garch(returns, horizon=5)++ assert result["alpha"] == pytest.approx(alpha, abs=0.05)+ assert result["beta"] == pytest.approx(beta, abs=0.08)+ assert result["persistence"] == pytest.approx(alpha + beta, abs=0.05)+ assert len(result["forecast_vol"]) == 5+ assert result["horizon"] == 5+ # conditional_volatility is already a std dev; a stray sqrt would land this+ # near 0.02 (sqrt of ~0.006) instead of in the plausible daily-vol range.+ assert 0.001 < result["current_vol"] < 0.20+++def test_fit_garch_return_shape():+ pytest.importorskip("arch", reason="the optional 'arch' package is not installed")++ returns = pd.Series(np.random.default_rng(201).standard_normal(600) * 0.01)+ result = fit_garch(returns, horizon=3)++ assert set(result) == {+ "omega", "alpha", "beta", "persistence", "long_run_vol",+ "current_vol", "forecast_vol", "horizon", "aic", "bic",+ }+ assert len(result["forecast_vol"]) == 3+++def test_fit_garch_rejects_a_non_positive_horizon():+ pytest.importorskip("arch", reason="the optional 'arch' package is not installed")++ with pytest.raises(ValueError, match="horizon >= 1"):+ fit_garch(pd.Series(np.random.default_rng(202).standard_normal(200) * 0.01), horizon=0)+++# ─── Optional-dependency degradation ───+++def test_missing_optional_backend_names_the_package_and_the_install_command():+ from src.quantlib import timeseries++ with pytest.raises(ImportError) as excinfo:+ timeseries._require("definitely_not_a_real_module", "arch", "fit_garch")++ message = str(excinfo.value)+ assert "fit_garch" in message+ assert "'arch'" in message+ assert "pip install" in message+++def test_fit_garch_raises_an_actionable_error_when_arch_is_absent():+ pytest.importorskip("pandas")+ try:+ import arch # noqa: F401+ except ImportError:+ pass+ else:+ pytest.skip("'arch' is installed, so the missing-dependency path cannot be exercised")++ with pytest.raises(ImportError, match="pip install"):+ fit_garch(pd.Series(np.random.default_rng(203).standard_normal(100) * 0.01))+++def test_importing_the_module_does_not_require_the_optional_backends():+ # The module must import cleanly even with no statsmodels and no arch, so+ # the pure-numpy bootstrap helpers stay usable on a bare install.+ import importlib++ module = importlib.import_module("src.quantlib.timeseries")++ assert len(module.__all__) == 11+ assert "statsmodels" not in module.__dict__+ assert "arch" not in module.__dict__diff --git a/pyproject.toml b/pyproject.tomlindex e97782f13..f573b8a78 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -132,6 +132,14 @@ krx = [# the kr_equity chain falls back to yahoo/yfinance (.KS/.KQ suffixes)."pykrx>=1.0.45",]+stats = [+ # Econometrics behind src/quantlib/timeseries: stationarity (ADF),+ # cointegration, Granger causality, Ljung-Box, VIF and GARCH. Those+ # functions lazy-import and raise an actionable ImportError naming this+ # extra, so the base install stays lean and nothing silently degrades.+ "statsmodels>=0.14",+ "arch>=6.0",+]ashare = [# Free, no-auth A-share source over BaoStock's TCP protocol; bypasses the# HTTP CDN IP blocks that affect eastmoney-backed sources. The Tencent