quantlite 0.9.0__tar.gz → 1.0.0__tar.gz

{quantlite-0.9.0/src/quantlite.egg-info → quantlite-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantlite
-Version: 0.9.0
+Version: 1.0.0
 Summary: A fat-tail-native quantitative finance toolkit: EVT, risk metrics, and honest modelling for markets that bite.
 Author-email: Prasant Sudhakaran <code@prasant.net>
 License: MIT License
@@ -1096,6 +1096,62 @@ print(f"Tail diversification:   {td['tail_diversification']:.3f}")
 | `quantlite.network` | Correlation networks, eigenvector centrality, cascade simulation, community detection |
 | `quantlite.diversification` | Effective Number of Bets, entropy diversification, tail diversification, diversification ratio, Herfindahl index |
 
+## v1.0: The Dream API
+
+QuantLite v1.0 introduces the **Dream API**, a five-function pipeline that chains the entire quant workflow:
+
+```python
+import quantlite as ql
+
+data = ql.fetch(["AAPL", "BTC-USD", "GLD", "TLT"], period="5y")
+regimes = ql.detect_regimes(data, n_regimes=3)
+weights = ql.construct_portfolio(data, regime_aware=True, regimes=regimes)
+result = ql.backtest(data, weights)
+ql.tearsheet(result, regimes=regimes, save="portfolio.txt")
+```
+
+### Regime-Aware Portfolio Construction
+
+Weights automatically tilt defensive during crisis regimes, increasing allocations to bonds and gold while reducing equity exposure:
+
+![Pipeline Equity Curve](https://raw.githubusercontent.com/prasants/QuantLite/main/docs/images/pipeline_equity_curve.png)
+
+### Regime Risk Analysis
+
+VaR, CVaR, volatility, skewness, and kurtosis computed separately for each market regime:
+
+![Regime Risk Summary](https://raw.githubusercontent.com/prasants/QuantLite/main/docs/images/regime_risk_summary.png)
+
+### Regime-Filtered Backtesting
+
+Different weight sets applied per regime, with full performance attribution:
+
+![Regime Filtered Backtest](https://raw.githubusercontent.com/prasants/QuantLite/main/docs/images/regime_filtered_backtest.png)
+
+### v1.0 Module Reference
+
+| Module | Description |
+|--------|-------------|
+| `quantlite.pipeline` | Dream API: `fetch`, `detect_regimes`, `construct_portfolio`, `backtest`, `tearsheet` |
+| `quantlite.regime_integration` | Regime-conditional risk, defensive portfolio tilting, filtered backtesting, tearsheets |
+| `quantlite.regimes` | HMM regime detection, Bayesian changepoint detection, conditional metrics |
+| `quantlite.portfolio` | Markowitz, CVaR, risk parity, HRP, Black-Litterman, Kelly optimisation |
+| `quantlite.backtesting` | Multi-asset engine with circuit breakers, slippage, regime-aware signals |
+| `quantlite.risk` | VaR, CVaR, Sortino, Calmar, omega ratio, tail ratio, drawdown analysis |
+| `quantlite.data` | Unified fetching: Yahoo Finance, CCXT, FRED, local files |
+| `quantlite.distributions` | Student-t, stable, GPD, GEV fitting and simulation |
+| `quantlite.simulation` | Fat-tail Monte Carlo: EVT-based, copula-based engines |
+| `quantlite.viz` | Stephen Few-inspired charts: regimes, portfolios, risk dashboards |
+| `quantlite.factors` | Classical factors, custom factors, tail risk factors |
+| `quantlite.ergodicity` | Time-average vs ensemble-average growth, Kelly sizing |
+| `quantlite.antifragile` | Barbell metrics, convexity scores, stress testing |
+| `quantlite.scenarios` | Historical, hypothetical, and Monte Carlo scenario analysis |
+| `quantlite.forensics` | Overfitting detection, data snooping tests, walk-forward analysis |
+| `quantlite.contagion` | CoVaR, Delta CoVaR, MES, Granger causality |
+| `quantlite.network` | Correlation networks, centrality, cascade simulation |
+| `quantlite.diversification` | Effective Number of Bets, entropy, tail diversification |
+| `quantlite.crypto` | On-chain risk, stablecoin depeg, exchange risk scoring |
+
 ## Design Philosophy
 
 1. **Fat tails are the default.** Gaussian assumptions are explicitly opt-in, never implicit.

{quantlite-0.9.0 → quantlite-1.0.0}/README.md

@@ -1015,6 +1015,62 @@ print(f"Tail diversification:   {td['tail_diversification']:.3f}")
 | `quantlite.network` | Correlation networks, eigenvector centrality, cascade simulation, community detection |
 | `quantlite.diversification` | Effective Number of Bets, entropy diversification, tail diversification, diversification ratio, Herfindahl index |
 
+## v1.0: The Dream API
+
+QuantLite v1.0 introduces the **Dream API**, a five-function pipeline that chains the entire quant workflow:
+
+```python
+import quantlite as ql
+
+data = ql.fetch(["AAPL", "BTC-USD", "GLD", "TLT"], period="5y")
+regimes = ql.detect_regimes(data, n_regimes=3)
+weights = ql.construct_portfolio(data, regime_aware=True, regimes=regimes)
+result = ql.backtest(data, weights)
+ql.tearsheet(result, regimes=regimes, save="portfolio.txt")
+```
+
+### Regime-Aware Portfolio Construction
+
+Weights automatically tilt defensive during crisis regimes, increasing allocations to bonds and gold while reducing equity exposure:
+
+![Pipeline Equity Curve](https://raw.githubusercontent.com/prasants/QuantLite/main/docs/images/pipeline_equity_curve.png)
+
+### Regime Risk Analysis
+
+VaR, CVaR, volatility, skewness, and kurtosis computed separately for each market regime:
+
+![Regime Risk Summary](https://raw.githubusercontent.com/prasants/QuantLite/main/docs/images/regime_risk_summary.png)
+
+### Regime-Filtered Backtesting
+
+Different weight sets applied per regime, with full performance attribution:
+
+![Regime Filtered Backtest](https://raw.githubusercontent.com/prasants/QuantLite/main/docs/images/regime_filtered_backtest.png)
+
+### v1.0 Module Reference
+
+| Module | Description |
+|--------|-------------|
+| `quantlite.pipeline` | Dream API: `fetch`, `detect_regimes`, `construct_portfolio`, `backtest`, `tearsheet` |
+| `quantlite.regime_integration` | Regime-conditional risk, defensive portfolio tilting, filtered backtesting, tearsheets |
+| `quantlite.regimes` | HMM regime detection, Bayesian changepoint detection, conditional metrics |
+| `quantlite.portfolio` | Markowitz, CVaR, risk parity, HRP, Black-Litterman, Kelly optimisation |
+| `quantlite.backtesting` | Multi-asset engine with circuit breakers, slippage, regime-aware signals |
+| `quantlite.risk` | VaR, CVaR, Sortino, Calmar, omega ratio, tail ratio, drawdown analysis |
+| `quantlite.data` | Unified fetching: Yahoo Finance, CCXT, FRED, local files |
+| `quantlite.distributions` | Student-t, stable, GPD, GEV fitting and simulation |
+| `quantlite.simulation` | Fat-tail Monte Carlo: EVT-based, copula-based engines |
+| `quantlite.viz` | Stephen Few-inspired charts: regimes, portfolios, risk dashboards |
+| `quantlite.factors` | Classical factors, custom factors, tail risk factors |
+| `quantlite.ergodicity` | Time-average vs ensemble-average growth, Kelly sizing |
+| `quantlite.antifragile` | Barbell metrics, convexity scores, stress testing |
+| `quantlite.scenarios` | Historical, hypothetical, and Monte Carlo scenario analysis |
+| `quantlite.forensics` | Overfitting detection, data snooping tests, walk-forward analysis |
+| `quantlite.contagion` | CoVaR, Delta CoVaR, MES, Granger causality |
+| `quantlite.network` | Correlation networks, centrality, cascade simulation |
+| `quantlite.diversification` | Effective Number of Bets, entropy, tail diversification |
+| `quantlite.crypto` | On-chain risk, stablecoin depeg, exchange risk scoring |
+
 ## Design Philosophy
 
 1. **Fat tails are the default.** Gaussian assumptions are explicitly opt-in, never implicit.

{quantlite-0.9.0 → quantlite-1.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantlite"
-version = "0.9.0"
+version = "1.0.0"
 description = "A fat-tail-native quantitative finance toolkit: EVT, risk metrics, and honest modelling for markets that bite."
 requires-python = ">=3.9"
 license = { file = "LICENSE" }

{quantlite-0.9.0 → quantlite-1.0.0}/src/quantlite/__init__.py

@@ -6,7 +6,7 @@ portfolio optimisation, multi-asset backtesting, and
 Stephen Few-inspired visualisation.
 """
 
-__version__ = "0.2.0"
+__version__ = "1.0.0"
 
 from .backtesting import (
     BacktestConfig,
@@ -79,6 +79,14 @@ __all__ = [
     "crypto",
     # Fat-tail Monte Carlo simulation
     "simulation",
+    # Regime-aware integration
+    "regime_integration",
+    # Dream API (pipeline)
+    "fetch",
+    "detect_regimes",
+    "construct_portfolio",
+    "backtest",
+    "tearsheet",
 ]
 
 from . import (  # noqa: E402
@@ -90,7 +98,15 @@ from . import (  # noqa: E402
     forensics,
     network,
     overfit,
+    regime_integration,
     resample,
     scenarios,
     simulation,
 )
+from .pipeline import (  # noqa: E402
+    backtest,
+    construct_portfolio,
+    detect_regimes,
+    tearsheet,
+)
+from .pipeline import fetch as fetch  # noqa: E402

{quantlite-0.9.0 → quantlite-1.0.0}/src/quantlite/antifragile/__init__.py

@@ -218,44 +218,40 @@ def barbell_allocation(
 def lindy_estimate(age: float, confidence: float = 0.95) -> dict[str, float]:
     """Estimate remaining life expectancy using the Lindy effect.
 
-    For non-perishable entities (ideas, technologies, institutions),
-    expected remaining lifespan is proportional to current age.
+    Models non-perishable entities (ideas, technologies, institutions)
+    with a Pareto survival distribution (alpha = 1).  Under this model:
 
-    Uses a Pareto-like survival model where the expected remaining
-    life equals the current age (for the median estimate).
+        P(T > age + t | T > age) = age / (age + t)
+
+    Key properties:
+
+    * **Expected remaining life** = age (the longer it has survived,
+      the longer we expect it to last).
+    * **Lower bound at confidence level c**: the additional time *t*
+      such that we are *c*-confident the entity survives at least *t*
+      more units.  Solve ``age / (age + t) = 1 - c`` to get
+      ``t = age * c / (1 - c)``.
 
     Parameters
     ----------
     age : float
         Current age of the entity (in any consistent unit).
     confidence : float
-        Confidence level for the survival bound (default 0.95).
+        Confidence level for the survival lower bound (default 0.95).
 
     Returns
     -------
     dict
-        Keys: 'age', 'expected_remaining' (median estimate),
-        'lower_bound' (at given confidence), 'total_expected'.
+        Keys: 'age', 'expected_remaining', 'lower_bound' (at the
+        given confidence), 'total_expected'.
     """
     if age <= 0:
         raise ValueError("age must be positive")
     if not 0 < confidence < 1:
         raise ValueError("confidence must be between 0 and 1")
 
-    # Under Lindy (Pareto with alpha=1), expected remaining life = age
     expected_remaining = age
-
-    # Lower bound: at confidence level, survival beyond this point
-    # P(survive t more) = age / (age + t), so t = age * (1/p - 1)
-    lower_bound = age * (1.0 / (1.0 - confidence) - 1.0) * (1.0 - confidence)
-    # Simplifies to: age * confidence / (1 - confidence) * (1 - confidence) = age * confidence
-    # Actually: P(T > age + t | T > age) = age / (age + t) for Pareto
-    # Set this = 1 - confidence: age/(age+t) = 1 - confidence
-    # t = age * confidence / (1 - confidence)
-    lower_bound = age * (1.0 - confidence) / confidence
-    # That's the point we're confident we'll reach (small value)
-    # More useful: expected remaining at median
-    # P(T > age + t | T > age) = 0.5 => t = age (median remaining = age)
+    lower_bound = age * confidence / (1.0 - confidence)
 
     return {
         "age": age,
@@ -268,11 +264,25 @@ def lindy_estimate(age: float, confidence: float = 0.95) -> dict[str, float]:
 def skin_in_game_score(
     manager_returns: ArrayLike,
     fund_returns: ArrayLike,
+    alignment_weight: float = 0.4,
+    downside_weight: float = 0.4,
+    asymmetry_weight: float = 0.2,
 ) -> dict[str, float]:
     """Measure principal-agent alignment via payoff asymmetry.
 
     Compares the manager's exposure to downside vs upside relative
-    to the fund. A good score means the manager shares the pain.
+    to the fund.  A good score means the manager shares the pain.
+
+    The composite score weights three components:
+
+    * **Alignment** (default 0.4): correlation between manager and fund
+      returns.  Are incentives actually correlated?
+    * **Downside sharing** (default 0.4): when the fund loses, does the
+      manager bleed proportionally?  This matters as much as alignment —
+      asymmetric downside is the hallmark of agency problems.
+    * **Upside asymmetry** (default 0.2): does the manager capture
+      disproportionate upside?  A secondary check — some asymmetry is
+      expected (performance fees), but extreme values signal misalignment.
 
     Parameters
     ----------
@@ -280,6 +290,12 @@ def skin_in_game_score(
         Returns experienced by the manager (compensation-adjusted).
     fund_returns : array-like
         Returns experienced by the fund investors.
+    alignment_weight : float
+        Weight for the alignment (correlation) component (default 0.4).
+    downside_weight : float
+        Weight for the downside-sharing component (default 0.4).
+    asymmetry_weight : float
+        Weight for the upside-asymmetry component (default 0.2).
 
     Returns
     -------
@@ -317,7 +333,11 @@ def skin_in_game_score(
 
     # Composite score: high alignment + high downside sharing + low upside asymmetry = good
     # Normalise to [0, 1] approximately
-    score = (alignment * 0.4) + (min(downside_sharing, 1.0) * 0.4) + (max(0, 1.0 - abs(upside_asymmetry - 1.0)) * 0.2)
+    score = (
+        alignment * alignment_weight
+        + min(downside_sharing, 1.0) * downside_weight
+        + max(0, 1.0 - abs(upside_asymmetry - 1.0)) * asymmetry_weight
+    )
 
     return {
         "alignment": alignment,

{quantlite-0.9.0 → quantlite-1.0.0}/src/quantlite/ergodicity/__init__.py

@@ -91,11 +91,13 @@ def ergodicity_gap(returns: ArrayLike) -> float:
 def kelly_fraction(returns: ArrayLike, risk_free: float = 0.0) -> float:
     """Compute the optimal Kelly fraction for geometric growth.
 
-    The Kelly criterion maximises the expected logarithmic growth rate.
-    For a simple binary-style approximation from empirical returns,
-    we optimise f to maximise E[log(1 + f * (r - risk_free))].
+    The Kelly criterion maximises the expected logarithmic growth rate:
 
-    Uses a numerical grid search over [0, 2] for robustness.
+        f* = argmax_f  E[log(1 + f * (r - r_f))]
+
+    Uses ``scipy.optimize.minimize_scalar`` with bounded search on
+    [-0.5, 3.0].  Falls back to Brent-bounded optimisation if the
+    primary solve fails.
 
     Parameters
     ----------
@@ -110,24 +112,36 @@ def kelly_fraction(returns: ArrayLike, risk_free: float = 0.0) -> float:
         Optimal fraction of capital to deploy. Can be < 0 (short)
         or > 1 (leveraged).
     """
+    from scipy.optimize import minimize_scalar
+
     r = _to_array(returns)
     excess = r - risk_free
 
-    # Grid search over fractions from -0.5 to 3.0
-    fractions = np.linspace(-0.5, 3.0, 3500)
-    best_f = 0.0
-    best_g = -np.inf
-
-    for f in fractions:
+    def neg_expected_log_growth(f: float) -> float:
         portfolio = 1.0 + f * excess
         if np.any(portfolio <= 0):
-            continue
-        g = np.mean(np.log(portfolio))
-        if g > best_g:
-            best_g = g
-            best_f = f
+            return 1e10  # infeasible
+        return -float(np.mean(np.log(portfolio)))
+
+    bounds = (-0.5, 3.0)
+
+    result = minimize_scalar(
+        neg_expected_log_growth, bounds=bounds, method="bounded",
+        options={"xatol": 1e-8, "maxiter": 500},
+    )
+
+    if result.success:
+        return float(round(result.x, 4))
+
+    # Fallback: try again with Brent in the same interval
+    result2 = minimize_scalar(
+        neg_expected_log_growth, bracket=(-0.5, 0.5, 3.0), method="brent",
+    )
+    if result2.success and bounds[0] <= result2.x <= bounds[1]:
+        return float(round(result2.x, 4))
 
-    return float(round(best_f, 4))
+    # Last resort: return 0 (no bet)
+    return 0.0
 
 
 def leverage_effect(