Diagnostic validation

This section documents validation utilities for diagnostics in eb-evaluation.

Diagnostic validation utilities check diagnostic outputs for structural correctness and consistency.

eb_evaluation.diagnostics.validate

Public validation entrypoints for diagnostic artifacts.

This module defines stable, versioned entrypoints for running Electric Barometer diagnostics. Consumers should prefer these functions over importing diagnostic modules directly.

The goal is API stability: diagnostic implementations may evolve, but these entrypoints remain stable and auditable.

GateResult dataclass

Result of running the governance gate from common raw inputs.

This is a convenience orchestrator that: - computes DQC from realized demand y, - computes raw FPC signals from (y, yhat_base, yhat_ral, tau, cwsl_r), - optionally computes snapped FPC signals when DQC requires snapping, - runs the governance decision contract, - returns an explicit recommended evaluation mode for downstream routing.

The authoritative decision is always decision (GovernanceDecision).

validate_fpc(*, signals, thresholds=None)

Run Forecast Primitive Compatibility (FPC) classification.

Parameters:

Name	Type	Description	Default
signals	FPCSignals	Precomputed observable signals used by FPC.	required
thresholds	FPCThresholds | None	Optional governance thresholds. If not provided, defaults are used.	None

Returns:

Type	Description
FPCResult	Compatibility class + signals + rationale.

validate_dqc(*, y, thresholds=None)

Run Demand Quantization Compatibility (DQC) classification.

Parameters:

Name	Type	Description	Default
y	Sequence[float]	Realized demand/usage series for a single entity.	required
thresholds	DQCThresholds | None	Optional governance thresholds. If not provided, defaults are used.	None

Returns:

Type	Description
DQCResult	Quantization class + signals + rationale.

validate_governance(*, y, fpc_signals_raw, fpc_signals_snapped=None, dqc_thresholds=None, fpc_thresholds=None, preset=None)

Run the governance decision contract (DQC x FPC) for a single entity.

This is the stable public entrypoint for governance-oriented evaluation. It combines: - Demand Quantization Compatibility (DQC): whether snapping to a demand grid is required - Forecast Primitive Compatibility (FPC): whether scale-based readiness adjustment (e.g., RAL) is structurally valid, evaluated in raw space and (when required) snapped space.

Presets

If preset is provided, callers MUST NOT also pass explicit dqc_thresholds and/or fpc_thresholds. Mixing a preset with explicit thresholds is ambiguous and is rejected.

Parameters:

Name	Type	Description	Default
y	Sequence[float]	Realized demand/usage series for a single entity. This should be the raw realized series (not pre-snapped).	required
fpc_signals_raw	FPCSignals	Observable FPC signals computed in raw units (no snapping).	required
fpc_signals_snapped	FPCSignals | None	Observable FPC signals computed after applying the snap-to-grid policy. Required when DQC indicates snapping is required; optional otherwise.	None
dqc_thresholds	DQCThresholds | None	Optional thresholds for DQC classification.	None
fpc_thresholds	FPCThresholds | None	Optional thresholds for FPC classification (applied to both raw and snapped signals).	None
preset	str | GovernancePreset | None	Optional governance preset. Provide either: - preset name: {"conservative", "balanced", "aggressive"}, or - a GovernancePreset instance.	None

Returns:

Type	Description
GovernanceDecision	A deterministic, auditable decision artifact containing: - DQC result (structure / snap requirement) - FPC results (raw + snapped) - snapping and τ interpretation policy - readiness adjustment allowability policy (traffic-light status)

Raises:

Type	Description
ValueError	If preset is provided together with explicit thresholds.
TypeError	If preset is not a str or GovernancePreset.
ValueError	If preset is a str but not a known preset name.

run_governance_gate(*, y, yhat_base, yhat_ral, tau, cwsl_r=None, dqc_thresholds=None, fpc_thresholds=None, preset=None)

Orchestrate governance from common raw inputs.

This helper computes FPC signals directly from series inputs and produces an explicit recommended evaluation mode:

• "continuous": demand is continuous-like; evaluate in raw units.
• "pack_aware": demand is quantized/packed; τ and adjustments should be interpreted in grid units; forecasts/adjustments should be snapped as required.
• "reroute_discrete": forecast primitive is incompatible for readiness control; consider rerouting to a discrete/event/state decision model.

Preset rules match validate_governance: do not mix preset with explicit thresholds.