API stability policy

This page records the frozen public API for the 4.1.x / 4.2.x compatibility series and the versioning rules that govern change. It summarizes design docs/design/DESIGN.md §8.1 and §8.4. Characterization tests under tests/ are the executable contract.

Frozen public surface

Downstream code may rely on the following import paths and names remaining available with compatible signatures and defaults:

Module

Public names

ecnet

ECNet, __version__

ecnet.model

load_model

ecnet.datasets

load_bp, load_cn, load_cp, load_kv, load_lhv, load_mon, load_mp, load_pp, load_ron, load_ysi, QSPRDataset, QSPRDatasetFromFile, QSPRDatasetFromValues

ecnet.tasks

select_rfr, tune_batch_size, tune_model_architecture, tune_training_parameters

ecnet.blends

cetane_number, yield_sooting_index, kinematic_viscosity, cloud_point, lower_heating_value, linear_blend_err, exponential_blend_err, kv_error

ecnet.callbacks

LRDecayLinear, Validator, Callback, CallbackOperator

Advanced import: PCADataset

PCADataset lives in ecnet.datasets.structs and is not part of the ecnet.datasets public export surface for this compatibility series. Use:

from ecnet.datasets.structs import PCADataset

Additive optional keyword arguments on frozen callables are allowed when defaults preserve current behavior.

Versioning policy

Release class

Examples

Contract

Patch (4.1.x)

Bugfixes, packaging, tests, documentation corrections

Signature and numeric oracles must continue to match

Minor (4.2.0)

Internal hardening, Sphinx/governance completion, dependency range expansions proven on CI

Still API-compatible with the frozen surface

Major (5.0.0)

Intentional breaks only with explicit approval

Examples: removing pickle-based full-module torch.load, changing default descriptor backends, altering bundled dataset schemas

Executable contract

CI and local verification should keep these green:

  • Signature locks — tests/test_api_signatures.py

  • Blend oracles — tests/blends/, tests/fixtures/

  • Dataset / model / tasks / callbacks characterization suites

Coverage floors: ecnet.blends ≥95% line coverage; overall package ≥90%, enforced in CI with --cov-fail-under=90.