API stability

merton adheres to Semantic Versioning from v1.0 onwards. This page is the canonical reference for what counts as the public API and how we evolve it across releases.

What’s public

A name is part of the public API if and only if all of the following hold:

  1. It appears in the __all__ list of some module that is part of import merton.*.

  2. It is documented under docs/api/ (auto-generated by sphinx-autoapi).

  3. Its module is not prefixed with _ (merton._backend, merton._deprecation, etc. are explicitly internal).

merton.__all__ enumerates the top-level public surface. As of v1.0 it includes:

  • Containers / results: Firm, FirmPanel, MertonResult, DefaultPoint.

  • Orchestrator: MertonModel.

  • Functional entry points: fit, batch_fit, distance_to_default, prob_of_default, equity_value, implied_credit_spread, physical_pd, term_structure_pd, warm_cache.

  • Namespaces: calibration, backtest, extensions, greeks, portfolio, reports, scenarios, excel, obs, cli, config, exceptions.

The previously-planned io, diagnostics, and viz namespaces are not part of the v1.0 surface. Their helpers currently live on

class:

~merton.core.panel.FirmPanel (CSV/Parquet round-trip),

meth:

~merton.core.result.MertonResult.summary, and

mod:

merton.reports; standalone namespaces for them are roadmapped for 1.x.

Stability contract from v1.0

  • Major version (X.0): removals, renames, behaviour changes that break documented invariants.

  • Minor version (1.X): additive only. New functions, new optional kwargs (with defaults that preserve old behaviour), new submodules.

  • Patch version (1.X.Y): bug fixes, performance improvements, documentation; no API changes.

Numerical stability: closed-form math (Greeks, BSM, distance-to-default) will not change in a minor release. Calibration algorithms that converge iteratively may produce values that differ by less than the documented tolerance (e.g., rtol=1e-6) — that’s by design.

Deprecation policy

Soft-deprecations route old names through

mod:

merton._deprecation. The decorator stamps the removal target into the warning text so users can plan migrations.

from merton._deprecation import deprecated

@deprecated("Use merton.fit(firm, method='vassalou_xing')", since="0.9", removed_in="2.0")
def calibrate(firm):
    ...

Rules:

  • Every deprecated public name remains callable for at least one full minor release before removal.

  • The warning text cites the replacement (function, kwarg, env var) so the migration path is unambiguous.

  • Removals land in major releases only and are listed in CHANGELOG.md under the appropriate version heading.

Pre-v1 caveat

Before v1.0, merton is 0.x. The same contract applies in spirit, but because we explicitly mark the project Alpha until v1.0, minor releases can introduce breaking changes if a design flaw is found. The 0.9 release candidate freezes the API surface in preparation for v1.0.