finval 0.1.0__tar.gz

finval-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Build artifacts
+*.log
+.cache/

finval-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sablier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

finval-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: finval
+Version: 0.1.0
+Summary: Rigorous validation for synthetic financial time series
+Project-URL: Homepage, https://github.com/sablier-it/finval
+Project-URL: Repository, https://github.com/sablier-it/finval
+Project-URL: Issues, https://github.com/sablier-it/finval/issues
+Author-email: Sablier <hello@sablier.it>
+License: MIT
+License-File: LICENSE
+Keywords: finance,generative models,stylized facts,synthetic data,time series,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+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: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.11
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# finval
+
+**Rigorous validation for synthetic financial time series.**
+
+`finval` is a Python library for assessing the quality of synthetic
+market data against real data. It was built because no existing library
+covers the financial stylized facts that matter: fat tails, volatility
+clustering, leverage effect, crash co-movement, and probabilistic
+forecast calibration.
+
+`finval` is the scoring backend behind
+**[FinBench](https://github.com/sablier-it/finbench)**, the public
+leaderboard for multivariate financial time-series generation.
+
+> ⚠️ **Beta.** The library is in active use (57 tests, FinBench
+> production scoring) but the public API may still evolve in minor
+> versions. Pin to `finval==0.1.x` if you need API stability.
+
+## Why finval?
+
+General-purpose synthetic data libraries (`sdmetrics`, `synthcity`,
+`tsgm`) treat time series as generic sequences. They don't know what
+"leverage effect" is, don't check PIT uniformity, and don't compute tail
+dependence coefficients. For financial applications — risk management,
+backtesting, derivatives — you need a suite that tests the things that
+actually matter for market data.
+
+`finval` ships **17 metric functions** producing **20 numeric scores**
+across 5 categories (the calibration `coverage_50 / 90 / 95` come from
+a single function), each with thresholds calibrated against real
+financial data and justified by the statistical literature.
+
+## Installation
+
+```bash
+pip install finval
+```
+
+## Quickstart
+
+```python
+import numpy as np
+import finval
+
+# 2D data: (n_samples, n_features) returns
+real = np.random.randn(1000, 3) * 0.01
+synthetic = np.random.randn(1000, 3) * 0.01
+
+report = finval.validate(synthetic, real)
+print(report.summary())
+print(f"Overall quality: {report.overall_quality}")
+print(f"Pass rate: {report.pass_rate:.0%}")
+
+# 3D data: (n_paths, horizon, n_features) for path-level validation
+real_paths = np.random.randn(100, 60, 3) * 0.01
+syn_paths = np.random.randn(100, 60, 3) * 0.01
+
+report = finval.validate_paths(syn_paths, real_paths)
+print(report.summary())
+```
+
+## Metrics
+
+### Distribution (15% of overall score)
+- **marginal_ks** — Kolmogorov-Smirnov test on each feature's marginal
+- **energy_distance** — multivariate distribution difference
+- **tail_quantiles** — 1st/5th/95th/99th percentile comparison (robust alternative to kurtosis)
+- **tail_heaviness** — excess kurtosis error (diagnostic only)
+
+### Dependence (25%)
+- **pearson_corr** — linear correlation matrix error
+- **spearman_corr** — rank correlation matrix error
+- **copula_distance** — Cramér-von Mises distance between empirical copulas
+- **tail_dependence_upper** — rally co-movement (λ_U)
+- **tail_dependence_lower** — crash co-movement (λ_L)
+- **correlation_breakdown** — stress vs calm regime correlation shift
+
+### Temporal (20%)
+- **acf_returns** — autocorrelation of returns (should be ~0)
+- **volatility_clustering** — autocorrelation of squared returns
+- **leverage_effect** — corr(r_t, |r_{t+k}|) (negative for equities)
+- **cross_correlation** — contemporaneous cross-asset correlation
+
+### Calibration (30%)
+- **pit_uniformity** — KS test on probability integral transforms
+- **crps** — continuous ranked probability score
+- **coverage_50 / 90 / 95** — empirical vs nominal interval coverage
+
+### Path-level (10%)
+- **drawdown_distribution** — KS test on max drawdown distribution
+
+## Baselines
+
+Compare your model against simple reference generators to calibrate what
+"good" means for your data:
+
+```python
+from finval.baselines import gaussian_baseline, historical_bootstrap, block_bootstrap
+
+# Gaussian: matches mean+cov, no temporal structure
+gauss = gaussian_baseline(real, n_samples=1000)
+
+# i.i.d. bootstrap: matches joint distribution exactly, zero temporal
+boot = historical_bootstrap(real, n_samples=1000)
+
+# Block bootstrap: preserves short-range temporal structure
+blocks = block_bootstrap(real, n_paths=100, path_length=60, block_size=20)
+
+# Validate each
+for name, syn in [("gaussian", gauss), ("iid", boot)]:
+    r = finval.validate(syn, real)
+    print(f"{name}: {r.overall_quality} ({r.overall_score:.0%})")
+```
+
+## Design principles
+
+1. **Reliable over comprehensive.** Each metric is chosen because it's
+   robust and informative, not because it's impressive.
+
+2. **Mean over max for pairwise metrics.** Max over n(n-1)/2 feature
+   pairs is dominated by sampling noise. `finval` uses mean error, which
+   is harder to fool and more stable run-to-run.
+
+3. **Lower is always better.** Every metric is normalized so that zero
+   is perfect and higher is worse. No flipped signs to remember.
+
+4. **Financial stylized facts first.** Leverage effect, vol clustering,
+   fat tails, crash co-movement — these aren't optional for financial
+   data.
+
+5. **Proper scoring rules.** CRPS and PIT uniformity are proper scoring
+   rules, not just rank-order checks. Your model is evaluated against
+   the ground truth the statistics literature actually endorses.
+
+## License
+
+MIT

finval-0.1.0/README.md

@@ -0,0 +1,137 @@
+# finval
+
+**Rigorous validation for synthetic financial time series.**
+
+`finval` is a Python library for assessing the quality of synthetic
+market data against real data. It was built because no existing library
+covers the financial stylized facts that matter: fat tails, volatility
+clustering, leverage effect, crash co-movement, and probabilistic
+forecast calibration.
+
+`finval` is the scoring backend behind
+**[FinBench](https://github.com/sablier-it/finbench)**, the public
+leaderboard for multivariate financial time-series generation.
+
+> ⚠️ **Beta.** The library is in active use (57 tests, FinBench
+> production scoring) but the public API may still evolve in minor
+> versions. Pin to `finval==0.1.x` if you need API stability.
+
+## Why finval?
+
+General-purpose synthetic data libraries (`sdmetrics`, `synthcity`,
+`tsgm`) treat time series as generic sequences. They don't know what
+"leverage effect" is, don't check PIT uniformity, and don't compute tail
+dependence coefficients. For financial applications — risk management,
+backtesting, derivatives — you need a suite that tests the things that
+actually matter for market data.
+
+`finval` ships **17 metric functions** producing **20 numeric scores**
+across 5 categories (the calibration `coverage_50 / 90 / 95` come from
+a single function), each with thresholds calibrated against real
+financial data and justified by the statistical literature.
+
+## Installation
+
+```bash
+pip install finval
+```
+
+## Quickstart
+
+```python
+import numpy as np
+import finval
+
+# 2D data: (n_samples, n_features) returns
+real = np.random.randn(1000, 3) * 0.01
+synthetic = np.random.randn(1000, 3) * 0.01
+
+report = finval.validate(synthetic, real)
+print(report.summary())
+print(f"Overall quality: {report.overall_quality}")
+print(f"Pass rate: {report.pass_rate:.0%}")
+
+# 3D data: (n_paths, horizon, n_features) for path-level validation
+real_paths = np.random.randn(100, 60, 3) * 0.01
+syn_paths = np.random.randn(100, 60, 3) * 0.01
+
+report = finval.validate_paths(syn_paths, real_paths)
+print(report.summary())
+```
+
+## Metrics
+
+### Distribution (15% of overall score)
+- **marginal_ks** — Kolmogorov-Smirnov test on each feature's marginal
+- **energy_distance** — multivariate distribution difference
+- **tail_quantiles** — 1st/5th/95th/99th percentile comparison (robust alternative to kurtosis)
+- **tail_heaviness** — excess kurtosis error (diagnostic only)
+
+### Dependence (25%)
+- **pearson_corr** — linear correlation matrix error
+- **spearman_corr** — rank correlation matrix error
+- **copula_distance** — Cramér-von Mises distance between empirical copulas
+- **tail_dependence_upper** — rally co-movement (λ_U)
+- **tail_dependence_lower** — crash co-movement (λ_L)
+- **correlation_breakdown** — stress vs calm regime correlation shift
+
+### Temporal (20%)
+- **acf_returns** — autocorrelation of returns (should be ~0)
+- **volatility_clustering** — autocorrelation of squared returns
+- **leverage_effect** — corr(r_t, |r_{t+k}|) (negative for equities)
+- **cross_correlation** — contemporaneous cross-asset correlation
+
+### Calibration (30%)
+- **pit_uniformity** — KS test on probability integral transforms
+- **crps** — continuous ranked probability score
+- **coverage_50 / 90 / 95** — empirical vs nominal interval coverage
+
+### Path-level (10%)
+- **drawdown_distribution** — KS test on max drawdown distribution
+
+## Baselines
+
+Compare your model against simple reference generators to calibrate what
+"good" means for your data:
+
+```python
+from finval.baselines import gaussian_baseline, historical_bootstrap, block_bootstrap
+
+# Gaussian: matches mean+cov, no temporal structure
+gauss = gaussian_baseline(real, n_samples=1000)
+
+# i.i.d. bootstrap: matches joint distribution exactly, zero temporal
+boot = historical_bootstrap(real, n_samples=1000)
+
+# Block bootstrap: preserves short-range temporal structure
+blocks = block_bootstrap(real, n_paths=100, path_length=60, block_size=20)
+
+# Validate each
+for name, syn in [("gaussian", gauss), ("iid", boot)]:
+    r = finval.validate(syn, real)
+    print(f"{name}: {r.overall_quality} ({r.overall_score:.0%})")
+```
+
+## Design principles
+
+1. **Reliable over comprehensive.** Each metric is chosen because it's
+   robust and informative, not because it's impressive.
+
+2. **Mean over max for pairwise metrics.** Max over n(n-1)/2 feature
+   pairs is dominated by sampling noise. `finval` uses mean error, which
+   is harder to fool and more stable run-to-run.
+
+3. **Lower is always better.** Every metric is normalized so that zero
+   is perfect and higher is worse. No flipped signs to remember.
+
+4. **Financial stylized facts first.** Leverage effect, vol clustering,
+   fat tails, crash co-movement — these aren't optional for financial
+   data.
+
+5. **Proper scoring rules.** CRPS and PIT uniformity are proper scoring
+   rules, not just rank-order checks. Your model is evaluated against
+   the ground truth the statistics literature actually endorses.
+
+## License
+
+MIT

finval-0.1.0/examples/quickstart.py

@@ -0,0 +1,88 @@
+"""finval quickstart example.
+
+Demonstrates the three main use cases:
+
+1. Flat 2D validation (distribution + dependence)
+2. Path-level 3D validation (adds temporal + path metrics)
+3. Baseline comparison (gaussian vs bootstrap vs your model)
+
+Run from the finval repo root:
+
+    python examples/quickstart.py
+"""
+
+import numpy as np
+
+import finval
+from finval.baselines import (
+    block_bootstrap,
+    gaussian_baseline,
+    historical_bootstrap,
+)
+
+
+def build_real_returns(n: int = 2000, seed: int = 0) -> np.ndarray:
+    """Synthesize realistic-ish multi-asset returns with fat tails,
+    cross-asset correlation, and a crash regime."""
+    rng = np.random.default_rng(seed)
+    x = rng.standard_t(df=5, size=(n, 3)) * 0.01
+    # Induce correlation: feature 1 is mostly driven by feature 0
+    x[:, 1] = 0.7 * x[:, 0] + 0.3 * x[:, 1]
+    # Inject a few crash days where all assets move together
+    crash_days = rng.choice(n, size=n // 100, replace=False)
+    x[crash_days] -= 0.04
+    return x
+
+
+def main() -> None:
+    print("=" * 72)
+    print("finval quickstart")
+    print("=" * 72)
+
+    # ----------------------------------------------------------------------
+    # 1. Flat validation
+    # ----------------------------------------------------------------------
+    real = build_real_returns(n=2000, seed=0)
+    synthetic_good = build_real_returns(n=2000, seed=1)  # same distribution, new seed
+
+    print("\n1) Flat validation (matched synthetic):")
+    report = finval.validate(synthetic_good, real, feature_names=["asset_a", "asset_b", "asset_c"])
+    print(report.summary())
+
+    # ----------------------------------------------------------------------
+    # 2. Baseline comparison
+    # ----------------------------------------------------------------------
+    print("\n2) Baseline comparison:")
+    for name, syn in [
+        ("gaussian_iid", gaussian_baseline(real, n_samples=2000, seed=2)),
+        ("iid_bootstrap", historical_bootstrap(real, n_samples=2000, seed=3)),
+        ("your_model", synthetic_good),
+    ]:
+        r = finval.validate(syn, real)
+        print(f"  {name:20s} {r.overall_quality:10s} {r.overall_score:5.0%}")
+
+    # ----------------------------------------------------------------------
+    # 3. Path-level validation
+    # ----------------------------------------------------------------------
+    # Build return paths from the flat series by slicing non-overlapping windows
+    real_paths = real[: 60 * 30].reshape(30, 60, 3)
+    syn_paths = synthetic_good[: 60 * 30].reshape(30, 60, 3)
+
+    print("\n3) Path-level validation:")
+    report = finval.validate_paths(syn_paths, real_paths)
+    print(report.summary())
+
+    # ----------------------------------------------------------------------
+    # 4. Block bootstrap as a strong baseline for path metrics
+    # ----------------------------------------------------------------------
+    print("\n4) Block bootstrap beats gaussian on path metrics:")
+    block_paths = block_bootstrap(real, n_paths=30, path_length=60, block_size=20, seed=4)
+    gauss_paths = gaussian_baseline(real, n_paths=30, path_length=60, seed=5)
+
+    for name, paths in [("gaussian_paths", gauss_paths), ("block_bootstrap", block_paths)]:
+        r = finval.validate_paths(paths, real_paths)
+        print(f"  {name:20s} {r.overall_quality:10s} {r.overall_score:5.0%}")
+
+
+if __name__ == "__main__":
+    main()

finval-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "finval"
+version = "0.1.0"
+description = "Rigorous validation for synthetic financial time series"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Sablier", email = "hello@sablier.it" },
+]
+keywords = [
+    "finance",
+    "synthetic data",
+    "time series",
+    "validation",
+    "generative models",
+    "stylized facts",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.11",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.0"]
+plot = ["matplotlib>=3.7"]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "ruff>=0.4",
+    "mypy>=1.8",
+    "pandas>=2.0",
+    "matplotlib>=3.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/sablier-it/finval"
+Repository = "https://github.com/sablier-it/finval"
+Issues = "https://github.com/sablier-it/finval/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/finval"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]  # line length handled by formatter
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --tb=short"

finval-0.1.0/src/finval/__init__.py

@@ -0,0 +1,29 @@
+"""finval — rigorous validation for synthetic financial time series.
+
+Quick start:
+
+    import finval
+
+    # synthetic and real are (n_samples, n_features) arrays of returns
+    report = finval.validate(synthetic, real)
+    print(report.summary())
+    report.to_dict()
+
+For path-level validation with drawdowns and calibration:
+
+    # paths are (n_paths, horizon, n_features) arrays
+    report = finval.validate_paths(synthetic_paths, real_returns)
+"""
+
+from finval.core.result import MetricResult, ValidationReport
+from finval.validate import validate, validate_paths
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MetricResult",
+    "ValidationReport",
+    "validate",
+    "validate_paths",
+    "__version__",
+]

