# Curves Docs

`fuggers_py.curves` contains term-structure models and calibration helpers.

## Main areas

- discount and credit curves
- curve builders and interpolation choices
- bumping and scenario utilities
- multicurve environments and rate indexes
- global fitting and parametric calibration
- cross-sectional fitted bond curves, fair values, and benchmark construction
- optional advanced overlays such as shadow-rate floors and deterministic jump-diffusion adjustments layered on top of an existing curve interface

## Example

```python
from decimal import Decimal

from fuggers_py.core import Date
from fuggers_py.curves import DiscountCurveBuilder

curve = (
    DiscountCurveBuilder(reference_date=Date.from_ymd(2026, 1, 15))
    .add_zero_rate(1.0, Decimal("0.0350"))
    .add_zero_rate(5.0, Decimal("0.0385"))
    .build()
)
```

## Guidance

- Keep explicit curve construction in `fuggers_py.curves`.
- Treat conversion, calibration, and bumping as curve-layer concerns rather than generic helpers.
- Use `fuggers_py.curves.fitted_bonds` when the research object is a bond cross section rather than a strip of bootstrap instruments.
- Fitted bond curves support exponential splines and cubic-spline discount-factor shapes, L1/L2 objectives, optional weights, regression adjustments, and fair-value residual outputs.
- The fitted-bond surface also exposes lower-level helper APIs for research workflows: `build_design_matrix`, `merge_regression_exposures`, `metadata_regression_exposures`, `clean_price_from_curve`, `fair_value_from_curve`, and `fair_value_from_fit`.
- `fuggers_py.curves.models` is intentionally separate from the default production path: `ShadowRateCurve` and `JumpDiffusionCurve` wrap an existing `YieldCurve`, preserve the standard curve interface, and expose research overlays without widening the bootstrap layer.
- `ValueType` is the contract for units and interpretation: discount factors and survival probabilities are unitless, zero/forward/hazard/par-swap values are raw decimal rates, and credit spreads keep their explicit spread-type metadata.
