# fuggers-py

`fuggers-py` is a Python library for fixed-income analytics. It is organized as a native Python package with explicit submodules for domain models, analytics, data, I/O, and engine workflows.

## Package layout

- `fuggers_py.core`: dates, prices, yields, spreads, calendars, day counts, base errors, interfaces
- `fuggers_py.math`: root finding, interpolation, extrapolation, optimization, linear algebra
- `fuggers_py.curves`: discount and credit curves, builders, calibration, bumping, multicurve tools, fitted bond-curve research, and optional advanced shadow-rate / jump-diffusion overlays
- `fuggers_py.bonds`: bond instruments, conventions, schedules, pricing helpers, options
- `fuggers_py.rates`: tradable IRS/OIS/FRA/same-currency-basis/cross-currency-basis/asset-swap products, rates options, government bond futures analytics including stochastic delivery-option models, pricers, risk helpers, and shared rates/futures records
- `fuggers_py.funding`: repo instruments, repo curves, funding analytics, and repo-specific routing helpers
- `fuggers_py.credit`: CDS instruments, pricers, bootstrap helpers, bond/CDS basis analytics, proxy risk-free helpers, and shared credit records
- `fuggers_py.analytics`: yield, spread, risk, pricing, YAS-style calculations, option Greek and RV helpers, reference-rate decomposition and balance-sheet overlay helpers, deterministic local/global RV analytics, and signal-to-trade workflow hooks for fitted-bond RV
- `fuggers_py.portfolio`: aggregate analytics, benchmarking, contribution, liquidity, stress, ETF workflows
- `fuggers_py.data`: identifiers, market data, reference data, pricing specs, output records, cross-domain shared records, and optional local-RV bond metadata
- `fuggers_py.io`: file adapters, JSON codecs, SQLite-backed storage, storage and transport interfaces
- `fuggers_py.engine`: bond, funding, and rates pricing routers, reactive engine, schedulers, and engine configuration

Canonical usage is explicit submodule imports. The package no longer exposes `prelude`, `traits`, or `ext` namespaces.

## Public API policy

- Use package roots such as `fuggers_py.analytics`, `fuggers_py.bonds`, and `fuggers_py.io` for common entry points.
- Import specialized exception subclasses from plural `errors` modules such as `fuggers_py.analytics.errors` and `fuggers_py.data.errors`.
- Deprecated compatibility aliases may remain temporarily, but they are not part of the stable long-term surface.

## Quoting conventions

- Unless a type or docstring says otherwise, rates and spreads are represented as raw decimals, for example `0.045` for 4.5%.
- Bond clean and dirty prices are generally quoted in percent-of-par, for example `101.25`.
- Accrued interest, coupon cashflows, repo cash amounts, and CDS premium/upfront amounts are returned in currency units.
- Settlement-date arguments refer to the economic settlement date used for accrual, pricing, and discounting.

## Installation

```bash
pip install fuggers-py
pip install "fuggers-py[dev]"
pip install "fuggers-py[engine]"
pip install "fuggers-py[examples]"
```

## Quickstart

```python
from decimal import Decimal

from fuggers_py.analytics import yield_to_maturity
from fuggers_py.bonds import FixedBondBuilder
from fuggers_py.core import Currency, Date, Frequency, Price

settlement = Date.from_ymd(2026, 1, 15)
bond = (
    FixedBondBuilder.new()
    .with_issue_date(Date.from_ymd(2024, 1, 15))
    .with_maturity_date(Date.from_ymd(2031, 1, 15))
    .with_coupon_rate(Decimal("0.0450"))
    .with_frequency(Frequency.SEMI_ANNUAL)
    .with_currency(Currency.USD)
    .build()
)

clean_price = Price.new(Decimal("101.25"), Currency.USD)
ytm = yield_to_maturity(bond, clean_price, settlement)
print(ytm.as_percentage())
```

## Engine and data workflows

```python
from fuggers_py.core import Date
from fuggers_py.data import MarketDataProvider, ReferenceDataProvider
from fuggers_py.engine import PricingEngineBuilder

engine = (
    PricingEngineBuilder.new()
    .with_market_data_provider(MarketDataProvider())
    .with_reference_data_provider(ReferenceDataProvider())
    .with_settlement_date(Date.from_ymd(2026, 3, 13))
    .build()
)

assert engine.reactive_engine is not None
```

## Testing

```bash
python -m pip install -e ".[dev,engine]"
pytest -q
```

The test suite includes deterministic validation fixtures under `tests/validation/` and a pinned external-reference corpus under `tests/fixtures/golden/validation_corpus.json`.

## Examples

Examples live in a workflow-based catalog under `examples/` and are authored as paired Jupytext `py:percent` sources plus synced `.ipynb` notebooks.

- Index: `examples/README.md`
- Notebook sources: `examples/NN_topic/*.py`
- Synced notebooks: `examples/NN_topic/*.ipynb`
- Shared helpers and fixtures: `examples/_shared/`, `examples/_fixtures/`

## Docs

- `docs/CORE_DOCS.md`
- `docs/MATH_DOCS.md`
- `docs/CURVES_DOCS.md`
- `docs/BONDS_DOCS.md`
- `docs/RATES_DOCS.md`
- `docs/FUNDING_DOCS.md`
- `docs/CREDIT_DOCS.md`
- `docs/ANALYTICS_DOCS.md`
- `docs/PORTFOLIO_DOCS.md`
- `docs/DATA_DOCS.md`
- `docs/IO_DOCS.md`
- `docs/ENGINE_DOCS.md`
- `docs/ARCHITECTURE.md`
- `docs/validation_strategy.md`
