Skip to content

"Vibe-Trading: Your Personal Trading Agent"

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.py
index 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, Optional
import numpy as np
import 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 = strike
self.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.0
total_theta = 0.0
total_vega = 0.0
+ total_rho = 0.0
for 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_multiplier
total_theta += greeks["theta"] * pos.qty * contract_multiplier
total_vega += greeks["vega"] * pos.qty * contract_multiplier
+ total_rho += greeks["rho"] * pos.qty * contract_multiplier
equity_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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 result
diff --git a/agent/src/skills/credit-analysis/SKILL.md b/agent/src/skills/credit-analysis/SKILL.md
index 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)
```python
import 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.md
index 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 slippage
5. **Volume constraints**: order size should not exceed 5-10% of the day’s traded volume, otherwise the impact model becomes invalid
6. **Backtest overfitting**: even with slippage included, the strategy may still overfit; out-of-sample validation matters more
7. **`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 silently
diff --git a/agent/src/skills/market-microstructure/SKILL.md b/agent/src/skills/market-microstructure/SKILL.md
index 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-shares
diff --git a/agent/src/skills/options-payoff/SKILL.md b/agent/src/skills/options-payoff/SKILL.md
index 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
```python
from dataclasses import dataclass
+from typing import Literal
+
import numpy as np
+from scipy.optimize import brentq
+
+from src.quantlib.options import bs_price
@dataclass
class 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 diagram
legs = [
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.md
index 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 i
r_b,i = benchmark return of sector i
R_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 correction
6. **Factor data requirement**: factor attribution requires factor return data, which can be obtained from `tushare` or self-constructed
7. **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 model
diff --git a/agent/src/skills/quant-statistics/SKILL.md b/agent/src/skills/quant-statistics/SKILL.md
index a6e25f3b0..b30abeca8 100644
--- a/agent/src/skills/quant-statistics/SKILL.md
+++ b/agent/src/skills/quant-statistics/SKILL.md
@@ -10,6 +10,20 @@ category: analysis
Common 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 Tests
diff --git a/agent/src/skills/risk-analysis/SKILL.md b/agent/src/skills/risk-analysis/SKILL.md
index f528f5a8a..98f0fd8cc 100644
--- a/agent/src/skills/risk-analysis/SKILL.md
+++ b/agent/src/skills/risk-analysis/SKILL.md
@@ -10,6 +10,32 @@ category: analysis
Systematic 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:
## Notes
1. **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 conservative
3. **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 stability
6. **Holding-period scaling**: the square-root-of-time rule only applies under i.i.d. returns; it becomes inaccurate under autocorrelation
7. **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 printing
diff --git a/agent/src/tools/options_pricing_tool.py b/agent/src/tools/options_pricing_tool.py
index 0dbc128b9..e8e8779c6 100644
--- a/agent/src/tools/options_pricing_tool.py
+++ b/agent/src/tools/options_pricing_tool.py
@@ -6,10 +6,8 @@ import json
import math
from 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_price
def _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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.toml
index 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