finval-0.1.0/src/finval/baselines/__init__.py

@@ -0,0 +1,32 @@
+"""Baseline generators for benchmarking synthetic financial data.
+
+A baseline is a simple generator that produces synthetic data from real
+data. Baselines are not meant to be good models — they're meant to be
+reference points so users can answer "is my fancy model actually better
+than X?" where X is a trivially simple generator.
+
+Three baselines ship with finval:
+
+- `gaussian`: Multivariate Gaussian with the empirical mean and covariance
+  of the real data. No temporal structure, no tails, no vol clustering.
+  This is the minimum bar any generative model should clear.
+
+- `historical_bootstrap`: Random sampling (with replacement) from real
+  returns. Reproduces marginals and joint distribution exactly in
+  expectation, but destroys all temporal structure (no ACF, no leverage).
+
+- `block_bootstrap`: Moving-block bootstrap preserves local dependence.
+  This is the strongest simple baseline — it reproduces short-range
+  temporal structure and most stylized facts at the cost of exact
+  marginal duplication. A generative model that beats block bootstrap
+  on all metrics is genuinely doing something new.
+"""
+
+from finval.baselines.gaussian import gaussian_baseline
+from finval.baselines.historical import block_bootstrap, historical_bootstrap
+
+__all__ = [
+    "gaussian_baseline",
+    "historical_bootstrap",
+    "block_bootstrap",
+]

