# Rates Docs

`fuggers_py.rates` now contains lightweight tradable rates products, narrow pricers,
government bond futures tooling, and finite-difference risk helpers, while keeping the bootstrap helpers in
`fuggers_py.curves.calibration.instruments` unchanged.

## Instruments

- `FixedFloatSwap` / `InterestRateSwap`
- `Ois` / `OvernightIndexedSwap`
- `Fra` / `ForwardRateAgreement`
- `BasisSwap` / `SameCurrencyBasisSwap`
- `CrossCurrencyBasisSwap`
- `AssetSwap`
- `FixedLegSpec`, `FloatingLegSpec`, `ScheduleDefinition`, and `PayReceive`
- `GovernmentBondFuture`, `DeliverableBond`, and `DeliverableBasket`
- `Swaption`, `CapFloor`, `FuturesOption`, and `OptionType`

All product classes are immutable dataclasses and reuse the existing schedule,
calendar, and day-count infrastructure from the bond and core layers.

## Government Bond Futures

- `GovernmentBondFuture`
  - delivery-date resolution from an explicit date or delivery window
  - contract size, tick size, standard coupon, and coupon frequency
- `DeliverableBond` / `DeliverableBasket`
  - fixed-coupon deliverables with current clean prices and optional published CFs
- `conversion_factor`
  - theoretical CFs using the bond pricer
  - published-CF override support
- `invoice_clean_price`, `invoice_price`, `invoice_amount`
- `cheapest_to_deliver`
  - explicit short-side sign convention via `delivery_payoff = F * CF - P`
- `gross_basis`, `net_basis`, `basis_metrics`
- `YieldGridCTDSwitchModel`
  - deterministic delivery-option adjustment from CTD switching over a yield grid
- `OneFactorDeliveryOptionModel`
  - stochastic parallel-yield delivery-option adjustment from externally supplied delivery-horizon volatility inputs
- `MultiFactorDeliveryOptionModel`
  - stochastic CTD-switch adjustment from externally supplied factor volatilities, scenario weights, and deliverable-specific factor loadings
- `fair_futures_price`, `oabpv`
  - option-adjusted fair futures price and finite-difference OABPV

The stochastic delivery-option models intentionally sit behind the same
`DeliveryOptionModel` protocol as the deterministic grid model, so the
Sprint 3 futures stack remains usable unchanged while allowing richer
externally parameterized CTD-switch scenarios.

## Rates Options

- `Black76Pricer`
  - transparent Black-76 pricing and Greeks
  - swaption, cap/floor, and futures-option wrappers
- `BachelierPricer`
  - transparent normal-model pricing and Greeks
  - supports negative forward rates cleanly
- `HullWhiteRateOptionModel` / `HullWhiteOptionPricer`
  - lightweight normal-vol approximation from externally supplied
    mean-reversion and volatility inputs
- `OptionGreeks`
  - reusable delta / gamma / vega / theta / rho container

Swaptions use the existing `FixedFloatSwap` products and swap pricer to obtain
forward swap rates and annuities. Caps/floors reuse the floating-leg schedule
and day-count infrastructure to price optionlets. Futures options can be priced
either from an explicit futures price or from the government-bond-futures fair
price stack, including delivery-option adjustments.

## Pricing

- `SwapPricer`
  - `par_rate`
  - `annuity`
  - `pv`
- `FraPricer`
  - `forward_rate`
  - `pv`
- `BasisSwapPricer`
  - `par_spread`
  - `pv`
- `CrossCurrencyBasisSwapPricer`
  - `par_spread`
  - `pv`
  - explicit valuation-currency output plus FX-forward-aware leg and principal PVs
- `AssetSwapPricer`
  - `par_spread`
  - `pv`
  - `funding_component`
  - `credit_component`
  - structured breakdown with funding-ladder detail

Pricing resolves curves from `AnalyticsCurves.multicurve_environment` when
available. If a multi-curve bundle is not present, the pricers fall back to the
existing `discount_curve` plus `forward_curve` path. The cross-currency basis
pricer also accepts an explicit `fx_forward_curve`; otherwise it falls back to
spot-plus-discount-factor parity.

The full asset-swap pricer stays in `fuggers_py.rates` and reuses the low-level
`ParParAssetSwap` and `ProceedsAssetSwap` kernels from `fuggers_py.analytics.spreads.asw`.

Rates-option pricers reuse `AnalyticsCurves.vol_surface` when present. The
surface lookup is explicit on expiry, tenor, strike, and quote type:
lognormal points feed Black-76 and normal points feed Bachelier.
The structured examples focus on Black-76, Bachelier, and the common
government-bond-futures workflow; `HullWhiteOptionPricer`,
`HullWhiteRateOptionModel`, and `MultiFactorDeliveryOptionModel` remain public
and are covered directly by unit tests even though they are not expanded into a
larger notebook section.

## Risk

- `pv01` / `bpv`
- `key_rate_risk`
- instrument-specific wrappers for swaps, FRAs, and basis swaps

The risk helpers are finite-difference wrappers over the pricers and reuse the
curve bumping utilities already present in `fuggers_py.curves`.

Unless a helper documents otherwise, rates, spreads, and volatilities are raw
decimals, while government-bond-futures prices and invoice-style bond inputs
remain quoted in percent-of-par and PV outputs stay in currency units.

## Shared records

The rates root re-exports the shared data records needed by the futures layer as
well as the tradable rates records:

- `SwapQuote`, `BasisSwapQuote`, `BondFutureQuote`
- `SwapQuoteOutput`, `BasisSwapQuoteOutput`, `FutureQuoteOutput`
- `SwapReferenceData`, `BondFutureReferenceData`, `BondFutureContractReference`
- `DeliverableBondReference`

The rates layer is also the deterministic pricing backbone for global RV
workflows in `fuggers_py.analytics.rv`: asset swaps, same-currency basis swaps,
and cross-currency basis swaps can be chained to express a bond on a common
floating or fixed cashflow basis without moving bond analytics into the
analytics root.
