docs: bring README up to v2.3 and add the Python binding README (#125)

Adds v2.1-v2.3 coverage: ArbitrageScanConfig scan grids, DataFilter / WeightingScheme / warm-start calibration controls, and the BoundaryLocalVol small-time adapter. Install snippets move to 2.3, the module tree gains the calibration module, and the changelog table lists v2.1-v2.3 with pre-1.0 history deferred to CHANGELOG.md.

Drops the "production-ready" framing and restates the query benchmark as "20 ns or less", matching the Criterion table.

python/README.md is new; the Bindings section now links to it directly.

Author: pandashark

README.md

@@ -5,9 +5,9 @@
 [![docs.rs](https://docs.rs/volsurf/badge.svg)](https://docs.rs/volsurf)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-Production-ready volatility surface construction for equity and FX derivatives.
+Volatility surface construction for equity and FX derivatives.
 
-`volsurf` builds implied volatility surfaces from market data, calibrates parametric smile models (SVI, SABR, SSVI), detects butterfly and calendar arbitrage, and provides sub-20ns vol queries suitable for real-time pricing engines.
+`volsurf` builds implied volatility surfaces from market data, calibrates parametric smile models (SVI, SABR, SSVI), and detects butterfly and calendar arbitrage. Vol queries take 20 ns or less, fast enough for real-time pricing engines.
 
 ## Features
 
@@ -28,6 +28,12 @@ Production-ready volatility surface construction for equity and FX derivatives.
 - Calendar spread arbitrage via cross-tenor variance monotonicity
 - Analytical calendar arbitrage for SSVI surfaces
 - Combined `SurfaceDiagnostics` report
+- Configurable scan grids via `ArbitrageScanConfig` on `is_arbitrage_free_with()` and `diagnostics_with()`
+
+**Calibration Control**
+- `DataFilter` drops wing strikes, sub-floor vols, and vol cliffs before fitting
+- `WeightingScheme` weights the least-squares fit by vega or uniformly (Zeliade 2009, Hagan 2002)
+- Warm-starting from prior parameters; SVI falls back to grid search when a seeded fit diverges
 
 **Implied Volatility**
 - **Black** (lognormal) implied vol via Jackel rational approximation (near-machine-precision)
@@ -36,6 +42,7 @@ Production-ready volatility surface construction for equity and FX derivatives.
 
 **Local Volatility**
 - **Dupire** local vol extraction (Dupire 1994) from any `VolSurface` via finite differences
+- **Boundary adapter** -- `with_boundary()` evaluates short expiries at a floor, avoiding the Dupire denominator blow-up as total variance goes to zero
 
 **Design**
 - No global state -- evaluation date is a parameter, not a singleton
@@ -49,13 +56,13 @@ Production-ready volatility surface construction for equity and FX derivatives.
 
 ```toml
 [dependencies]
-volsurf = "2.0"
+volsurf = "2.3"
 ```
 
 Optional features:
 
 ```toml
-volsurf = { version = "2.0", features = ["parallel", "logging"] }
+volsurf = { version = "2.3", features = ["parallel", "logging"] }
 ```
 
 | Feature | Description |
@@ -171,6 +178,8 @@ use volsurf::OptionType;
 let vol = BlackImpliedVol::compute(10.45, 100.0, 100.0, 1.0, OptionType::Call)?;
 ```
 
+Runnable programs for every layer live in [`examples/`](examples/). Run one with `cargo run --example local_vol`.
+
 ## Architecture
 
 Five-layer pipeline following the natural domain flow:
@@ -184,6 +193,7 @@ Option Prices -> Implied Vol -> Smile -> Surface -> Local Vol
 
 ```
 volsurf
+├── calibration    DataFilter, WeightingScheme, apply_filter
 ├── conventions    StickyKind, log_moneyness, forward_price
 ├── error          VolSurfError, Result<T>
 ├── implied
@@ -194,14 +204,14 @@ volsurf
 │   ├── svi        SviSmile (Gatheral 2006)
 │   ├── sabr       SabrSmile (Hagan 2002)
 │   ├── spline     SplineSmile (cubic on variance)
-│   └── arbitrage  ArbitrageReport, ButterflyViolation
+│   └── arbitrage  ArbitrageReport, ButterflyViolation, ArbitrageScanConfig
 ├── surface
 │   ├── ssvi       SsviSurface (Gatheral-Jacquier 2014)
 │   ├── essvi      EssviSurface, EssviSlice (Hendriks-Martini 2019)
 │   ├── piecewise  PiecewiseSurface (per-tenor interpolation)
 │   ├── builder    SurfaceBuilder, SmileModel
 │   └── arbitrage  SurfaceDiagnostics, CalendarViolation
-├── local_vol      LocalVol trait, DupireLocalVol (Dupire 1994)
+├── local_vol      LocalVol trait, DupireLocalVol (Dupire 1994), BoundaryLocalVol
 └── types          Strike, Tenor, Vol, Variance, OptionType
 ```
 
@@ -246,27 +256,27 @@ Measured with Criterion.rs on Apple Silicon. All performance targets exceeded.
 pip install volsurf
 ```
 
-Built with PyO3. See [`python/`](python/) for usage and API docs.
+Built with PyO3. See [`python/README.md`](python/README.md) for the API and usage examples.
 
 ### WebAssembly
 
 ```bash
 wasm-pack build wasm/ --target web
 ```
 
-Built with wasm-bindgen. See [`wasm/README.md`](wasm/README.md) for JavaScript API and usage examples.
+Built with wasm-bindgen. v2.3 added implied vol, conventions, and local vol, so the WASM bindings now cover all five layers. See [`wasm/README.md`](wasm/README.md) for the JavaScript API and usage examples.
 
 ## Changelog
 
+See [CHANGELOG.md](CHANGELOG.md) for the full history. Recent releases:
+
 | Version | Name | Key Features |
 |---------|------|--------------|
-| **v2.0** | **Type-Safe Inputs** | **Strike/Tenor newtypes for all API inputs** |
+| **v2.3** | **WASM Parity** | **Implied vol, conventions, and local vol in the WASM bindings** |
+| v2.2 | Local Vol Boundary | `BoundaryLocalVol` small-time adapter, `with_boundary()` |
+| v2.1 | API Polish | `model_name()`, `tenors()`, configurable arbitrage scans and calibration |
+| v2.0 | Type-Safe Inputs | `Strike`/`Tenor` newtypes for all API inputs |
 | v1.0 | Stable | API stability, PyO3 bindings, WASM target |
-| v0.4 | Hardening | Coverage gaps, tracing diagnostics, dead code removal |
-| v0.3 | Production Grade | eSSVI surface + calibration, parallel construction, dividend yield |
-| v0.2.1 | | Normal/Displaced IV, Dupire local vol, serde validation, CI |
-| v0.2 | Market Ready | SABR, SSVI, calendar arbitrage, surface diagnostics |
-| v0.1 | First Light | SVI smile, cubic spline, ragged grid surface, builder API |
 
 ## References
 

python/README.md

@@ -0,0 +1,215 @@
+# volsurf (Python)
+
+Python bindings for [volsurf](https://github.com/volsurf-rs/volsurf), a volatility
+surface library for equity and FX derivatives. Built with PyO3.
+
+## Install
+
+```bash
+pip install volsurf
+```
+
+Requires Python 3.9 or later. NumPy is the only runtime dependency.
+
+To build from source:
+
+```bash
+maturin develop --release -m python/Cargo.toml
+```
+
+## Build a surface
+
+`SurfaceBuilder` sets its options through method calls rather than chaining, so
+call each setter on its own line.
+
+```python
+from volsurf import SurfaceBuilder, SmileModel
+
+strikes = [80.0, 90.0, 95.0, 100.0, 105.0, 110.0, 120.0]
+vols = [0.28, 0.24, 0.22, 0.20, 0.22, 0.24, 0.28]
+
+b = SurfaceBuilder()
+b.spot(100.0)
+b.rate(0.05)
+b.add_tenor(0.25, strikes, vols)
+b.add_tenor(1.00, strikes, vols)
+surface = b.build()
+
+surface.black_vol(0.5, 100.0)      # vol at any (expiry, strike)
+surface.black_variance(0.5, 100.0) # total variance
+surface.tenors()                   # [0.25, 1.0]
+```
+
+Pick a smile model with `b.model(...)`. `SmileModel.svi()` is the default and
+needs 5 strikes per tenor, `SmileModel.cubic_spline()` needs 3, and
+`SmileModel.sabr(beta)` needs 4.
+
+```python
+b.model(SmileModel.sabr(0.5))
+b.dividend_yield(0.02)
+b.add_tenor_with_forward(0.25, strikes, vols, 101.2)
+```
+
+## Query a smile
+
+`smile_at()` returns the calibrated section for one tenor.
+
+```python
+smile = surface.smile_at(0.5)
+smile.vol(105.0)
+smile.density(105.0)   # risk-neutral density (Breeden-Litzenberger)
+smile.forward          # a property, as are smile.expiry and smile.model_name
+```
+
+Sections taken from a `SurfaceBuilder` surface report `model_name == "CubicSpline"`.
+The builder fits your chosen model per tenor, then hands back a spline through the
+fitted variances. Construct a model directly if you need its own parameters.
+
+Construct smiles directly when you already have parameters, or calibrate one
+tenor at a time:
+
+```python
+from volsurf import SviSmile, SabrSmile, SplineSmile
+
+svi = SviSmile(100.0, 1.0, 0.04, 0.4, -0.4, 0.0, 0.2)  # forward, expiry, a, b, rho, m, sigma
+sabr = SabrSmile(100.0, 1.0, 0.20, 0.5, -0.3, 0.4)     # forward, expiry, alpha, beta, rho, nu
+
+market = [(80.0, 0.28), (90.0, 0.24), (100.0, 0.20), (110.0, 0.24), (120.0, 0.28)]
+fitted = SviSmile.calibrate(100.0, 1.0, market)
+```
+
+## Global surfaces
+
+`SsviSurface` and `EssviSurface` parameterize the whole surface at once. Both
+take parameters directly or calibrate from per-tenor market data.
+
+```python
+from volsurf import SsviSurface, EssviSurface
+
+ssvi = SsviSurface(
+    rho=-0.3, eta=0.5, gamma=0.5,
+    tenors=[0.25, 0.5, 1.0],
+    forwards=[100.0, 100.0, 100.0],
+    thetas=[0.04, 0.08, 0.16],   # ATM total variance
+)
+
+essvi = EssviSurface.calibrate(
+    [market_3m, market_1y],   # per-tenor [(strike, vol), ...]
+    [0.25, 1.0],              # tenors
+    [100.0, 100.0],           # forwards
+)
+```
+
+To see how well each tenor fit, run the first stage on its own.
+`EssviSurface.fit_per_tenor(market_data, tenors, forwards)` returns a list of
+`PerTenorFit` — each with `rms_error`, `theta`, and the fitted `svi` slice — and
+`EssviSurface.from_per_tenor(fits)` turns that list into the surface.
+
+```python
+fits = EssviSurface.fit_per_tenor([market_3m, market_1y], [0.25, 1.0], [100.0, 100.0])
+print([f.rms_error for f in fits])
+surface = EssviSurface.from_per_tenor(fits)
+```
+
+## NumPy grids
+
+Every surface exposes `vol_grid(expiries, strikes)`, which returns a
+`(len(expiries), len(strikes))` array of `float64`. Smiles expose
+`vol_array(strikes)`.
+
+```python
+import numpy as np
+
+vols = surface.vol_grid(np.array([0.25, 0.5, 1.0]), np.array([90.0, 100.0, 110.0]))
+vols.shape   # (3, 3)
+```
+
+Grid values match the scalar calls to within 1e-14, so use whichever fits the
+calling code.
+
+## Arbitrage checks
+
+```python
+report = smile.is_arbitrage_free()
+report.is_free                 # property
+report.butterfly_violations    # property, a list
+report.worst_violation()       # method
+
+diag = surface.diagnostics()
+for v in diag.calendar_violations:
+    print(v)
+```
+
+`is_arbitrage_free_with(config)` and `diagnostics_with(config)` take an
+`ArbitrageScanConfig` when you want a denser or sparser scan grid than the
+default.
+
+## Calibration control
+
+`DataFilter` drops points before the fit. `WeightingScheme` sets how the
+remaining points are weighted.
+
+```python
+from volsurf import DataFilter, WeightingScheme
+
+f = DataFilter(max_log_moneyness=0.5, min_vol=0.01)  # drop far wings and sub-floor quotes
+
+b.data_filter(f)
+b.weighting(WeightingScheme.vega())
+```
+
+The same options reach single-tenor fits through
+`SviSmile.calibrate_with_config(forward, expiry, market_vols, filter, weighting, seed)`.
+Pass `seed` to warm-start from prior parameters.
+
+## Implied volatility
+
+Prices are undiscounted and quoted on the forward.
+
+```python
+from volsurf import BlackImpliedVol, NormalImpliedVol, DisplacedImpliedVol
+from volsurf import black_price, normal_price, displaced_price, OptionType
+
+price = black_price(100.0, 100.0, 0.20, 1.0, OptionType.Call)
+vol = BlackImpliedVol.compute(price, 100.0, 100.0, 1.0, OptionType.Call)
+```
+
+Use `NormalImpliedVol` (Bachelier) when forwards can go negative, and
+`DisplacedImpliedVol(beta)` to interpolate between normal (`beta=0`) and Black
+(`beta=1`).
+
+Conventions helpers: `log_moneyness(strike, forward)`, `moneyness(strike, forward)`,
+and `forward_price(spot, rate, dividend_yield, expiry)`.
+
+## Local volatility
+
+`DupireLocalVol` wraps a `Surface`, `SsviSurface`, or `EssviSurface` and extracts
+local vol by finite differences.
+
+```python
+from volsurf import DupireLocalVol
+
+lv = DupireLocalVol(surface)          # or DupireLocalVol(surface, bump_size=1e-3)
+lv.local_vol(0.5, 100.0)
+```
+
+## Serialization
+
+Model structs round-trip through JSON with `to_json()` and `from_json()`.
+
+```python
+s = ssvi.to_json()
+restored = SsviSurface.from_json(s)
+```
+
+## Errors
+
+Invalid inputs raise `ValueError` with the underlying message: negative vols,
+zero or negative forwards, non-finite values, too few strikes for the chosen
+model, and calibration failures.
+
+## Tests
+
+```bash
+pytest python/tests
+```

python/src/local_vol.rs

@@ -1,10 +1,13 @@
 use std::sync::Arc;
 
+use pyo3::exceptions::PyTypeError;
 use pyo3::prelude::*;
+use pyo3::types::PyAny;
 use volsurf::local_vol::{DupireLocalVol, LocalVol};
-use volsurf::{Strike, Tenor};
+use volsurf::{Strike, Tenor, VolSurface};
 
 use crate::error::to_py_err;
+use crate::surface::{PyEssviSurface, PySsviSurface};
 use crate::types::PySurface;
 
 #[pyclass(frozen, name = "DupireLocalVol")]
@@ -16,8 +19,21 @@ pub struct PyDupireLocalVol {
 impl PyDupireLocalVol {
     #[new]
     #[pyo3(signature = (surface, bump_size=None))]
-    fn new(surface: &PySurface, bump_size: Option<f64>) -> PyResult<Self> {
-        let mut lv = DupireLocalVol::new(Arc::clone(&surface.inner));
+    fn new(surface: &Bound<'_, PyAny>, bump_size: Option<f64>) -> PyResult<Self> {
+        let surface: Arc<dyn VolSurface> =
+            if let Ok(surface) = surface.extract::<PyRef<PySurface>>() {
+                Arc::clone(&surface.inner)
+            } else if let Ok(surface) = surface.extract::<PyRef<PySsviSurface>>() {
+                Arc::new(surface.inner.clone())
+            } else if let Ok(surface) = surface.extract::<PyRef<PyEssviSurface>>() {
+                Arc::new(surface.inner.clone())
+            } else {
+                return Err(PyTypeError::new_err(
+                    "surface must be a Surface, SsviSurface, or EssviSurface",
+                ));
+            };
+
+        let mut lv = DupireLocalVol::new(surface);
         if let Some(h) = bump_size {
             lv = lv.with_bump_size(h).map_err(to_py_err)?;
         }

python/src/surface.rs

@@ -46,7 +46,7 @@ macro_rules! impl_vol_grid {
 
 #[pyclass(frozen, name = "SsviSurface")]
 pub struct PySsviSurface {
-    inner: SsviSurface,
+    pub(crate) inner: SsviSurface,
 }
 
 #[pymethods]
@@ -208,7 +208,7 @@ impl PyPerTenorFit {
 
 #[pyclass(frozen, name = "EssviSurface")]
 pub struct PyEssviSurface {
-    inner: EssviSurface,
+    pub(crate) inner: EssviSurface,
 }
 
 #[pymethods]