# stochastic-rs — API audit (2026-04)

> Az audit tárgya **kizárólag az API-felület és a modul-szintű konzisztencia**.
> Nem foglalkozik az algoritmikus helyességgel és a numerikai pontossággal.
> Verzió: `2.0.0-beta.1`, edition `2024`.

---

## 0. Tartalom

- [1. Magas szintű állapot](#1-magas-szintű-állapot)
- [2. Globális (egész cratet érintő) problémák](#2-globális-egész-cratet-érintő-problémák)
- [3. Modulonkénti megállapítások](#3-modulonkénti-megállapítások)
- [4. Cross-module integráció — hol szakad meg a pipeline](#4-cross-module-integráció)
- [5. Workspace-szé alakítás opciója](#5-workspace-szé-alakítás-opciója)
- [6. Prioritizált javaslatok](#6-prioritizált-javaslatok)
- [Függelék — számok és táblázatok](#függelék)

---

## 1. Magas szintű állapot

A crate jelenleg **monolitikus** (egy `lib`, egy `cdylib`), 8 publikus root‑modullal:

```
stochastic_rs::
├── ai            (feature = "ai")
├── copulas
├── distributions
├── quant
├── simd_rng
├── stats
├── stochastic
├── traits
└── visualization
```

**Méret (becsült publikus felület):**

| Réteg | Publikus típusok | ProcessExt impl | PricerExt/ModelPricer impl |
|---|---|---|---|
| `stochastic` | ~140 process struct + ~10 utility | 140 | 0 |
| `quant` | ~120 (pricerek, kalibrátorok, kalendárium, instrumentumok…) | 0 | ~40 |
| `distributions` | 19 `Simd*` + `ComplexDistribution` | 0 | 0 |
| `copulas` | bivariate (~10) + multivariate (3) + 2D helperek (3) | 0 | 0 |
| `stats` | 17+ submodul, kevert API stílussal | 0 | 0 |
| `ai` | 4 `*Nn` modell + `DataSet`, `TrainConfig` | 0 | 0 |
| `visualization` | 1 `GridPlotter` + 1 trait | 0 | 0 |

**Build‑ és feature‑mátrix:** 12 feature flag (`ai`, `python`, `openblas`, `gpu`, `gpu-cuda`, `gpu-wgpu`, `cuda-native`, `metal`, `accelerate`, `jemalloc`, `mimalloc`, `yahoo`, `hotpath`).
A `lib.rs` csak `pub mod` deklarációkat tartalmaz — **prelude / re‑export nincs**.

---

## 2. Globális (egész cratet érintő) problémák

### 2.1. Nincs prelude / nincs root re‑export

Az `src/lib.rs` 33 sor; a felhasználó kénytelen 4–5 szegmensű path‑eket írni:

```rust
use stochastic_rs::quant::pricing::heston::HestonPricer;
use stochastic_rs::stochastic::diffusion::gbm::GBM;
use stochastic_rs::distributions::normal::SimdNormal;
use stochastic_rs::stats::heston_mle::nmle_heston;
```

Sem `prelude`, sem rövidített `pub use` nincs. A modulok közötti vegyes import miatt a `use` blokk minden példában hosszú.

**Hatás:** rossz felhasználói élmény, kötelező mély struktúra‑ismeret.

---

### 2.2. Modul‑root fájlok üresek

A 8 root‑szintű modulfájl (`stochastic.rs`, `quant.rs`, `distributions.rs`, `stats.rs`, `copulas.rs`, `ai.rs`, `traits.rs`, `visualization.rs`) közül **csak `traits.rs` és `quant.rs` tartalmaz közös típust** (`OptionType`, `OptionStyle`, `Moneyness`, `LossMetric`, `CalibrationLossScore`).
A többi tisztán `pub mod` lista. Sem közös prelude, sem facade típusok, sem domain‑szintű re‑exportok.

```rust
// src/copulas.rs (teljes tartalma)
pub mod bivariate;
pub mod correlation;
pub mod empirical;
#[cfg(feature = "openblas")]
pub mod multivariate;
pub mod samples;
pub mod univariate;
```

**Lehetne például:**

```rust
pub mod bivariate;
pub mod multivariate;
pub mod univariate;
// ...
pub use bivariate::{Clayton, Frank, Gumbel, Independence};
pub use samples::{ClaytonCopula2D, GaussianCopula2D, GumbelCopula2D};
```

---

### 2.3. Konstruktor‑konvenciók szétfutottak

| Minta | Hol | Példa |
|---|---|---|
| Pozícionális `new(...)` 2–4 arggal | egyszerű processek | `Bm::new(n, t)` |
| Pozícionális `new(...)` 10+ arggal | komplex processek/pricerek | `Heston::new(s0, v0, kappa, theta, sigma, rho, mu, n, t, pow, use_sym)` |
| `new(...)` + `.builder(...)` | `BSMPricer`, `HestonPricer` | mutable builder chaining |
| Csak `Default` | `CarrMadanPricer` | nincs `new` |
| Public field literal | `SabrModel`, `HestonParams` | `SabrModel { alpha, beta, rho, nu }` |
| `Option<T>` opcionális mezők | minden process | `t: Option<T>`, `x0: Option<T>` |

**A 6 különböző stílus** miatt nincs egyértelmű felhasználói minta. A 10+ paraméteres `new` hívások hibára érzékenyek (sorrendcsere).

---

### 2.4. `t: Option<T>` mindenhol — dokumentálatlan default

A `ProcessExt` implementációkban `t` (időhorizont) opcionális, és `None` esetén implicit `T::one()` (=1.0). Ez **nincs trait‑szinten dokumentálva**. Egyes processek (interest rate, vol modellek) értelmezhetetlenné válnak `t = 1` defaulttal — a felhasználónak nincs jelzése arról, hogy ezt explicit kell megadni.

**Javaslat (tárgyalási pont):** vagy kötelezővé tenni (`t: T`), vagy egy `Horizon` enum (`Years(T)`, `Days(usize)`, `Default`) dokumentált alapértékkel.

---

### 2.5. Output‑típus nem egységes

| Minta | Hol | Példa |
|---|---|---|
| `Array1<T>` | diffusion, jump, autoregressive, autoregressive | `GBM`, `Merton` |
| `[Array1<T>; 2]` | volatility (Heston-style) | `Heston`, `Bergomi` |
| `Array2<T>` | interest curves, sheet | `BGM`, `HJM`, `WuZhangD`, `FBS` |
| `[Array1<T>; 2]` _vagy_ `Array2<T>` | volatility 2-state | `RoughHeston` (impl-függő) |

A trait `Output: Send` túl laza: a felhasználónak kell megnéznie az impl‑t, hogy megtudja a dimenziót. **Nincs marker trait** (pl. `OneDimensional`, `TwoDimensional`) ami ezt típusszinten kifejezné.

---

### 2.6. Naming inkonzisztencia

A `stochastic` modulban három családra szakad a névadás:

- **Teljes nevek:** `Vasicek`, `HullWhite`, `Heston`, `Bergomi`, `Logistic`, `Gompertz`, `Verhulst`, `Merton`
- **Akronimák, ALL CAPS:** `GBM`, `OU`, `CIR`, `CEV`, `BGM`, `HJM`, `KOU`, `VG`, `NIG`, `CGMY`
- **Hibrid:** `JumpFOU`, `LevyDiffusion`, `BatesSVJ`, `RoughHeston`, `FBatesSVJ`

**Konkrét konfliktusok:**
- `OU` vs `Vasicek` — gyakorlatilag ugyanaz az SDE, két módon implementálva.
- `GBM` (akronim) vs `Logistic` (teljes név) — ugyanaz a modul.
- `KOU` ALL CAPS vs `Bates1996` (verziószám a névben).

A `quant::pricing` ugyanezt megismétli: `BSMFourier`, `HestonFourier` vs `SabrModel`, `HscmModel` (suffix `Fourier` vs `Model` ugyanazon réteg).

**A SIMD‑es disztribúciók viszont konzisztensek:** mindegyik `Simd<Name>` (kivétel: `ComplexDistribution`).

---

### 2.7. Trait coverage lyukak

| Trait | Definíció | Tényleges használat |
|---|---|---|
| `DistributionExt` | `traits.rs:239` | **0 implementáció** — minden 12 metódus default `0.0` |
| `MalliavinExt`, `Malliavin2DExt` | `traits.rs:583`, `:616` | **0 implementáció** a process struktúrákon |
| `Default`, `Clone`, `Debug` | derive | szórványos, nem szisztematikus |
| `ToModel` | `traits.rs:554` | **hiányzik** `SabrCapletCalibrator`-ban, `HullWhiteSwaptionCalibrator`-ban |
| `ModelPricer` | `traits.rs:564` | rács‑/lattice‑modellek nem implementálják |

A `DistributionExt` jelenleg **deklaratív szemét** — definiálva van, de nem implementálva. Vagy implementálni kell, vagy törölni.

---

### 2.8. SIMD / GPU acceleration aszimmetria

- **GPU sample metódusok** (`sample_gpu`, `sample_cuda_native`, `sample_metal`, `sample_accelerate`) csak az `FGN` és `FBM` processeken vannak override‑olva.
- **Drága modellek (Heston, RoughBergomi, CIR2F, BGM, HJM)** csak CPU.
- A `sample_par` mindenhol elérhető (rayon), de nincs egységes batch vs single‑path konvenció.

---

### 2.9. Python binding aszimmetriák

A `python.rs` 103 osztályt regisztrál, **macro‑driven** (`py_process_1d!`, `py_process_2x1d!`, `py_process_2d!`, `py_distribution!`, `py_distribution_int!`).

**Hiányoznak:**
- AI modul (`HestonNn`, `OneFactorNn`, `RoughBergomiNn`, `StochVolNn`, `TrainConfig`) → 0 osztály
- `visualization::GridPlotter`
- `quant::pricing` pricerek (csak processek mennek át)
- `quant::calibration` kalibrátorok
- `stats` becslők (nincs Python wrapper a Hurst / fOU / heston_mle becslőkre)
- `copulas` (BivariateExt / MultivariateExt nincs Python‑ben)
- `SeedExt` trait — Python `seed: int` paramétert kap, de a determinisztikus seed‑propagáció nem érhető el

A Python API **csak a sampling oldalt** fedi le, a quant pipeline‑t nem.

---

### 2.10. `quant.rs` és `python.rs` lokális típusai szétszórva

- `OptionType`, `OptionStyle`, `Moneyness` → `quant.rs`
- `LossMetric`, `CalibrationLossScore` → `quant.rs`
- `CalibrationHistory` → `quant/calibration/calibration.rs` (hivatkozott, de nem világos exposure)
- `ReturnType` → `quant/yahoo.rs` (csak `yahoo` feature alatt)

Ez OK, de **inkább `quant::types` modulban** lenne a helyük.

---

## 3. Modulonkénti megállapítások

### 3.1. `stochastic` (140+ process)

**Erősségek:**
- `ProcessExt<T>` szinte mindenre implementálva, egységes `sample()` / `sample_par()` API
- 13 jól tagolt almodul (autoregressive, correlation, diffusion, interest, isonormal, ito, jump, malliavin, mc, noise, process, rough, sde, sheet, volatility)
- Generic precision (`f32`/`f64`) konzisztens

**Problémák:**
- **Output dimensziók kevertek** (lásd 2.5)
- **Naming kaotikus** (lásd 2.6)
- **Generic distribution kötés** (`Merton<T, D, S>`) ütközik a Python wrappers szignatúráival
- `sde::Sde<T, F, G>` *generikus solver* külön él a fix processzektől — **két különböző API ugyanarra**: vagy egy konkrét struct, vagy `Sde::new(drift, diff, …).sample()`
- `ito::ItoCalculator`, `mc::Mlmc`, `mc::Lsm`, `mc::HaltonSeq`, `mc::SobolSeq`, `isonormal::ISONormal`, `rough::RlKernel`, `rough::MarkovLift` — ezek **utility típusok**, nem implementálnak `ProcessExt`‑et — érdemes lenne `stochastic::utils` vagy `stochastic::numerics` névtérbe szervezni
- **`MalliavinExt` deklarált, sehol nem implementált** a `stochastic/malliavin.rs`-en kívül — a 600‑soros trait halott kód, vagy hiányos

### 3.2. `quant` (~120 típus)

**Két párhuzamos pricing‑réteg:**
1. **`PricerExt`‑pricerek** (BSM, Heston, Asian, Barrier, Kirk, Bjerksund‑Stensland, FiniteDifference, FdAsian, ChooserPricer, ForwardStartPricer, …) — *bundle data + logic*, builder/new mintával.
2. **`ModelPricer`‑modellek** (SABR, HSCM, RBergomi és minden `FourierModelExt` automatikusan) — *separated model & query*, vol‑surface pipeline‑hoz.

Ez **két felhasználói pattern** és nincs köztük bridge.

**Pipeline (vol_surface dokumentáció szerint):**

```
Calibrator → ToModel → ModelPricer → ModelSurface → ImpliedVolSurface
```

**Hol szakad meg:**
- `SabrCapletCalibrator` → nincs `ToModel`
- `HullWhiteSwaptionCalibrator` → nincs `ToModel`, nincs `ModelPricer` impl
- `lattice/*` (Hull‑White / Black‑Karasinski / G2++ tree) → nincs `ModelPricer`, nincs vol_surface integráció
- `instruments/*` (Cap, Floor, Swaption, Bond) → saját `VolatilityModel` trait‑et használnak, nem `ModelPricer`‑t
- `credit/*` → független ágon él, nincs köze a vol_surface‑hez

**Orphan modulok (semmi nem hivatkozik rájuk):**
- `quant::order_book` — 220 sor, kompletten független
- `quant::fourier_malliavin` — realized variance utilities, nem hívja sehol a kalibráció
- `quant::microstructure` — Almgren‑Chriss, Kyle, propagator → nincs feedback a pricinghez
- `quant::factors` — PCA, Fama‑MacBeth → nincs köze a pricinghez

**Inkonzisztens kalibráció‑output:**

| Calibrator | Visszatérés |
|---|---|
| `HestonCalibrator` | `HestonParams` (közvetlen) |
| `CgmysvCalibrator` | `CgmysvCalibrationResult` (wrapper) |
| `LevyCalibrator` | `LevyCalibrationResult` (variant‑függő modell) |
| `SabrCalibrator` | `SabrCalibrationResult` |
| `BSMCalibrator` | `BSMCalibrationResult` |

Néhol params struct, néhol result struct, néhol `Box<dyn ModelPricer>`. **Egységes return‑konvenció hiányzik.**

**Date/tau kezelés:**
- Pricerek: `tau: Option<f64>` + `eval/expiration: Option<NaiveDate>` + `TimeExt::tau_with_dcc`
- Kalibrátorok: csak előre kiszámolt `tau: f64` slice‑okat fogadnak

### 3.3. `distributions` (19 disztribúció)

**Erősségek:**
- Konzisztens `Simd<Name>` névadás (kivéve `ComplexDistribution`)
- Mindegyiken `fill_slice()` és `new()` / `with_seed()`
- Const‑generikus ziggurat buffer (`SimdNormal<T, const N: usize = 64>`)

**Problémák:**
- **`DistributionExt` 0 implementációval** — a 12 metódus mindenhol default `0.0` (lásd 2.7)
- 5 disztribúció (`binomial`, `complex`, `hypergeometric`, `lognormal`, `poisson`) **nem expozícióznak** `fill_slice_fast()`-et
- Csak `SimdUniform` implementál `rand_distr::Distribution<T>` — a többinél nincs scalar‑mintázás közvetlen API
- `SimdPoisson::new(lambda: f64)` — nem generikus `T`, miközben a struct generikus
- A `DistributionSampler<T>` trait `distributions.rs`‑ben él, **nincs re‑exportálva** a `traits` modulból

### 3.4. `copulas`

**Probléma‑1: Térbeli duplikáció.** Ugyanaz a copula család két helyen, két traitre:

| Bivariate (`BivariateExt`) | 2D helper (`NCopula2DExt`) |
|---|---|
| `bivariate::Clayton` | `samples::ClaytonCopula2D` |
| `bivariate::Gumbel` | `samples::GumbelCopula2D` |
| `bivariate::Frank` (impl) | `samples::GaussianCopula2D` |

Két különböző trait + két különböző fájl + két különböző konstruktor — ugyanazokra a copulákra.

**Probléma‑2: Multivariate / bivariate konstruktor‑aszimmetria:**

```rust
// bivariate
Clayton::new(theta: Option<f64>, tau: Option<f64>)

// multivariate
GaussianMultivariate::new()
GaussianMultivariate::new_with_corr(corr: Array2<f64>)
```

A bivariate Kendall tau‑val működik, a multivariate kovariancia‑mátrixszal — két különböző parametrizálás, nincs híd.

**Probléma‑3: `MultivariateExt` `feature = "openblas"` mögött rejtve.** A bivariate ágy mindig elérhető, a multivariate nem — de a felhasználói pattern‑mátrix nem szétdarabolható feature‑ek szerint.

### 3.5. `stats`

**Visszatérési típus káosz** — ugyanazon Hurst‑becslő család négy különböző stílusban:

| Becslő | Minta | Visszatérés |
|---|---|---|
| `fd::estimate_hurst` | szabad fn | `f64` |
| `fukasawa_hurst::estimate` | szabad fn | `FukasawaResult` (struct) |
| `fou_estimator::FOUParameterEstimationV1`–`V4` | mutáló struct | `(f64, f64, f64, f64)` tuple |
| `heston_mle::nmle_heston` | szabad fn | `HestonMleResult` |
| `heston_nml_cekf::nmle_cekf_heston` | szabad fn + `Config` | `HestonNMLECEKFResult` |

**Input típus káosz:**

| Becslő | Bemenet |
|---|---|
| `realized::*` | `ArrayView1<T>` (zero‑copy, generic) |
| `heston_mle::*` | `Array1<f64>` (owned) |
| `fukasawa_hurst::estimate` | `&[f64]` |
| `fou_estimator::*` | `Array1<f64>` (struct‑ban tárolva) |
| `fd::estimate_hurst` | `&ArrayView1<f64>` |
| `normality::*`, `stationarity::*` | `&[f64]` |

**5 bemeneti típus 5 hasonló jellegű time‑series becslőre.**

**Cross‑module hiány:**
- `distributions::normal::SimdNormal` és `stats::normality::*` (Jarque‑Bera, Shapiro‑Francia, Anderson‑Darling) **egymást nem ismerik**
- `distributions::pareto`, `distributions::alpha_stable` és `stats::tail_index` **egymást nem ismerik**
- `stochastic::diffusion::cir::CIR` és `stats::cir::sample` (egyszem fn) **egymást nem ismerik**

### 3.6. `ai`

**Önálló sziget.**
- Saját `Tensor` (candle‑core), saját `rand` használat (nem `simd_rng`)
- 3 modell (`HestonNn`, `OneFactorNn`, `RoughBergomiNn`) közös `StochVolNn` interfésszel — *belül konzisztens*
- **Nincs bridge** sem `ProcessExt`‑re (training data forrás), sem `ModelPricer`‑re (predikció output)
- **0 Python binding**

### 3.7. `visualization`

- 1 trait (`Plottable<T>`), 1 generic plotter (`GridPlotter`) — **belül konzisztens**, builder pattern
- Plotly HTML output, nincs PNG/SVG
- 3D surface plotting csak teszt‑szintű, public API hiányzik
- Nincs convenience fn‑halmaz (`plot_process()`, `plot_distribution()`, `plot_vol_surface()`)
- 0 Python binding

### 3.8. `simd_rng`

- Belül konzisztens (`SimdRng`, `SeedExt`, `Unseeded`, `Deterministic`)
- **Implementáció‑detail réteg**, mégis publikus
- `SeedExt` Python‑ből nem elérhető — a determinizmus reprodukciós láncolat törik a Python boundary‑n

### 3.9. `traits`

- 14 trait + 4 helper typedef egy 654 soros fájlban
- Domain‑szempontból kevert (`FloatExt` és `BivariateExt` egy fájlban)
- **Néhány trait halott kód**: `DistributionExt`, `MalliavinExt`, `Malliavin2DExt`, `NCopula2DExt`
- A 600+ soros monolit‑fájl **trait/-modul‑szintű hiba**: érdemes lenne `traits/{float,process,distribution,copula,pricing,malliavin}.rs`-re bontani

---

## 4. Cross-module integráció

### 4.1. Fontos pipeline‑ok és állapotuk

| Pipeline | Állapot | Megjegyzés |
|---|---|---|
| `simd_rng` → `distributions` → `stochastic` (sampling) | ✅ Működik | Egységes `T: FloatExt` + `RngCore` |
| `stochastic` → `quant::pricing` (Monte Carlo) | ⚠️ Részleges | MC pricerek (RBergomi, McBasket, McCliquet) eseti `ProcessExt` használat |
| `quant::market` → `quant::calibration` → `quant::pricing` (Fourier) → `quant::vol_surface` | ✅ Működik **a Fourier‑ágban** | `ToModel` + `FourierModelExt` blanket |
| `quant::market` → `quant::calibration` → `quant::pricing` (SABR/HSCM) → vol_surface | ✅ Működik | manuális `ModelPricer` impl |
| Caplet / Swaption kalibráció → vol_surface | ❌ Megszakad | hiányzó `ToModel` |
| `quant::lattice` → vol_surface | ❌ Nincs híd | rács‑modellek nem `ModelPricer` |
| `quant::credit` → bárhova | ❌ Sziget | önálló survival/hazard |
| `quant::microstructure` → `quant::pricing` | ❌ Sziget | execution kalibráció nem kerül vissza |
| `quant::factors` → `quant::portfolio` → `quant::risk` | ⚠️ Részleges | factors/portfolio nincs egységes interfész |
| `stats::*` → `quant::calibration` (mint seed) | ❌ Nincs híd | pl. `heston_mle::nmle_heston` nem etethető a `HestonCalibrator`‑ba |
| `distributions::normal` ↔ `stats::normality` | ❌ Nem ismerik egymást | |
| `ai::volatility::HestonNn` → `quant::pricing::HestonFourier` | ❌ Nincs híd | |
| `stochastic::*` → `visualization::GridPlotter` | ✅ Működik | `Plottable` trait blanket |
| Bármi → Python | ⚠️ Sampling‑only | quant/stats/ai/copulas nincs |

### 4.2. Konkrét hiányzó adapterek

1. **`stats::heston_mle::HestonMleResult` → `quant::pricing::HestonParams`** (most két különböző struct ugyanarra a 6 paraméterre)
2. **`stats::fou_estimator::*` → `quant::calibration` seed**
3. **`quant::calibration::HullWhiteCalibrationResult` → `quant::lattice::HullWhiteTree`**
4. **`ai::*Nn::predict_surface()` → `quant::vol_surface::ImpliedVolSurface`**
5. **`copulas::bivariate::*` → `stochastic::correlation::*`** (a copula‑függésű 2D folyamatok generálásához)
6. **`distributions::*` → `quant::risk::monte_carlo_var`** (custom sampler injekció)

---

## 5. Workspace-szé alakítás opciója

### 5.1. Javaslat — sub‑crate lebontás

A jelenlegi belső modul‑hierarchia 1:1 fordítható Cargo workspace‑re:

```
stochastic-rs/                   (workspace root)
├── Cargo.toml                    (workspace = { members = [...] })
├── crates/
│   ├── stochastic-rs-core/       — FloatExt, SimdFloatExt, ProcessExt, simd_rng, macros
│   ├── stochastic-rs-distributions/
│   ├── stochastic-rs-stochastic/ — sampling-only
│   ├── stochastic-rs-copulas/
│   ├── stochastic-rs-stats/
│   ├── stochastic-rs-quant/      — pricing, calibration, vol_surface, instruments
│   │     ├── stochastic-rs-quant-rates/    (lattice, curves, cashflows, bonds)
│   │     ├── stochastic-rs-quant-credit/   (CDS, hazard, Merton structural)
│   │     ├── stochastic-rs-quant-fx/
│   │     └── stochastic-rs-quant-microstructure/
│   ├── stochastic-rs-ai/         — feature-gated standalone
│   ├── stochastic-rs-viz/        — visualization
│   └── stochastic-rs-py/         — pyo3 wrappers (cdylib)
└── stochastic-rs/                — umbrella crate, csak `pub use`
```

A **`stochastic-rs` umbrella crate** csak re‑exportál:

```rust
// src/lib.rs (umbrella)
pub use stochastic_rs_core as core;
pub use stochastic_rs_distributions as distributions;
pub use stochastic_rs_stochastic as stochastic;
pub use stochastic_rs_quant as quant;
// ...
pub mod prelude {
    pub use stochastic_rs_core::traits::{FloatExt, ProcessExt, ModelPricer, ToModel};
    pub use stochastic_rs_quant::OptionType;
    // ...
}
```

### 5.2. Előnyök

| Előny | Részletek |
|---|---|
| **Compile time** | A felhasználó csak azt fordítja, amit használ. Pl. quant pricing nélküli sampling‑user 3–5× gyorsabb buildet kap. CI‑ben a per‑crate tesztelés is gyorsabb. |
| **Tisztább függőségi gráf** | `ndarray-linalg` (openblas), `candle-*` (ai), `pyo3` (python) eltűnik a base build‑ből. Most minden user fizet az `argmin`, `levenberg-marquardt`, `kendalls`, `gauss-quad` költségéért, akkor is, ha csak `Bm`‑et szimulál. |
| **Feature flag tisztulás** | A 12 feature jelentős része `dep:` proxy. Workspace‑ben minden sub‑crate maga gondoskodik a saját feature flagjeiről. |
| **API surface enforcement** | Sub‑crate boundaryk **fizikailag kényszerítik** a tisztább interfészeket. A jelenlegi crossover‑ek (`quant::pricing` használja a `stochastic::process::FBM`‑et, a `stats::heston_mle` használja a `quant::pricing::HestonParams`‑ot) **láthatóvá válnak** Cargo dependency‑ként. |
| **Verziózás** | A `quant` és `ai` sokkal gyorsabban változik mint a `core`. Sub‑crate‑ek külön semver‑t kaphatnak. |
| **Python binding mérete** | Most a `cdylib` artefakt **mindent tartalmaz**. Külön `stochastic-rs-py` crate‑ben opt‑in feature‑ekkel le lehet kapcsolni az AI / quant rétegeket az `.so`‑ból. |
| **Külső használat** | Egy felhasználó használhatja **csak** a `stochastic-rs-stochastic`-ot (pl. data simulation lib‑ben), `quant` nélkül. |

### 5.3. Költségek és kockázatok

| Kockázat | Részletek |
|---|---|
| **Re‑export tax** | Az umbrella crate `pub use stochastic_rs_X as X` minta minden szimbólumnak két útvonalat ad. A docs.rs‑en az `stochastic_rs::quant::pricing::HestonPricer` és `stochastic_rs_quant::pricing::HestonPricer` is megjelenik — érdemes `#[doc(hidden)]` sub‑crateket csinálni az alsó réteghez, vagy `#[doc(no_inline)]`. |
| **Trait koherencia** | A `FloatExt`, `ProcessExt` a `core` crate‑ben kell legyen, és **minden process‑t implementáló sub‑crate az `core`‑ra hivatkozik**. Egyetlen helyen lehet a definíció (orphan rule). Ez most működik egy crateben — workspace‑ben extra figyelmet igényel. |
| **Cyclic dependencies** | Pl. `quant::pricing` használ `distributions::SimdNormal`‑t, `quant::calibration` használhatja a `stats::heston_mle`‑t. Egy circular ágat **fel kell oldani** (pl. `stats` → `quant::HestonParams` használat csak adapterben). |
| **Macros** | A `py_process_1d!` és társai jelenleg `#[macro_use]`‑pel exportálódnak a crate‑ben. Workspace‑ben **`#[macro_export]`** + `pub use crate::macros::*` kell, vagy proc‑macro crate. |
| **Build‑rendszer komplexitás** | `Cargo.lock` egy közös, de minden sub‑crate saját `Cargo.toml`. Release koordináció: ha egy `core` token signature‑változás ér, mindegyik sub‑crate verzióját bumpolni kell. |
| **GPU feature‑ek tisztességes szétosztása** | A `cuda-native`, `gpu-cuda`, `gpu-wgpu`, `metal`, `accelerate` mind az `FGN`‑hez tartoznak — a `stochastic-rs-stochastic` sub‑crate kapja meg, a többi sub‑crate **soha** ne lássa. |
| **CI mátrix robbanás** | Minden sub‑crate × minden feature kombináció. **Megoldás:** csak az umbrella crate fut le `--all-features`‑szel CI‑ben, sub‑crate‑ek default + minimum feature‑set. |
| **Python `cdylib` egysége** | A `pyo3` jelenleg **egy `cdylib`** outputot ad. Workspace‑ben **egy** `stochastic-rs-py` cdylib crate kell, ami minden sub‑crate Rust‑oldali wrapperjét re‑exportálja. |

### 5.4. Lépésterv (ha ezt választjuk)

1. **Fázis 0 — előkészítés (most):**
   - Re‑export prelude bevezetése: `pub use` lib.rs‑ben + facade típusok modul‑rootokba (workspace nélkül is hasznos)
   - `traits.rs` szétdarabolása `traits/{float,process,distribution,copula,pricing}.rs`‑re — workspace előfeltétele
   - Halott trait‑ek (`DistributionExt`, `MalliavinExt`) eldöntése (impl vagy törlés)

2. **Fázis 1 — `core` kiemelése:**
   - `stochastic-rs-core` crate: `traits`, `simd_rng`, `macros`
   - Minden más maradjon a fő crate‑ben, de hivatkozzon a `core`‑ra

3. **Fázis 2 — `distributions` kiemelése:**
   - Egyetlen függőség: `core`
   - Independent unit testekkel zárható

4. **Fázis 3 — `stochastic` kiemelése:**
   - Függőség: `core` + `distributions`
   - GPU feature‑ek **csak ide** költöznek

5. **Fázis 4 — `stats` és `copulas` párhuzamosan:**
   - `stats` függ: `core` + `distributions` (+ opcionálisan `stochastic`)
   - `copulas` függ: `core` + `distributions`

6. **Fázis 5 — `quant` kiemelése:**
   - Függőség: `core` + `distributions` + `stochastic` (MC pricerekhez)
   - **Itt kell a circular dep‑ot feloldani** (stats → quant adapterek külön sub‑crate‑ben)

7. **Fázis 6 — perifériák:**
   - `ai`, `viz`, `py` mind opt‑in standalone

8. **Fázis 7 — umbrella crate refaktor:**
   - `stochastic-rs` csak `pub use` + `prelude` + dokumentáció
   - **API tovább működik** a meglévő path‑ekkel (`stochastic_rs::quant::…`)

### 5.5. Hibrid megoldás (kompromisszum)

Ha a teljes workspace nehéz, **első körben:**

- **Egyetlen workspace, három crate:**
  - `stochastic-rs-core` (traits + simd_rng + distributions + stochastic + copulas)
  - `stochastic-rs-quant` (quant + stats — finance‑specifikus)
  - `stochastic-rs` (umbrella + py + ai + viz)

- Ez kiváltja a 12 feature flag jelentős részét, közben 3 crate‑re csökkenti a koordinációs overhead‑et.

### 5.6. Mikor **ne** workspace‑szé

- Ha a felhasználói telepítések nagyon kevés feature‑t használnak (pl. mindenki minden flagot bekapcsol).
- Ha a fejlesztőcsapat 1 fős és a release‑koordináció overhead nem éri meg.
- Ha a mostani build idő elfogadható, és a feature‑szennyezés nem tényleges fájdalom.

A jelenlegi crate **mérete és complexitása már átlépte az egy crate‑es ergonomikus határt** (12 feature, 200+ publikus típus, GPU/Python/AI keveredés) — a workspace ROI valószínűleg pozitív.

---

## 6. Prioritizált javaslatok

A workspace‑opció **független** ezektől — mindkét döntés mellett értelmesek.

### P0 — kritikus, kis költség

1. **Prelude bevezetése** (`stochastic_rs::prelude::*`) — 1 napos munka, minden user nyer.
2. **`DistributionExt` döntés** — vagy implementálni (~19 disztribúció × 12 metódus, jelentős munka), vagy törölni a defaultokat. Most halott interfész.
3. **`ToModel` lyukak betöltése** — `SabrCapletCalibrator`, `HullWhiteSwaptionCalibrator`. Ez **lyukat tömi** a vol_surface pipeline‑on.
4. **Modul‑root facade re‑exportok** (`stochastic.rs`, `quant.rs`, `distributions.rs`, …) — 1 nap, nincs breaking change.

### P1 — fontos, közepes költség

5. **Naming konvenció dokumentálása + a kirívó eltérések rendezése** (`OU` vagy `Vasicek`? `KOU` vagy `Kou`?). Verzióváltáshoz kötve, deprecated aliasekkel.
6. **Stats input‑típus egységesítése** — válassz egyet (`ArrayView1<T>` ajánlott zero‑copy miatt) és vidd át mindenhova.
7. **Stats output struct sablon** — `XxxResult` minta minden becslőre, közös trait (`pub trait EstimatorResult { fn params(&self) -> ...; }`).
8. **Copula duplikáció megszüntetése** — `samples::*Copula2D` vagy törlendő, vagy `BivariateExt` blanket impl alapján generálni.
9. **`traits.rs` szétdarabolása** modulokra.
10. **Halott utility típusok átszervezése** `stochastic` modulban (`stochastic::numerics`).

### P2 — nice‑to‑have, nagyobb költség

11. **Builder‑pattern minden 6+ paraméteres pricer/processre** (Heston, HullWhite, Bates, Bergomi, …). Most a `.builder()` mintát csak BSM/Heston követi.
12. **Output‑típus marker traitek** (`OneDimensional`, `TwoDimensional`, `MultiPath`).
13. **Egységes `Calibrator` trait + `CalibrationResult` trait** — most minden kalibrátor egyedi.
14. **Cross‑module adapterek** (`stats::heston_mle` ↔ `quant::HestonCalibrator` mint seed forrás; `ai::*Nn::predict_surface` ↔ `ImpliedVolSurface`).
15. **Python coverage kibővítése** — quant pricerek, kalibrátorok, AI, copulas.

### P3 — stratégiai

16. **Workspace‑szé alakítás** (lásd 5. fejezet).
17. **`stochastic::sde::Sde<F, G>` generikus solver vs. konkrét processek** — döntés: vagy egységes generikus API, vagy a generikus solvert privátizálni.
18. **GPU pipeline kiterjesztése** drága modellekre (Heston, RoughBergomi).
19. **Greeks pipeline egységesítése** (Malliavin, analitikus, finite difference egy interfész alatt).

---

## Függelék

### F1 — modul‑szintű tényadatok

| Modul | Almodulok | Public root‑fájl tartalma |
|---|---|---|
| `stochastic` | 14 (autoregressive, correlation, diffusion, interest, isonormal, ito, jump, malliavin, mc, noise, process, rough, sde, sheet, volatility) | csak `pub mod` |
| `quant` | 20 + `loss.rs` + `order_book.rs` + `yahoo.rs` | `OptionType`, `OptionStyle`, `Moneyness`, `LossMetric`, `CalibrationLossScore` |
| `distributions` | 19 disztribúció | `DistributionSampler<T>` trait |
| `copulas` | bivariate, multivariate, univariate, samples, correlation, empirical | csak `pub mod` |
| `stats` | 17 | csak `pub mod` |
| `ai` | volatility, utils | `DataSet` |
| `traits` | flat | 14 trait + helpers, 654 sor |
| `visualization` | flat | `Plottable`, `GridPlotter` |
| `simd_rng` | flat | `SimdRng`, `SeedExt`, `Unseeded`, `Deterministic` |
| `macros` | flat (private) | 7 deklaratív macro |
| `python` | flat (private, `feature = "python"`) | 103 PyO3 osztály |

### F2 — feature‑flag mátrix

| Flag | Default | Mit kapcsol |
|---|---|---|
| `default` | igen | (nincs) |
| `ai` | nem | `candle-core`, `candle-datasets`, `candle-nn`, `polars` |
| `python` | nem | `pyo3`, `numpy`, macro‑driven 103 wrapper |
| `openblas` | nem | `ndarray-linalg`, `openblas-src` — kell a `stats::stationarity`, `copulas::multivariate`, és néhány `quant` becsléshez |
| `gpu` | nem | `cubecl`, `gpu-fft` |
| `gpu-cuda` | nem | `gpu` + `cubecl-cuda` |
| `gpu-wgpu` | nem | `gpu` + `cubecl-wgpu` |
| `cuda-native` | nem | `cudarc` (cufft) |
| `metal` | nem | `metal` |
| `accelerate` | nem | (csak feature gate, nincs új dep) |
| `jemalloc` | nem | `tikv-jemallocator` global allocator |
| `mimalloc` | nem | `mimalloc` global allocator |
| `yahoo` | nem | `yahoo_finance_api`, `time`, `polars`, `tokio-test` |
| `hotpath` | nem | `hotpath` profiler |
| `hotpath-alloc` | nem | `hotpath` + alloc tracking |

**Megfigyelés:** `accelerate` **nem ad új függőséget**, csak feature gate — gyanús, érdemes ellenőrizni hogy ténylegesen kapcsol‑e bármit.

### F3 — orphan modulok listája

| Fájl | Méret | Hivatkozza‑e bárki |
|---|---|---|
| `quant/order_book.rs` | ~220 sor | csak self |
| `quant/fourier_malliavin.rs` | ~240 sor | csak self |
| `quant/microstructure/*` | ~1500 sor | csak self |
| `quant/factors/*` | ~800 sor | csak self |

**Total:** ~2700 sor publikus kódot semmi nem használ a craten belül.

### F4 — halott trait‑ek

| Trait | Definíció | Implementálva |
|---|---|---|
| `DistributionExt` | `traits.rs:239` | sehol |
| `MalliavinExt<T>` | `traits.rs:583` | sehol az 1D processekben |
| `Malliavin2DExt<T>` | `traits.rs:616` | sehol |
| `NCopula2DExt` | `traits.rs:477` | csak a 2D helperekben (samples.rs) |

### F5 — release blocker check

Az audit alapján a `2.0.0` stabil release **előtt** rendezendő:

- [ ] P0/2: `DistributionExt` döntés (csak akkor stabilizálható az API ha él vagy kihal)
- [ ] P0/3: `ToModel` lyukak — két dokumentált pipeline‑pont megszakad
- [ ] P1/8: copula duplikáció (két trait ugyanarra a copulára nem mehet stable‑ként)
- [ ] Naming: `OU` vs `Vasicek` döntés
- [ ] Orphan modulok: vagy integrálni vagy `#[doc(hidden)]` jelölni vagy törölni

---

*Audit kelt: 2026-04-26 — `git rev-parse HEAD`: `83d9351` ("chore: update readme")*
