Add ssvi

[lsbardel]

No description provided.

[Copilot]

Pull request overview

This PR adds an SSVI (Surface SVI) volatility parametrisation to the options module, along with documentation and site enhancements to support bibliographic cross-references and richer MkDocs output.

Changes:

• Add SSVI model with calibration helpers (fit, fit_surface) and comprehensive unit tests.
• Improve docs bibliography linking and styling (BibTeX entries + MkDocs config updates), and add an API docs page for SSVI.
• Miscellaneous robustness/typing tweaks across app APIs and options pricing.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
quantflow/ta/paths.py	Adds typing annotation for tau list in Hurst exponent calculation.
quantflow/options/svi.py	Updates SVI docstring to link to bibliography entries.
quantflow/options/surface.py	Forces Black price sum to float before sigfig/Decimal conversion.
quantflow/options/ssvi.py	Introduces new SSVI model, analytics, and calibration routines.
quantflow_tests/test_ssvi.py	Adds tests covering SSVI shape, variance/IV, arbitrage checks, and calibration.
pyproject.toml	Bumps pandas + dev tooling minimum versions.
mkdocs.yml	Adds site description, nav entry for SSVI, enables md_in_html, and includes extra CSS.
docs/stylesheets/bibliography.css	Adds bibliography entry highlighting/styling.
docs/references.bib	Adds Gatheral SVI and Gatheral-Jacquier references.
docs/contributing.md	Tightens wording around responsibility for AI-assisted contributions.
docs/bibliography.md	Wrapes bibliography entries for styling and fragment targeting.
docs/bib2md.py	Changes bibliography generator output to emit wrapped entries.
docs/api/options/ssvi.md	Adds mkdocstrings page for quantflow.options.ssvi.SSVI.
app/utils/paths.py	Injects social OpenGraph/Twitter meta tags into MkDocs pages.
app/api/volatility.py	Ensures ttm_grid is JSON-friendly (float list).
app/api/cointegration.py	Suppresses ComplexWarning and coerces eigenvector to real values.
.github/instructions/release.instructions.md	Adds applyTo front matter.
.github/instructions/makefile.instructions.md	Adds applyTo front matter.
.github/copilot-instructions.md	Fixes documented test command and doc examples output path.

Comments suppressed due to low confidence (2)

quantflow/options/ssvi.py:160

• fit() uses np.interp(0.0, k_arr, w_obs) and then runs least-squares without checking that inputs are non-empty, same-shape, and sorted by k. np.interp requires an increasing x-grid, and empty/mismatched inputs will currently produce nan initial guesses or broadcast errors.

        k_arr = np.asarray(k, dtype=float)
        iv_arr = np.asarray(iv, dtype=float)
        w_obs = iv_arr**2 * ttm

        atm_var = float(np.interp(0.0, k_arr, w_obs)) if k_arr.size else w_obs.mean()
        x0 = [0.0, 1.0, max(atm_var, 1e-4)]

quantflow/options/ssvi.py:213

• fit_surface() collects slices without validating/sorting each (k, iv) pair. This can break the ATM interpolation (np.interp expects sorted k) and can yield nan initial thetas if a slice is empty.

        data = []
        thetas0 = []
        for k, iv, ttm in slices:
            k_arr = np.asarray(k, dtype=float)
            iv_arr = np.asarray(iv, dtype=float)
            w_obs = iv_arr**2 * ttm
            data.append((k_arr, w_obs))
            atm = float(np.interp(0.0, k_arr, w_obs)) if k_arr.size else w_obs.mean()
            thetas0.append(max(atm, 1e-4))

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.21739% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.85%. Comparing base (5e16f37) to head (9361d70).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
app/utils/paths.py	18.18%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #86      +/-   ##
==========================================
+ Coverage   88.75%   88.85%   +0.09%     
==========================================
  Files          84       85       +1     
  Lines        5142     5229      +87     
==========================================
+ Hits         4564     4646      +82     
- Misses        578      583       +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.