finval-0.1.0/src/finval/baselines/gaussian.py

@@ -0,0 +1,64 @@
+"""Multivariate Gaussian baseline.
+
+Fits a multivariate normal to the real returns and samples from it.
+This is the naive "Gaussian i.i.d." benchmark. A model that can't beat
+this on temporal metrics is not capturing any time structure.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def gaussian_baseline(
+    real: np.ndarray,
+    n_samples: int | None = None,
+    n_paths: int | None = None,
+    path_length: int | None = None,
+    seed: int = 42,
+) -> np.ndarray:
+    """Generate samples from a multivariate Gaussian fit to real returns.
+
+    Two output modes:
+
+    1. Flat mode (n_samples given): returns shape (n_samples, n_features),
+       matching the format expected by distribution / dependence metrics.
+
+    2. Path mode (n_paths and path_length given): returns shape
+       (n_paths, path_length, n_features), matching the format expected
+       by temporal and path metrics. Each row within a path is an
+       independent draw — there is no temporal structure.
+
+    Args:
+        real: (n_obs, n_features) real return series used to fit mean+cov.
+        n_samples: Number of flat samples to return.
+        n_paths: Number of paths to return (requires path_length).
+        path_length: Length of each path.
+        seed: RNG seed.
+
+    Returns:
+        numpy array of shape (n_samples, n_features) or (n_paths, path_length, n_features).
+    """
+    real = np.asarray(real)
+    if real.ndim != 2:
+        raise ValueError(f"real must be 2D, got shape {real.shape}")
+
+    mean = np.nanmean(real, axis=0)
+    # Handle NaN by dropping rows before covariance
+    clean = real[~np.any(np.isnan(real), axis=1)]
+    if len(clean) < 2:
+        raise ValueError("need at least 2 clean rows to fit covariance")
+    cov = np.cov(clean, rowvar=False)
+    # Regularize to ensure positive-definite
+    d = cov.shape[0]
+    cov = cov + 1e-10 * np.eye(d)
+
+    rng = np.random.default_rng(seed)
+
+    if n_samples is not None:
+        return rng.multivariate_normal(mean, cov, size=n_samples)
+
+    if n_paths is not None and path_length is not None:
+        return rng.multivariate_normal(mean, cov, size=(n_paths, path_length))
+
+    raise ValueError("must specify either n_samples or (n_paths and path_length)")