Envelope¶
The metric envelope packages a value with the parameter set, observed depth, and op counts so a regulator can verify the encrypted execution against the declared spec.
fairlearn_fhe.envelope.ENVELOPE_SCHEMA = 'fairlearn-fhe.metric-envelope.v1'
module-attribute
¶
fairlearn_fhe.envelope.MetricEnvelope
dataclass
¶
fairlearn_fhe.envelope.ParameterSet
dataclass
¶
fairlearn_fhe.envelope.canonical_envelope_payload(payload)
¶
Return canonical JSON bytes for hashing or signing an envelope.
The embedded signature field is excluded, so the same function can
produce the payload before signing and during verification.
fairlearn_fhe.envelope.validate_envelope(payload, *, allowed_metrics=None, max_observed_depth=None, max_age_seconds=None, now=None, min_security_bits=_DEFAULT_MIN_SECURITY_BITS)
¶
Return validation errors for an audit-envelope payload.
An empty list means the envelope is structurally valid, the
parameter_set_hash matches the embedded parameter set, and the
observed depth is within the declared multiplicative-depth budget.
This is intentionally dependency-free so it can run in lightweight
verifier tooling.
Optional verifier-side checks:
max_age_secondsrejects envelopes older than the given window (anti-replay).nowdefaults totime.time().min_security_bitsrejects parameter sets whose recorded security level is below the verifier's minimum. Defaults to 128; passmin_security_bits=0to opt out (e.g. for testing benchmark contexts that intentionally use sub-128-bit parameters).
fairlearn_fhe.envelope.sign_envelope(payload, private_key_pem)
¶
Return a signed envelope payload using an Ed25519 PEM private key.
cryptography is imported lazily so unsigned envelope validation does
not require the optional signing dependency.
fairlearn_fhe.envelope.verify_envelope_signature(payload, public_key_pem)
¶
Return signature-verification errors for a signed envelope payload.
fairlearn_fhe.envelope.parameter_set_from_context(ctx, *, depth=None)
¶
Build a :class:ParameterSet from an active CKKS context.
depth is the declared multiplicative-depth budget. When omitted
we infer it from the context (len(coeff_mod_bit_sizes) - 2 for
TenSEAL; defaults to 6 for OpenFHE which sets the depth at build time).
fairlearn_fhe.audit.audit_metric(metric_name, y_true, y_pred, *, sensitive_features=None, ctx=None, min_group_size=DEFAULT_MIN_GROUP_SIZE, **kwargs)
¶
Run metric_name under encryption and return an audit envelope.
y_pred may be plaintext (encrypted internally) or an
:class:EncryptedVector (used as-is).
A :class:SmallGroupWarning is emitted when any audited group has
fewer than min_group_size samples (default 10) — set to 0
to disable. The warning is informational; the envelope is still
produced.