# Source Structure

`src/fuggers_py/` is the canonical implementation root for the library.

For the complete file-by-file module inventory, see [MODULE_REFERENCE.md](MODULE_REFERENCE.md).

```python
from fuggers_py import (
    adapters,
    calc,
    core,
    market,
    math,
    measures,
    portfolio,
    pricers,
    products,
    reference,
)
from fuggers_py.market.curves import DiscountCurveBuilder
from fuggers_py.products.bonds import FixedBondBuilder
```

## Root package files

- `__init__.py`: top-level package exports and runtime version import.
- `_version.py`: generated version metadata for builds; not handwritten library code.
- `py.typed`: typing marker for downstream users.

## Directory map

### `adapters/`

- External boundaries and persistence layers.
- File-backed loaders, JSON codecs, storage protocols, SQLite storage, portfolio storage, transport interfaces, and adapter-specific errors.

### `calc/`

- Orchestration and runtime wiring.
- Pricing specs, output records, pricing routers, curve-building coordination, calc graph execution, reactive listeners, scheduler, and runtime config/coordination helpers.

### `core/`

- Shared primitives used everywhere else.
- Calendars, day counts, ids, low-level traits, common value types, and core errors.

### `market/`

- Dynamic market-layer objects.
- Market data containers, market state records, index/fixing infrastructure, and the canonical curve namespace under `market.curves`.

### `math/`

- Numerical infrastructure.
- Shared numerical helpers plus dedicated interpolation, extrapolation, linear-algebra, optimization, and solver subpackages.

### `measures/`

- User-facing analytics and report-style calculations.
- Yield, YAS, spread, RV, cashflow, risk, option, credit, funding, and inflation measure families.

### `portfolio/`

- Portfolio-level aggregation and workflow code.
- Portfolio types, summary analytics, benchmark comparison, bucketing, contribution/attribution, ETF helpers, liquidity, stress, and result records.

### `pricers/`

- Low-level valuation and risk engines.
- Bond, credit, and rates pricers, including pricing helpers that resolve market inputs into model-level calculations.

### `products/`

- Contract definitions and product-level structures only.
- Bond, credit, funding, and rates product families, including rates futures/options and inflation-linked rate contracts where applicable.

### `reference/`

- Reference and convention data.
- Shared reference-data records plus bond and inflation-specific conventions, metadata, and related reference helpers.

## Notable subdirectories

### `market/curves/`

- Single home for generic and specialized curve logic.
- Base term-structure types, conversion/value semantics, discrete/derived/forward/delegated/segmented curves, calibration helpers, builders, and specialized curve families.

### `market/indices/`

- Bond-index and fixing-store infrastructure plus overnight index conventions.

### `products/rates/`

- Rates contracts, including swaps, FRAs, basis structures, and inflation-swap products.

### `portfolio/types/`

- Portfolio value objects such as holdings, classifications, maturity buckets, and weighting/config helpers.

## Reading order

1. Start with `core/` for shared types and conventions.
2. Read `reference/` and `market/` for static versus dynamic market inputs.
3. Read `products/` for contracts.
4. Read `pricers/` and `measures/` for calculations.
5. Read `portfolio/` and `calc/` for aggregate workflows and orchestration.
6. Read `adapters/` for file/storage/transport boundaries.
