squeeze-kernel 0.7.1__tar.gz → 3.1.0__tar.gz

squeeze_kernel-3.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: squeeze-kernel
+Version: 3.1.0
+Summary: Streaming, PSD-by-construction covariance estimator with Fisher-kernel weighting and adaptive shrinkage
+Keywords: covariance,correlation,ewma,kernel,risk,streaming
+Author: Robert Kende
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=1.24
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.7 ; extra == 'dev'
+Requires-Dist: scipy>=1.11 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: scipy>=1.11 ; extra == 'full'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/r0k3/squeeze-kernel
+Project-URL: Repository, https://github.com/r0k3/squeeze-kernel
+Project-URL: Issues, https://github.com/r0k3/squeeze-kernel/issues
+Provides-Extra: dev
+Provides-Extra: full
+Description-Content-Type: text/markdown
+
+# Squeeze Kernel Covariance Estimator
+
+[![CI](https://github.com/r0k3/squeeze-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/r0k3/squeeze-kernel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
+[![Python](https://img.shields.io/pypi/pyversions/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A **streaming covariance estimator for panels of financial returns** whose entire public surface is **one number** — the decay `lam` of the anchor correlation timescale. Every other quantity is derived from it, fixed by a structural argument, or computed online from the estimator's own state. An `O(Kn²)` state update per day, positive semi-definite **by construction**, missing values handled **natively**, no tuning, no refits. Only dependency: NumPy.
+
+```python
+from squeeze_kernel import SqueezeKernel
+
+sk = SqueezeKernel(lam=0.996)        # the entire public surface
+for r_t in returns:                  # NaN marks missing assets
+    sk.update(r_t)
+cov = sk.covariance()
+```
+
+Reference: *"The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage"* (Kende, 2026) — [SSRN abstract 6455918](https://ssrn.com/abstract=6455918); the 2.0 estimator is described in the paper's current revision.
+
+## Why
+
+Markets do not keep calendar time. Following Mandelbrot, the estimator treats a panel as a collection of partially coupled markets, **each advancing on its own activity-driven clock** — and reads those clocks from the panel's own correlation structure, so a hot cluster (say precious metals and FX) advances its correlation state while an idle one (agriculture) does not, without anyone identifying a cluster. On those clocks it runs a single recursion that:
+
+- **is PSD at every step, structurally** — the correlation state evolves by a diagonal-congruence flow (a congruence plus a rank-one term); no eigenvalue clipping, no nearest-PSD repair, and no factorisation anywhere in the state update. (The adaptive timescale weights are the one exception: they read each timescale's predictive likelihood, which costs one Cholesky per timescale per day. Turn them off and the estimator is pure `O(Kn²)`.)
+- **learns in market time and forgets in calendar time** — observations enter with a saturating, self-studentising weight (no day counts more than one unit of trading time); memory decays at fixed per-day rates on a geometric ladder of three timescales `(lam⁴, lam, lam^¼)`. Pairs accrue covariance at the geometric mean of their two clock increments, which is the most positive semi-definiteness allows and exactly the Cauchy–Schwarz bound on how far two assets' clocks can overlap;
+- **regularises itself** — each timescale's shrinkage intensity is computed from two online statistics, the concentration `n/ν` (dimension per unit trading time) and the de-noised fraction of correlation dispersion the target explains; the target is the Hadamard square of the running correlation, which is exactly the correlation matrix of the *squared* returns (cluster-respecting, PSD by the Schur product theorem, and sign-blind by construction — the signs are carried by the unshrunk term);
+- **adapts its memory to regime breaks, in both stages** — the timescale mix moves by an exponentiated-gradient step on the *blend's* own log score (not on any single timescale's, which would select rather than blend), at a temperature calibrated so that uninformative evidence leaves the mix within a factor e of its prior; the marginal variance is tracked on its own three-rung ladder, two octaves below the correlation ladder, and pooled panel-wide by the same rule on saturated evidence, so one spike day cannot hand a stale rung weeks of weight. Nothing in either mixture is fitted: the ladders are derived from `lam`, the evidence memory is the fastest rung's, and the temperature is the null's;
+- **ingests missing values natively** — listings, delistings, halts enter as `NaN`;
+- **is fast** — one Cholesky and one triangular solve per day; a thirty-year daily pass at n=300 runs in about two minutes single-threaded, well under daily rolling-window refits.
+
+**Evidence.** On thirty years of S&P 500 constituents against an eleven-method field (EWMA, DCC, Ledoit–Wolf, OAS, nonlinear shrinkage, RMT filtering, Gerber, IEWMA, CM-IEWMA, and the published v1 estimator) it leads at every universe size from 50 to 300 and is the **sole member of the 90% model confidence set at every size**. Carried **zero-shot** to a diversified panel of 121 futures across eight asset classes it beats the same field *calibrated on that panel's own history* — matched-backbone IEWMA by 6.9 NLL/day (p = 4·10⁻⁴), calibrated DCC by 17.9 — out-of-time.
+
+## See the difference
+
+A passive strategy any allocator would recognize: long-only minimum-variance over 300 liquid US stocks, scaled to a 15% volatility target, rebalanced monthly, 5 bps costs. Two runs on identical data; the only difference is the covariance matrix. The Squeeze Kernel arm runs `SqueezeKernel(lam=0.996)` — **nothing tuned on this panel**.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/r0k3/squeeze-kernel/main/examples/figures/vol_targeted_portfolio_dark.png">
+  <img alt="Vol-targeted long-only minimum-variance portfolio on 300 US equities: Squeeze Kernel vs Ledoit-Wolf equity curves, drawdown, realized volatility, and risk/return profile" src="https://raw.githubusercontent.com/r0k3/squeeze-kernel/main/examples/figures/vol_targeted_portfolio.png">
+</picture>
+
+| Method | CAGR | Vol | Sharpe | MaxDD | Calmar | Vol-target RMSE |
+|---|---|---|---|---|---|---|
+| **Squeeze Kernel (default)** | **12.4%** | **13.5%** | **0.91** | **-34.6%** | **0.36** | **7.10%** |
+| Ledoit-Wolf (252d) | 11.7% | 14.6% | 0.80 | -38.7% | 0.30 | 7.51% |
+
+Reproduce from the repo alone (the 300-stock panel ships as a parquet; survivorship and provenance are documented in the script):
+
+```bash
+pip install squeeze-kernel pandas pyarrow scikit-learn matplotlib
+python examples/vol_targeted_portfolio.py    # ~2 minutes
+```
+
+## Installation
+
+```bash
+pip install squeeze-kernel          # NumPy only
+pip install "squeeze-kernel[full]"  # + SciPy (faster detector factorisations)
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from squeeze_kernel import SqueezeKernel, estimate_squeeze_cov
+
+returns = np.random.default_rng(42).normal(0.0, 0.01, size=(500, 30))
+
+sk = SqueezeKernel()                 # lam=0.996 (anchor half-life ~173 days)
+for r_t in returns:
+    w = sk.update(r_t)               # returns the day's kernel weight
+cov, corr = sk.covariance(), sk.correlation()
+sk.state()                           # kernel scale, per-timescale effective sizes, mixture tilt
+
+# batch mode: full panel in, covariance path out
+cov_path, corr_path, weights = estimate_squeeze_cov(returns, with_weights=True)
+```
+
+Missing values: pass `NaN` (or `mask=` on `update`). Newly listed, delisted or halted assets need no imputation and no complete-case subsetting.
+
+## What derives from `lam`
+
+| quantity | value |
+|---|---|
+| timescale ladder | decays `(lam⁴, lam, lam^¼)` — half-lives `(h/4, h, 4h)`, `h = -1/log2(lam)` |
+| kernel scale | state: `κ_t = ⅓ · EWMA(activity)` at the anchor rate |
+| shrinkage intensity | per timescale, `α = min(1,c) · g̃²/(g̃² + (1−g̃)²·max(0, 1/c − 1))` from the online concentration `c = n/ν` and target-fit `g̃` |
+| timescale weights | prior ∝ √h, moved by exponentiated gradient on the blend log score at the null temperature, fast-rung memory |
+| volatility memory | ladder `(h/16, h/4, h)`, pooled panel-wide by the same rule on tanh-saturated evidence, uniform prior |
+| structural constants | K=3, b=4, θ=½, κ-scale ⅓, Schur power 2 — each bracketed by ablation in the paper |
+| fitted constants | none (the 2.x volatility clock `λ_v = 0.98` is replaced by the ladder above) |
+
+`from squeeze_kernel import CONSTANTS` exposes the structural constants for research. The published v1 estimator (all its knobs) remains available as `SqueezeKernelEstimator` / `SqueezeKernel.v1(...)`; every 2.0 mechanism is also an estimator-level switch for ablation. See [MIGRATION.md](MIGRATION.md).
+
+## How it works
+
+One daily update: variance on a three-rung ladder per asset, pooled by panel-wide self-adapting weights → standardised surprise → per-asset clock increments from the Schur-square-weighted neighbourhood mean of squared surprises → diagonal-congruence update of each timescale's correlation state on those clocks → per-timescale shrinkage as a learned pool of the raw correlation, its equicorrelation level and its Hadamard square, with the self-tuning intensity rule as the prior and the blend gradient as the correction → blend across timescales, moved by the gradient of the blend's own log score → covariance. The paper gives the derivations, guarantees (PSD, conditioning floor, exact reductions to the published special cases), and the full evaluation.
+
+## Development
+
+```bash
+uv sync --extra full --extra dev
+uv run python -m pytest        # test suite
+uv run python -m ruff check .  # lint
+uv run mypy                      # strict type check (src/squeeze_kernel)
+uv build                       # build sdist + wheel
+```
+
+## Citation
+
+```bibtex
+@article{kende2026squeeze,
+  title  = {The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage},
+  author = {Kende, Robert},
+  year   = {2026},
+  note   = {Available at SSRN: \url{https://ssrn.com/abstract=6455918}}
+}
+```
+
+See also [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT

squeeze_kernel-3.1.0/README.md

@@ -0,0 +1,125 @@
+# Squeeze Kernel Covariance Estimator
+
+[![CI](https://github.com/r0k3/squeeze-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/r0k3/squeeze-kernel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
+[![Python](https://img.shields.io/pypi/pyversions/squeeze-kernel.svg)](https://pypi.org/project/squeeze-kernel/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A **streaming covariance estimator for panels of financial returns** whose entire public surface is **one number** — the decay `lam` of the anchor correlation timescale. Every other quantity is derived from it, fixed by a structural argument, or computed online from the estimator's own state. An `O(Kn²)` state update per day, positive semi-definite **by construction**, missing values handled **natively**, no tuning, no refits. Only dependency: NumPy.
+
+```python
+from squeeze_kernel import SqueezeKernel
+
+sk = SqueezeKernel(lam=0.996)        # the entire public surface
+for r_t in returns:                  # NaN marks missing assets
+    sk.update(r_t)
+cov = sk.covariance()
+```
+
+Reference: *"The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage"* (Kende, 2026) — [SSRN abstract 6455918](https://ssrn.com/abstract=6455918); the 2.0 estimator is described in the paper's current revision.
+
+## Why
+
+Markets do not keep calendar time. Following Mandelbrot, the estimator treats a panel as a collection of partially coupled markets, **each advancing on its own activity-driven clock** — and reads those clocks from the panel's own correlation structure, so a hot cluster (say precious metals and FX) advances its correlation state while an idle one (agriculture) does not, without anyone identifying a cluster. On those clocks it runs a single recursion that:
+
+- **is PSD at every step, structurally** — the correlation state evolves by a diagonal-congruence flow (a congruence plus a rank-one term); no eigenvalue clipping, no nearest-PSD repair, and no factorisation anywhere in the state update. (The adaptive timescale weights are the one exception: they read each timescale's predictive likelihood, which costs one Cholesky per timescale per day. Turn them off and the estimator is pure `O(Kn²)`.)
+- **learns in market time and forgets in calendar time** — observations enter with a saturating, self-studentising weight (no day counts more than one unit of trading time); memory decays at fixed per-day rates on a geometric ladder of three timescales `(lam⁴, lam, lam^¼)`. Pairs accrue covariance at the geometric mean of their two clock increments, which is the most positive semi-definiteness allows and exactly the Cauchy–Schwarz bound on how far two assets' clocks can overlap;
+- **regularises itself** — each timescale's shrinkage intensity is computed from two online statistics, the concentration `n/ν` (dimension per unit trading time) and the de-noised fraction of correlation dispersion the target explains; the target is the Hadamard square of the running correlation, which is exactly the correlation matrix of the *squared* returns (cluster-respecting, PSD by the Schur product theorem, and sign-blind by construction — the signs are carried by the unshrunk term);
+- **adapts its memory to regime breaks, in both stages** — the timescale mix moves by an exponentiated-gradient step on the *blend's* own log score (not on any single timescale's, which would select rather than blend), at a temperature calibrated so that uninformative evidence leaves the mix within a factor e of its prior; the marginal variance is tracked on its own three-rung ladder, two octaves below the correlation ladder, and pooled panel-wide by the same rule on saturated evidence, so one spike day cannot hand a stale rung weeks of weight. Nothing in either mixture is fitted: the ladders are derived from `lam`, the evidence memory is the fastest rung's, and the temperature is the null's;
+- **ingests missing values natively** — listings, delistings, halts enter as `NaN`;
+- **is fast** — one Cholesky and one triangular solve per day; a thirty-year daily pass at n=300 runs in about two minutes single-threaded, well under daily rolling-window refits.
+
+**Evidence.** On thirty years of S&P 500 constituents against an eleven-method field (EWMA, DCC, Ledoit–Wolf, OAS, nonlinear shrinkage, RMT filtering, Gerber, IEWMA, CM-IEWMA, and the published v1 estimator) it leads at every universe size from 50 to 300 and is the **sole member of the 90% model confidence set at every size**. Carried **zero-shot** to a diversified panel of 121 futures across eight asset classes it beats the same field *calibrated on that panel's own history* — matched-backbone IEWMA by 6.9 NLL/day (p = 4·10⁻⁴), calibrated DCC by 17.9 — out-of-time.
+
+## See the difference
+
+A passive strategy any allocator would recognize: long-only minimum-variance over 300 liquid US stocks, scaled to a 15% volatility target, rebalanced monthly, 5 bps costs. Two runs on identical data; the only difference is the covariance matrix. The Squeeze Kernel arm runs `SqueezeKernel(lam=0.996)` — **nothing tuned on this panel**.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/r0k3/squeeze-kernel/main/examples/figures/vol_targeted_portfolio_dark.png">
+  <img alt="Vol-targeted long-only minimum-variance portfolio on 300 US equities: Squeeze Kernel vs Ledoit-Wolf equity curves, drawdown, realized volatility, and risk/return profile" src="https://raw.githubusercontent.com/r0k3/squeeze-kernel/main/examples/figures/vol_targeted_portfolio.png">
+</picture>
+
+| Method | CAGR | Vol | Sharpe | MaxDD | Calmar | Vol-target RMSE |
+|---|---|---|---|---|---|---|
+| **Squeeze Kernel (default)** | **12.4%** | **13.5%** | **0.91** | **-34.6%** | **0.36** | **7.10%** |
+| Ledoit-Wolf (252d) | 11.7% | 14.6% | 0.80 | -38.7% | 0.30 | 7.51% |
+
+Reproduce from the repo alone (the 300-stock panel ships as a parquet; survivorship and provenance are documented in the script):
+
+```bash
+pip install squeeze-kernel pandas pyarrow scikit-learn matplotlib
+python examples/vol_targeted_portfolio.py    # ~2 minutes
+```
+
+## Installation
+
+```bash
+pip install squeeze-kernel          # NumPy only
+pip install "squeeze-kernel[full]"  # + SciPy (faster detector factorisations)
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from squeeze_kernel import SqueezeKernel, estimate_squeeze_cov
+
+returns = np.random.default_rng(42).normal(0.0, 0.01, size=(500, 30))
+
+sk = SqueezeKernel()                 # lam=0.996 (anchor half-life ~173 days)
+for r_t in returns:
+    w = sk.update(r_t)               # returns the day's kernel weight
+cov, corr = sk.covariance(), sk.correlation()
+sk.state()                           # kernel scale, per-timescale effective sizes, mixture tilt
+
+# batch mode: full panel in, covariance path out
+cov_path, corr_path, weights = estimate_squeeze_cov(returns, with_weights=True)
+```
+
+Missing values: pass `NaN` (or `mask=` on `update`). Newly listed, delisted or halted assets need no imputation and no complete-case subsetting.
+
+## What derives from `lam`
+
+| quantity | value |
+|---|---|
+| timescale ladder | decays `(lam⁴, lam, lam^¼)` — half-lives `(h/4, h, 4h)`, `h = -1/log2(lam)` |
+| kernel scale | state: `κ_t = ⅓ · EWMA(activity)` at the anchor rate |
+| shrinkage intensity | per timescale, `α = min(1,c) · g̃²/(g̃² + (1−g̃)²·max(0, 1/c − 1))` from the online concentration `c = n/ν` and target-fit `g̃` |
+| timescale weights | prior ∝ √h, moved by exponentiated gradient on the blend log score at the null temperature, fast-rung memory |
+| volatility memory | ladder `(h/16, h/4, h)`, pooled panel-wide by the same rule on tanh-saturated evidence, uniform prior |
+| structural constants | K=3, b=4, θ=½, κ-scale ⅓, Schur power 2 — each bracketed by ablation in the paper |
+| fitted constants | none (the 2.x volatility clock `λ_v = 0.98` is replaced by the ladder above) |
+
+`from squeeze_kernel import CONSTANTS` exposes the structural constants for research. The published v1 estimator (all its knobs) remains available as `SqueezeKernelEstimator` / `SqueezeKernel.v1(...)`; every 2.0 mechanism is also an estimator-level switch for ablation. See [MIGRATION.md](MIGRATION.md).
+
+## How it works
+
+One daily update: variance on a three-rung ladder per asset, pooled by panel-wide self-adapting weights → standardised surprise → per-asset clock increments from the Schur-square-weighted neighbourhood mean of squared surprises → diagonal-congruence update of each timescale's correlation state on those clocks → per-timescale shrinkage as a learned pool of the raw correlation, its equicorrelation level and its Hadamard square, with the self-tuning intensity rule as the prior and the blend gradient as the correction → blend across timescales, moved by the gradient of the blend's own log score → covariance. The paper gives the derivations, guarantees (PSD, conditioning floor, exact reductions to the published special cases), and the full evaluation.
+
+## Development
+
+```bash
+uv sync --extra full --extra dev
+uv run python -m pytest        # test suite
+uv run python -m ruff check .  # lint
+uv run mypy                      # strict type check (src/squeeze_kernel)
+uv build                       # build sdist + wheel
+```
+
+## Citation
+
+```bibtex
+@article{kende2026squeeze,
+  title  = {The Squeeze Kernel Covariance Estimator: Dual-Timescale Tracking with Adaptive Shrinkage},
+  author = {Kende, Robert},
+  year   = {2026},
+  note   = {Available at SSRN: \url{https://ssrn.com/abstract=6455918}}
+}
+```
+
+See also [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT

{squeeze_kernel-0.7.1 → squeeze_kernel-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "squeeze-kernel"
-version = "0.7.1"
+version = "3.1.0"
 description = "Streaming, PSD-by-construction covariance estimator with Fisher-kernel weighting and adaptive shrinkage"
 readme = "README.md"
 license = "MIT"

{squeeze_kernel-0.7.1 → squeeze_kernel-3.1.0}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "squeeze-kernel"
-version = "0.7.1"
+version = "3.1.0"
 description = "Streaming, PSD-by-construction covariance estimator with Fisher-kernel weighting and adaptive shrinkage"
 readme = "README.md"
 license = "MIT"

squeeze_kernel-3.1.0/src/squeeze_kernel/__init__.py

@@ -0,0 +1,42 @@
+"""
+Squeeze Kernel Covariance Estimator
+====================================
+
+Streaming, PSD-by-construction covariance estimator. The 2.0 API is one
+number; everything else derives from that decay, is a frozen
+structural constant, or is self-tuning state — including per-asset
+market clocks read from the correlation structure itself.
+
+Quick start::
+
+    import numpy as np
+    from squeeze_kernel import SqueezeKernel
+
+    returns = np.random.default_rng(42).normal(0.0, 0.01, size=(250, 30))
+
+    sk = SqueezeKernel(lam=0.996)        # the entire public surface
+    for r_t in returns:
+        sk.update(r_t)                   # NaN marks missing assets
+
+    cov = sk.covariance()
+    corr = sk.correlation()
+
+The published v1 estimator (all legacy knobs) remains available as
+``SqueezeKernelEstimator`` or ``SqueezeKernel.v1(...)``; see MIGRATION.md.
+"""
+
+from squeeze_kernel.core import CONSTANTS, SqueezeKernel, StructuralConstants
+from squeeze_kernel.estimator import SqueezeKernelEstimator
+from squeeze_kernel.kernels import kernel_fisher
+from squeeze_kernel.batch import estimate_squeeze_cov
+
+__all__ = [
+    "SqueezeKernel",
+    "StructuralConstants",
+    "CONSTANTS",
+    "SqueezeKernelEstimator",
+    "estimate_squeeze_cov",
+    "kernel_fisher",
+]
+
+__version__ = "3.1.0"

squeeze_kernel-3.1.0/src/squeeze_kernel/batch.py

@@ -0,0 +1,52 @@
+"""Batch estimation over an entire returns panel."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from squeeze_kernel.core import SqueezeKernel
+
+
+def estimate_squeeze_cov(
+    returns: ArrayLike,
+    *,
+    lam: float = 0.996,
+    with_corr: bool = True,
+    with_weights: bool = False,
+) -> tuple[np.ndarray, np.ndarray | None, np.ndarray | None]:
+    """Run :class:`SqueezeKernel` over a panel and collect the estimate path.
+
+    Parameters
+    ----------
+    returns : array-like, shape (T, n)
+        Daily returns; NaN marks missing observations.
+    lam : float
+        The estimator's single parameter (default 0.996).
+    with_corr : bool
+        Also return the correlation path.
+    with_weights : bool
+        Also return the per-day kernel weight.
+
+    Returns
+    -------
+    cov : ndarray, shape (T, n, n)
+    corr : ndarray or None, shape (T, n, n)
+    weights : ndarray or None, shape (T,)
+    """
+    values = np.asarray(returns, dtype=np.float64)
+    if values.ndim != 2:
+        raise ValueError(f"Expected 2D returns, got shape {values.shape}.")
+    t_total, n_assets = values.shape
+    sk = SqueezeKernel(lam=lam)
+    cov = np.empty((t_total, n_assets, n_assets), dtype=np.float64)
+    corr = np.empty_like(cov) if with_corr else None
+    weights = np.empty(t_total, dtype=np.float64) if with_weights else None
+    for t in range(t_total):
+        w_t = sk.update(values[t])
+        cov[t] = sk.covariance()
+        if corr is not None:
+            corr[t] = sk.correlation()
+        if weights is not None:
+            weights[t] = w_t
+    return cov, corr, weights

squeeze_kernel-3.1.0/src/squeeze_kernel/core.py

@@ -0,0 +1,187 @@
+"""squeeze-kernel 2.0 public API: the one-number estimator.
+
+``SqueezeKernel`` exposes the v2 configuration of the estimator — every
+constant either derives from ``half_life`` or is a frozen structural
+constant (``CONSTANTS``) — with a public surface of one number and two
+booleans.  The v1 estimator remains available unchanged as
+``SqueezeKernelEstimator`` (or via :meth:`SqueezeKernel.v1`).
+
+Configuration (research record: squeeze_cov V2_STATUS.md, branch v2):
+
+- correlation ladder at ``half_life * (43/173, 1, 693/173)`` — the
+  canonical rungs at the default half-life; rung weights ``pi ~ sqrt(h)``
+  (theta = 1/2, structural),
+- volatility on a ladder at ``half_life * (1/16, 1/4, 1)``, pooled
+  panel-wide by Bayes at the null-calibrated temperature on saturated
+  evidence with the fastest rung's memory and a uniform prior; this
+  replaced the 2.x fitted constant ``lambda_vol = 0.98`` (still accepted
+  by ``SqueezeKernelEstimator`` and ignored when ``vol_ladder=True``),
+- timescale weights moved by exponentiated gradient on the blend's log
+  score at the null temperature (fast-rung memory) from the prior
+  ``pi ~ sqrt(h)``; replaced the 2.x CUSUM detector,
+- (3.1) each timescale's shrunk correlation is a learned convex
+  combination of three PSD unit-diagonal experts -- its raw
+  correlation, the equicorrelation matrix at its mean level, and its
+  Schur square -- whose prior is the intensity rule's morph
+  ``(1-a, a(1-a), a^2)`` and whose weights the same blend gradient
+  corrects online (studentised within the timescale, same temperature
+  and memory).  At the prior the estimator is the 3.0 one,
+- kernel scale as state, not parameter: ``kappa_t = (1/3) EWMA_h(d^2)``
+  (chi-squared-null constant),
+- self-tuning shrinkage intensity per rung from the online concentration
+  ``c = n / nu`` and the de-noised equicorrelation-explained fraction
+  ``g``:  ``alpha = min(1, c) g^2 / (g^2 + (1-g)^2 max(0, 1/c - 1))``,
+- shrinkage target: gamma = 1 Schur-square cluster target (PSD by the
+  Schur product theorem) or equicorrelation,
+- sequential surprise-gated rung weights (Page CUSUM on the studentised
+  inter-rung predictive-score drift), switchable via ``detector``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .estimator import SqueezeKernelEstimator, _BlendGradient
+
+__all__ = ["SqueezeKernel", "StructuralConstants", "CONSTANTS"]
+
+
+@dataclass(frozen=True)
+class StructuralConstants:
+    """Frozen structural constants of the v2 estimator.
+
+    Importable for research; not constructor arguments.
+    """
+
+    b: float = 4.0                  # ladder spacing: rungs (h/b, h, h*b)
+    theta: float = 0.5              # rung weights ~ h^theta
+    lambda_vol: float = 0.98        # 2.x constant; unused by the 3.0 front-end (vol ladder)
+    kappa_c: float = 1.0 / 3.0      # kernel scale: kappa = kappa_c * EWMA(activity)
+    schur_p: int = 2                # Hadamard power of the cluster target
+    epsilon: float = 1e-8
+
+
+CONSTANTS = StructuralConstants()
+
+
+class SqueezeKernel:
+    """Streaming covariance estimator whose public surface is one number.
+
+    Parameters
+    ----------
+    lam : float
+        The single tunable: the exponential decay of the anchor
+        correlation timescale per trading day, in the classical EWMA
+        convention (default 0.996, a half-life of about 173 days).  The
+        timescale ladder ``(lam**b, lam, lam**(1/b))`` with ``b = 4``, the
+        kernel-scale clock, and the rung weights all derive from it.
+
+    Everything else is structural or self-tuning state: per-asset market
+    clocks read from the correlation neighborhood (row-normalized Schur-
+    square weighting of squared surprises), a per-timescale shrinkage
+    intensity from the online concentration and target-fit, the Schur-
+    square cluster target, and the surprise-gated timescale weights.
+    The number of assets is inferred from the first ``update`` call.
+    The published v1 estimator and every ablation switch remain available
+    on ``SqueezeKernelEstimator``.
+    """
+
+    def __init__(self, lam: float = 0.996) -> None:
+        if not (0.0 < lam < 1.0):
+            raise ValueError("lam must be in (0, 1).")
+        self.lam = float(lam)
+        self._est: SqueezeKernelEstimator | None = None
+        self._t = 0
+
+    @property
+    def half_life(self) -> float:
+        """Anchor half-life in trading days implied by ``lam``."""
+        return float(-1.0 / np.log2(self.lam))
+
+    # ── lifecycle ────────────────────────────────────────────────────────
+
+    def _build(self, n_assets: int) -> SqueezeKernelEstimator:
+        c = CONSTANTS
+        h = self.half_life                    # ladder = (lam**b, lam, lam**(1/b))
+        ladder = (h / c.b, h, h * c.b)
+        return SqueezeKernelEstimator(
+            n_assets,
+            lambda_vol=c.lambda_vol,
+            shrinkage="auto",
+            shrinkage_target="cluster",
+            corr_half_lives=ladder,
+            corr_theta=c.theta,
+            kappa_mode="adaptive",
+            alpha_rule="selftuning",
+            level_match=False,
+            detector=True,
+            clock="asset",
+            vol_ladder=True,
+            weights="eg_blend",
+            split_learn=True,
+            epsilon=c.epsilon,
+        )
+
+    # ── public API ───────────────────────────────────────────────────────
+
+    def update(self, r_t: ArrayLike, mask: ArrayLike | None = None) -> float:
+        """Process one return vector; returns the kernel weight w_t.
+
+        ``r_t`` may contain NaN for missing assets; ``mask`` (optional
+        boolean, True = observed) is an alternative way to mark them.
+        """
+        r = np.asarray(r_t, dtype=np.float64)
+        if r.ndim != 1:
+            raise ValueError("r_t must be one-dimensional.")
+        if mask is not None:
+            m = np.asarray(mask, dtype=bool)
+            if m.shape != r.shape:
+                raise ValueError("mask must match r_t's shape.")
+            r = np.where(m, r, np.nan)
+        if self._est is None:
+            self._est = self._build(r.size)
+        self._t += 1
+        return self._est.update(r)
+
+    def covariance(self) -> np.ndarray:
+        """Current covariance estimate (n x n)."""
+        if self._est is None:
+            raise RuntimeError("Call update() at least once first.")
+        return self._est.get_cov()
+
+    def correlation(self) -> np.ndarray:
+        """Current correlation estimate (n x n)."""
+        if self._est is None:
+            raise RuntimeError("Call update() at least once first.")
+        return self._est.get_corr()
+
+    def state(self) -> dict[str, object]:
+        """Diagnostics: update count, last weight, kernel scale, per-rung
+        effective sizes, detector tilt."""
+        if self._est is None:
+            return {"n_assets": None, "t": 0}
+        est = self._est
+        det = est._detector
+        S = list(est._S_list or [])
+        J = list(est._J_list or [])
+        nu = [s * s / max(j, est.epsilon) for s, j in zip(S, J)]
+        return {
+            "n_assets": est.n_assets,
+            "t": self._t,
+            "last_weight": est.weight,
+            "kappa_t": getattr(est, "_last_kappa",
+                               CONSTANTS.kappa_c * est._kap_state),
+            "rung_S": S,
+            "rung_nu": nu,
+            "detector_tilt": 0.0 if det is None else det.tilt,
+            "split": det.v.copy() if isinstance(det, _BlendGradient) and det.split else None,
+        }
+
+    # ── v1 escape hatch ──────────────────────────────────────────────────
+
+    @classmethod
+    def v1(cls, n_assets: int, **kwargs: object) -> SqueezeKernelEstimator:
+        """The published v1 estimator, unchanged (all legacy knobs)."""
+        return SqueezeKernelEstimator(n_assets, **kwargs)  # type: ignore[arg-type]