Metadata-Version: 2.4
Name: fuggers-py
Version: 0.1.0b1
Summary: Fixed-income analytics, market-data traits, and research-oriented engine workflows.
Author-email: Stanislaw Kubik <skubik234@icloud.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/stanislawkubik/fuggers-py
Project-URL: Repository, https://github.com/stanislawkubik/fuggers-py
Project-URL: Documentation, https://github.com/stanislawkubik/fuggers-py/tree/main/docs
Project-URL: Issues, https://github.com/stanislawkubik/fuggers-py/issues
Project-URL: Changelog, https://github.com/stanislawkubik/fuggers-py/blob/main/CHANGELOG.md
Keywords: fixed-income,bonds,yield-curves,quant-finance,credit,analytics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: coverage[toml]>=7; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: jupytext>=1.16; extra == "dev"
Requires-Dist: mypy>=1.14; extra == "dev"
Requires-Dist: nbformat>=5.10; extra == "dev"
Requires-Dist: pre-commit>=4; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15.6; extra == "dev"
Provides-Extra: engine
Requires-Dist: croniter>=2; extra == "engine"
Dynamic: license-file

# 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
- `fuggers_py.bonds`: bond instruments, conventions, schedules, pricing helpers, options
- `fuggers_py.analytics`: yield, spread, risk, pricing, and YAS-style calculations
- `fuggers_py.portfolio`: aggregate analytics, benchmarking, contribution, liquidity, stress, ETF workflows
- `fuggers_py.data`: identifiers, market data, reference data, pricing specs, output records
- `fuggers_py.io`: file adapters, JSON codecs, SQLite-backed storage, storage and transport interfaces
- `fuggers_py.engine`: pricing router, reactive engine, schedulers, 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.

## Installation

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

## 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`.

## Community

- Contributor guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- Security reporting: [SECURITY.md](SECURITY.md)

## Examples

Examples live under `examples/` as paired `.py` and `.ipynb` files. A good starting set is:

- `examples/public_api_surface_examples.ipynb`
- `examples/data_provider_surface_examples.ipynb`
- `examples/io_file_and_storage_examples.ipynb`
- `examples/engine_reactive_examples.ipynb`
- `examples/portfolio_etf_surface_examples.ipynb`

## Docs

- `docs/CORE_DOCS.md`
- `docs/MATH_DOCS.md`
- `docs/CURVES_DOCS.md`
- `docs/BONDS_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`
