# API stability

`sparho` is pre-alpha; the public API may change between minor versions
until v1.0. This page declares which surfaces are committed to in the
current release line and which are not, so downstream packages know what
they can lean on.

## Stable

These names and signatures are committed to within a given minor version.
Breaking changes require a deprecation cycle: a new release introduces
the replacement and emits `DeprecationWarning` on the old surface; the
old surface is removed in the next minor (not patch) bump.

- `sparho.Problem`, `sparho.SquaredLoss`, `sparho.LogisticLoss`.
- The `sparho.Penalty` union and its variants `L1`, `ElasticNet`,
  `WeightedL1`, `GroupL1` (including the `from_labels` factory).
- The `sparho.Solver` protocol — `(problem, hyperparam) -> SolverResult`,
  with optional keyword-only `x0` and `tol`.
- `sparho.SolverResult`, `sparho.SearchResult`, `sparho.SearchState`,
  `sparho.IterationRecord` *as dataclasses* — field names, types, and
  default values. See the experimental section below for
  `IterationRecord.extras`.
- `sparho.grad_search`, `sparho.hoag_search` — positional / keyword
  arguments, including the v0.4 `callback` kwarg.
- `sparho.implicit_forward`.
- The three sklearn-compatible wrapper estimators
  (`sparho.LassoHO`, `sparho.ElasticNetHO`, `sparho.LogisticRegressionHO`)
  and their fitted attributes (`coef_`, `intercept_`, `alpha_`,
  `n_iter_`, `feature_names_in_`, `n_features_in_`,
  `search_result_`, `classes_` for the classifier).

## Experimental

Subject to change in any release, including patch. Pin your version if
you depend on these.

### `IterationRecord.extras` schema

`IterationRecord.extras` is a `Mapping[str, object]` populated by the
search loops. Keys and value types may be added, removed, or renamed
between releases. As of v0.4 the following keys are populated when
available:

| key | type | populated by | meaning |
|---|---|---|---|
| `cg_status` | `Literal["ok", "nonconvergence", "nonfinite"]` | always | summary of the inner CG solve inside `implicit_forward`. `"nonfinite"` means CG returned NaN/Inf (the search treats this as a zero hypergradient and stalls one iter); `"nonconvergence"` means CG returned a finite but unconverged result. |
| `inner_dual_gap` | `float` | when the criterion surfaces it (`HeldOutMSE` / `HeldOutLogistic` directly; `CrossVal` takes max across folds; `Sure` takes max across its two solves) | inner-solver convergence proxy. Compare against the configured `inner_tol`. |
| `step_size` | `float` | `hoag_search` only | `1 / L_estimate` — the θ-space step magnitude that drove this iter's update. |
| `L_estimate` | `float` | `hoag_search` only | Lipschitz proxy used by HOAG's acceptance test. Doubles on rejected steps, multiplied by 0.95 on accepted steps. |

Future keys under consideration but not committed: `n_inner_iter` per
solve, `active_set_size`, `objective` (current outer-loop criterion
value). Treat anything not listed above as private.

### Adapter internals

`sparho.adapters` re-exports `SklearnLasso`, `CelerLasso`, etc. as a
convenience. The internal layout (`adapters._common`, the per-adapter
modules) is not stable.

### Hypergradient ridge default

`implicit_forward(..., ridge=None)` resolves to
`1e-10 · trace(M_AA) / |A|`. The coefficient and the auto-scale formula
may change as we accumulate more empirical evidence on near-singular
designs.

## Private

Anything under a leading underscore (`_VerbosePrinter`,
`_extras_from_warnings`, etc.) and the entire `sparho._core` extension
module. Calling these from outside the package is unsupported.

## Optional dependencies

The `[celer]` extra is tracked by a dedicated CI job (`ci-celer`). The
floor-version pins are tracked by `ci-min-deps`. Bumps to either are
documented in `CHANGELOG.md`.