Governance diagnostics

This section documents governance-related diagnostics provided by eb-evaluation.

Governance diagnostics surface signals related to policy compliance, readiness thresholds, and decision accountability.

eb_evaluation.diagnostics.governance

Forecast governance entrypoints for Electric Barometer diagnostics.

This module unifies governance-oriented diagnostics into a single, stable decision surface:

• Demand Quantization Compatibility (DQC) diagnoses whether realized demand is continuous-like or strongly quantized/packed (piecewise items, pack sizes).
• Forecast Primitive Compatibility (FPC) diagnoses whether a scale-based readiness adjustment (e.g., RAL) is a structurally valid control lever for the demand process at the evaluation resolution.

The resulting GovernanceDecision is an auditable, deterministic artifact used to drive: - snapping requirements (raw units vs grid units), - tolerance policy interpretation (τ in raw units vs τ in grid units), - readiness adjustment policy (allow / caution / disallow), - reporting and downstream policy gating.

Decision contract (authoritative)

Inputs: - y (realized demand series) is used ONLY for DQC. - fpc_signals_raw is REQUIRED and represents FPC signals computed on raw units. - fpc_signals_snapped is OPTIONAL and represents FPC signals computed after snapping forecasts to the demand grid. If omitted, snapped == raw.

Outputs: - snap_required: True iff DQC class ∈ {quantized, piecewise_packed}. - snap_unit: DQC granularity when snap_required else None. - tau_policy: grid_units when snap_required else raw_units. - ral_policy & status: Determined from FPC on: * snapped FPC when snap_required * raw FPC when continuous-like

Policy presets: - conservative / balanced / aggressive provide small, stable presets for governance thresholds. Explicit threshold overrides always win.

Notes

This module is a governance layer. It is not a performance metric and is not an optimization objective.

GovernancePreset

Bases: str, Enum

Small, stable governance presets.

These presets tune only thresholds (not algorithms). They are intended as governance defaults that are easy to communicate and keep stable over time.

• conservative: harder to declare "compatible"
• balanced: current default behavior (close to upstream defaults)
• aggressive: easier to declare "compatible" (still deterministic/auditable)

GovernanceStatus

Bases: str, Enum

Traffic-light status for downstream gating.

TauPolicy

Bases: str, Enum

How to interpret tolerance τ downstream.

RALPolicy

Bases: str, Enum

Whether readiness adjustment is allowed downstream.

GovernanceDecision dataclass

Authoritative governance decision.

Fields are designed to be stable and auditable. Downstream systems should use these values directly rather than re-implementing policy logic.

snap_to_grid(values, unit, *, mode='ceil')

Snap values to the detected demand grid.

We default to ceil snapping because readiness is a "build to cover" control in most operational settings (i.e., avoid underbuild). Downstream systems may choose alternate snapping (round/floor) but governance should be conservative.

Parameters:

Name	Type	Description	Default
values	Sequence[float]	Forecast values to snap.	required
unit	float	Grid unit (granularity) to snap to. Must be > 0.	required
mode	str	One of {"ceil", "round", "floor"}.	'ceil'

Returns:

Type	Description
list[float]	Snapped values.

build_fpc_signals(*, nsl_base, nsl_ral, hr_base_tau, hr_ral_tau, ud, cwsl_base=None, cwsl_ral=None, intervals=None, shortfall_intervals=None)

Convenience builder for FPCSignals with derived deltas.

This keeps the public governance entrypoint stable even if the FPCSignals dataclass grows fields later.

preset_thresholds(preset)

Return (DQCThresholds, FPCThresholds) for a governance preset.

Explicit thresholds passed to decide_governance override these defaults.

decide_governance(*, y, fpc_signals_raw, fpc_signals_snapped=None, dqc_thresholds=None, fpc_thresholds=None, preset=GovernancePreset.BALANCED)

Produce an authoritative governance decision for a single realized series.

Inputs

y: Realized demand series (used for DQC only). fpc_signals_raw: FPC signals computed in raw units. fpc_signals_snapped: Optional FPC signals computed after snapping forecasts to the detected demand grid. If not provided, the snapped decision is treated as equal to the raw decision. dqc_thresholds: Optional thresholds for DQC. Overrides preset thresholds. fpc_thresholds: Optional thresholds for FPC. Overrides preset thresholds. preset: GovernancePreset determining default thresholds when explicit thresholds are not provided.

Returns:

Type	Description
GovernanceDecision	Deterministic policy artifact.