Skip to content

v0.2.0 - extended metric coverage + CLI + JSON Schema + threat model

Choose a tag to compare

View all tags
@BAder82t BAder82t released this 27 Apr 16:27
· 7 commits to main since this release
v0.2.0
1206d86

Feature release on top of 0.1.0.

Highlights

Metric coverage

The encrypted metric catalog grows from 12 to 35 functions, closing
most of the gap with upstream Fairlearn:

  • Per-rate _difference / _ratio family (10 new) —
    selection_rate_difference / _ratio,
    true_positive_rate_difference / _ratio,
    true_negative_rate_difference / _ratio,
    false_positive_rate_difference / _ratio,
    false_negative_rate_difference / _ratio.
  • Scoring disaggregations (9 new) — accuracy_score_difference,
    accuracy_score_group_min, balanced_accuracy_score_group_min,
    precision_score_group_min, recall_score_group_min,
    f1_score_group_min, zero_one_loss_difference,
    zero_one_loss_group_max, zero_one_loss_ratio.
  • Regression disaggregations (3 new) —
    mean_squared_error_group_max, mean_absolute_error_group_max,
    r2_score_group_min. MSE is exact (one ct×ct multiply for ŷ²);
    MAE is approximated as sqrt(MSE) (exact for constant residuals,
    upper bound otherwise — documented).
  • selection_rate(pos_label=0) now works under encryption (computed
    as 1 - selection_rate(pos_label=1)). Other pos_label values still
    raise NotImplementedError with a clear message.

Backend / context

  • OpenFHE noise_flooding is now wired through build_context.
    Pass noise_flooding="openfhe-NOISE_FLOODING_DECRYPT" (or
    "noise-flooding", True) to enable OpenFHE's EXEC_NOISE_FLOODING
    execution mode where the linked openfhe-python build supports it.
    Underscore / hyphen / case variants are normalised. TenSEAL ignores
    the flag (no NOISE_FLOODING_DECRYPT mode in SEAL).

CLI

  • New fairlearn-fhe entry point with subcommands:
    • verify — validate an envelope (the original behaviour);
    • inspect — pretty-print or JSON-dump an envelope summary
      (--json);
    • schema — emit the envelope JSON Schema (--pretty to indent);
    • doctor — show backend availability.
  • The legacy fairlearn-fhe-verify entry point is preserved and
    maps directly to fairlearn-fhe verify. Existing CI scripts keep
    working.

Envelope schema

  • ENVELOPE_JSON_SCHEMA (draft 2020-12) and
    envelope_json_schema() factory are now exported at the package
    level. Validators can check envelopes against a formal schema rather
    than the bare version-tag string.

Documentation

  • New Threat model
    page formalising Mode A vs Mode B trust boundaries, what the auditor
    learns vs does not learn, recommended deployments, and CKKS-specific
    caveats. Linked from mkdocs.yml nav.

Backward compatibility

No breaking changes vs 0.1.0. Every public import from 0.1.0 continues
to work; the new helpers are purely additive.

Quality

  • 154 tests pass, ruff clean.
  • Coverage 86%. Plaintext-fallthrough and Mode A paths of the new
    metrics are covered; encrypted-mask Mode B paths for the new
    regression / scoring helpers are wired but pinned to follow-up
    fixtures.

Install

pip install --upgrade fairlearn-fhe
- uses: BAder82t/fairlearn-fhe@v0.2.0

Full changelog: see docs/changelog.md.

Assets 4
Loading