fuggers-py 0.2.0

Fixed-income analytics, market-data traits, and research-oriented engine workflows.

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 including fixed, floating, callable, sinking-fund, and TIPS cashflow models, plus conventions, schedules, real-yield pricing helpers, and options
• fuggers_py.rates: tradable IRS/OIS/FRA/same-currency-basis/cross-currency-basis/asset-swap/zero-coupon-inflation-swap/standard-coupon-inflation-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.inflation: shared inflation conventions, daily reference-index helpers, projected inflation-index curves, deterministic inflation-swap bootstrap helpers, normalized monthly CPI adapters, Treasury auctioned-TIPS metadata adapters, and small linker breakeven/parity analytics
• 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.
• TIPS real yields are also represented as raw decimals, for example 0.0125 for 1.25%. The library now also includes a first inflation-curve abstraction bootstrapped from zero-coupon inflation swaps.
• 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

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

Quickstart

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

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

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/INFLATION_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