Reports And Recommendations

Analyst-facing public-descent reports.

class updatesupport.report.PublicFiberDiagnostic(public_value, public_mass, hidden_cells, fiber_range, contribution, min_state, min_value, max_state, max_value, decomposition_available=True)[source]

Bases: object

Public-fiber contribution or point-range diagnostic.

Parameters:
public_value: tuple[Hashable, ...]
public_mass: float
hidden_cells: int
fiber_range: float
contribution: float | None
min_state: tuple[Hashable, ...]
min_value: float
max_state: tuple[Hashable, ...]
max_value: float
decomposition_available: bool = True
property contribution_available: bool
property diagnostic_kind: str
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.WitnessCellShift(state, public_value, state_label, public_label, target_value, lower_mass, upper_mass, mass_shift, abs_mass_shift, lower_contribution, upper_contribution, contribution_shift, abs_contribution_shift)[source]

Bases: object

One hidden-cell difference between lower and upper endpoint witnesses.

Parameters:
state: Hashable
public_value: Hashable
state_label: str
public_label: str
target_value: float
lower_mass: float
upper_mass: float
mass_shift: float
abs_mass_shift: float
lower_contribution: float | None
upper_contribution: float | None
contribution_shift: float | None
abs_contribution_shift: float | None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.WitnessFiberShift(public_value, public_label, hidden_cells, lower_public_mass, upper_public_mass, public_mass_difference, total_abs_mass_shift, lower_contribution, upper_contribution, contribution_shift)[source]

Bases: object

Public-fiber witness check and within-fiber movement summary.

Parameters:

  • public_value (Hashable)

  • public_label (str)

  • hidden_cells (int)

  • lower_public_mass (float)

  • upper_public_mass (float)

  • public_mass_difference (float)

  • total_abs_mass_shift (float)

  • lower_contribution (float | None)

  • upper_contribution (float | None)

  • contribution_shift (float | None)

public_value: Hashable
public_label: str
hidden_cells: int
lower_public_mass: float
upper_public_mass: float
public_mass_difference: float
total_abs_mass_shift: float
lower_contribution: float | None
upper_contribution: float | None
contribution_shift: float | None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.WitnessReport(grouped, interval, observed_value, cells, fibers, title='Adversarial Witness Report', top=20)[source]

Bases: ReportArtifactMixin

Adversarial lower-vs-upper hidden-composition witness report.

Parameters:
grouped: GroupedProblem
interval: TransportResult
observed_value: float
cells: tuple[WitnessCellShift, ...]
fibers: tuple[WitnessFiberShift, ...]
title: str = 'Adversarial Witness Report'
top: int = 20
property public_law_match: bool
property additive_contributions: bool
property lower_value: float
property upper_value: float
property ambiguity: float
as_dict()[source]
Return type:

dict[str, Any]

to_markdown()[source]
Return type:

str

class updatesupport.report.RefinementCandidate(column, before_ambiguity, after_ambiguity, reduction, reduction_percent, public_cells, before_ambiguity_bound_type='exact', after_ambiguity_bound_type='exact', screening_backend=None, screening_status=None, screening_certified=False, screening_exact_solve_run=False, screening_exact_solve_avoided=False, screening_conservative_ambiguity=None, screening_exact_ambiguity=None)[source]

Bases: object

One-column public refinement ranked by ambiguity reduction.

Parameters:

  • column (str)

  • before_ambiguity (float)

  • after_ambiguity (float)

  • reduction (float)

  • reduction_percent (float)

  • public_cells (int)

  • before_ambiguity_bound_type (str)

  • after_ambiguity_bound_type (str)

  • screening_backend (str | None)

  • screening_status (str | None)

  • screening_certified (bool)

  • screening_exact_solve_run (bool)

  • screening_exact_solve_avoided (bool)

  • screening_conservative_ambiguity (float | None)

  • screening_exact_ambiguity (float | None)

column: str
before_ambiguity: float
after_ambiguity: float
reduction: float
reduction_percent: float
public_cells: int
before_ambiguity_bound_type: str = 'exact'
after_ambiguity_bound_type: str = 'exact'
screening_backend: str | None = None
screening_status: str | None = None
screening_certified: bool = False
screening_exact_solve_run: bool = False
screening_exact_solve_avoided: bool = False
screening_conservative_ambiguity: float | None = None
screening_exact_ambiguity: float | None = None
property diameter: float

Backward-compatible alias for the after-refinement ambiguity.

property reduction_fraction: float
property percent_reduction: float

Alias for callers who prefer noun-first naming.

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.InteractionRefinementCandidate(columns, before_ambiguity, after_ambiguity, reduction, reduction_percent, public_cells, best_single_column=None, best_single_reduction=0.0, single_reduction_sum=0.0)[source]

Bases: object

Multi-column public refinement ranked by ambiguity reduction and gain.

Parameters:

  • columns (tuple[str, ...])

  • before_ambiguity (float)

  • after_ambiguity (float)

  • reduction (float)

  • reduction_percent (float)

  • public_cells (int)

  • best_single_column (str | None)

  • best_single_reduction (float)

  • single_reduction_sum (float)

columns: tuple[str, ...]
before_ambiguity: float
after_ambiguity: float
reduction: float
reduction_percent: float
public_cells: int
best_single_column: str | None = None
best_single_reduction: float = 0.0
single_reduction_sum: float = 0.0
property order: int
property column: str

Human-readable label compatible with one-column refinement tables.

property diameter: float

Backward-compatible alias for the after-refinement ambiguity.

property reduction_fraction: float
property percent_reduction: float

Alias for callers who prefer noun-first naming.

property interaction_gain: float

Additional reduction beyond the best single column in the set.

property interaction_gain_percent: float
property additive_synergy: float

Reduction beyond the sum of one-column reductions in the set.

property additive_synergy_percent: float
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.InteractionRefinementReport(candidates, singletons, title, public_columns, hidden_columns, candidate_refinements, target, q_name, q_description, baseline_ambiguity, max_order, evaluated_sets, truncated=False, max_evaluations=None, row_count=None)[source]

Bases: ReportArtifactMixin

Interaction-aware refinement search over small column sets.

Parameters:
candidates: tuple[InteractionRefinementCandidate, ...]
singletons: tuple[InteractionRefinementCandidate, ...]
title: str
public_columns: tuple[str, ...]
hidden_columns: tuple[str, ...]
candidate_refinements: tuple[str, ...]
target: str
q_name: str
q_description: str
baseline_ambiguity: float
max_order: int
evaluated_sets: int
truncated: bool = False
max_evaluations: int | None = None
row_count: int | None = None
property best: InteractionRefinementCandidate | None
property best_interaction: InteractionRefinementCandidate | None
as_dict()[source]
Return type:

dict[str, Any]

to_tables()[source]

Return named tables for structured export.

Return type:

dict[str, tuple[dict[str, Any], …]]

to_markdown()[source]
Return type:

str

class updatesupport.report.RefinementCoalitionEvaluation(columns, ambiguity, reduction, reduction_percent, public_cells)[source]

Bases: object

Ambiguity result for one candidate refinement coalition.

Parameters:
columns: tuple[str, ...]
ambiguity: float
reduction: float
reduction_percent: float
public_cells: int
property order: int
property label: str
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.RefinementAttribution(column, shapley_value, baseline_ambiguity, full_reduction, singleton_reduction, singleton_after_ambiguity, marginal_min, marginal_max, marginal_mean, evaluated_marginals)[source]

Bases: object

Shapley-style ambiguity-reduction attribution for one refinement column.

Parameters:

  • column (str)

  • shapley_value (float)

  • baseline_ambiguity (float)

  • full_reduction (float)

  • singleton_reduction (float)

  • singleton_after_ambiguity (float)

  • marginal_min (float)

  • marginal_max (float)

  • marginal_mean (float)

  • evaluated_marginals (int)

column: str
shapley_value: float
baseline_ambiguity: float
full_reduction: float
singleton_reduction: float
singleton_after_ambiguity: float
marginal_min: float
marginal_max: float
marginal_mean: float
evaluated_marginals: int
property shapley_share: float
property shapley_percent: float
property baseline_percent: float
property singleton_percent: float
property interaction_lift: float

Shapley attribution beyond the one-column reduction.

property interaction_lift_percent: float
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.RefinementAttributionReport(attributions, coalitions, title, public_columns, hidden_columns, candidate_refinements, target, q_name, q_description, baseline_ambiguity, full_ambiguity, full_reduction, method, exact, max_exact_columns, n_permutations=None, seed=None, evaluated_sets=0, row_count=None)[source]

Bases: ReportArtifactMixin

Shapley-style attribution of ambiguity reduction across refinements.

Parameters:
attributions: tuple[RefinementAttribution, ...]
coalitions: tuple[RefinementCoalitionEvaluation, ...]
title: str
public_columns: tuple[str, ...]
hidden_columns: tuple[str, ...]
candidate_refinements: tuple[str, ...]
target: str
q_name: str
q_description: str
baseline_ambiguity: float
full_ambiguity: float
full_reduction: float
method: str
exact: bool
max_exact_columns: int
n_permutations: int | None = None
seed: int | None = None
evaluated_sets: int = 0
row_count: int | None = None
property residual_ambiguity: float
property top_attribution: RefinementAttribution | None
property shapley_total: float
property approximation_gap: float
as_dict()[source]
Return type:

dict[str, Any]

to_tables()[source]

Return named tables for structured export.

Return type:

dict[str, tuple[dict[str, Any], …]]

to_markdown()[source]
Return type:

str

class updatesupport.report.RefinementSensitivityCandidate(column, evaluated_scenarios, mean_before_ambiguity, mean_after_ambiguity, mean_reduction, min_reduction, max_reduction, mean_reduction_percent, min_reduction_percent, max_reduction_percent, positive_reduction_scenarios, best_rank, mean_rank, worst_rank, top_rank_count, min_public_cells, max_public_cells)[source]

Bases: object

One refinement candidate aggregated over a sensitivity grid.

Parameters:

  • column (str)

  • evaluated_scenarios (int)

  • mean_before_ambiguity (float)

  • mean_after_ambiguity (float)

  • mean_reduction (float)

  • min_reduction (float)

  • max_reduction (float)

  • mean_reduction_percent (float)

  • min_reduction_percent (float)

  • max_reduction_percent (float)

  • positive_reduction_scenarios (int)

  • best_rank (int)

  • mean_rank (float)

  • worst_rank (int)

  • top_rank_count (int)

  • min_public_cells (int)

  • max_public_cells (int)

column: str
evaluated_scenarios: int
mean_before_ambiguity: float
mean_after_ambiguity: float
mean_reduction: float
min_reduction: float
max_reduction: float
mean_reduction_percent: float
min_reduction_percent: float
max_reduction_percent: float
positive_reduction_scenarios: int
best_rank: int
mean_rank: float
worst_rank: int
top_rank_count: int
min_public_cells: int
max_public_cells: int
property rank_range: int
property positive_reduction_share: float
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.RefinementSensitivityRow(scenario, column, rank, q_name, q_description, min_cell_weight, hidden_columns, before_ambiguity, after_ambiguity, reduction, reduction_percent, public_cells)[source]

Bases: object

One candidate’s refinement score in one sensitivity scenario.

Parameters:
scenario: str
column: str
rank: int
q_name: str
q_description: str
min_cell_weight: float
hidden_columns: tuple[str, ...]
before_ambiguity: float
after_ambiguity: float
reduction: float
reduction_percent: float
public_cells: int
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.RefinementSensitivityScenario(scenario, q_name, q_description, min_cell_weight, hidden_columns, candidate_count=0, best_column=None, best_reduction=None, baseline_ambiguity=None, status='ok', error=None)[source]

Bases: object

Scenario-level status for refinement sensitivity aggregation.

Parameters:

  • scenario (str)

  • q_name (str)

  • q_description (str)

  • min_cell_weight (float)

  • hidden_columns (tuple[str, ...])

  • candidate_count (int)

  • best_column (str | None)

  • best_reduction (float | None)

  • baseline_ambiguity (float | None)

  • status (str)

  • error (str | None)

scenario: str
q_name: str
q_description: str
min_cell_weight: float
hidden_columns: tuple[str, ...]
candidate_count: int = 0
best_column: str | None = None
best_reduction: float | None = None
baseline_ambiguity: float | None = None
status: str = 'ok'
error: str | None = None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.RefinementSensitivityReport(candidates, scenarios, rows, title='Public Refinement Sensitivity Report', row_count=None)[source]

Bases: ReportArtifactMixin

Refinement recommendations aggregated over a sensitivity grid.

Parameters:
candidates: tuple[RefinementSensitivityCandidate, ...]
scenarios: tuple[RefinementSensitivityScenario, ...]
rows: tuple[RefinementSensitivityRow, ...]
title: str = 'Public Refinement Sensitivity Report'
row_count: int | None = None
property successful_scenarios: tuple[RefinementSensitivityScenario, ...]
property failed_scenarios: tuple[RefinementSensitivityScenario, ...]
as_dict()[source]
Return type:

dict[str, Any]

to_markdown()[source]
Return type:

str

class updatesupport.report.StatisticalUncertainty(estimate=None, standard_error=None, lower=None, upper=None, confidence_level=None, method=None, label='Statistical uncertainty')[source]

Bases: object

Optional statistical uncertainty metadata supplied by an external workflow.

Parameters:

  • estimate (float | None)

  • standard_error (float | None)

  • lower (float | None)

  • upper (float | None)

  • confidence_level (float | None)

  • method (str | None)

  • label (str)

estimate: float | None = None
standard_error: float | None = None
lower: float | None = None
upper: float | None = None
confidence_level: float | None = None
method: str | None = None
label: str = 'Statistical uncertainty'
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.EstimatorUncertaintyAdjustment(base_lower, base_upper, base_diameter, confidence_multiplier, lower_endpoint_standard_error, upper_endpoint_standard_error, conservative_standard_error_bound, endpoint_lower, endpoint_upper, endpoint_diameter, conservative_lower, conservative_upper, conservative_diameter, confidence_core=None, method='endpoint_and_conservative')[source]

Bases: object

Estimator-standard-error adjustment for hidden-composition ambiguity.

Parameters:
base_lower: float
base_upper: float
base_diameter: float
confidence_multiplier: float
lower_endpoint_standard_error: float | None
upper_endpoint_standard_error: float | None
conservative_standard_error_bound: float
endpoint_lower: float | None
endpoint_upper: float | None
endpoint_diameter: float | None
conservative_lower: float
conservative_upper: float
conservative_diameter: float
confidence_core: UncertainLinearConfidenceCoreResult | None = None
method: str = 'endpoint_and_conservative'
property endpoint_lower_margin: float | None
property endpoint_upper_margin: float | None
property conservative_margin: float
property added_conservative_diameter: float
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.CausalReportingStabilitySuite(primary, sensitivity=None, refinement_sensitivity=None, statistical_uncertainty=None, title='Causal Reporting Stability Suite')[source]

Bases: ReportArtifactMixin

One-stop report object for causal-effect reporting stability.

Parameters:
primary: PublicDescentReport
sensitivity: SensitivityReport | None = None
refinement_sensitivity: RefinementSensitivityReport | None = None
statistical_uncertainty: StatisticalUncertainty | None = None
title: str = 'Causal Reporting Stability Suite'
as_dict()[source]
Return type:

dict[str, Any]

to_markdown()[source]
Return type:

str

class updatesupport.report.PublicDescentReport(grouped, observed_value, interval, public_adequate, fibers, refinements, title='Public Descent Report', target_description='target value', observed_label='Observed value', row_count=None, row_count_label='Rows', min_cell_weight=None, diagnostics=(), estimator_uncertainty=None, refinement_screening=None)[source]

Bases: ReportArtifactMixin

Structured public-descent audit with Markdown rendering.

Parameters:
grouped: GroupedProblem
observed_value: float
interval: TransportResult
public_adequate: bool
fibers: tuple[PublicFiberDiagnostic, ...]
refinements: tuple[RefinementCandidate, ...]
title: str = 'Public Descent Report'
target_description: str = 'target value'
observed_label: str = 'Observed value'
row_count: int | None = None
row_count_label: str = 'Rows'
min_cell_weight: float | None = None
diagnostics: tuple[DataDiagnostic, ...] = ()
estimator_uncertainty: EstimatorUncertaintyAdjustment | None = None
refinement_screening: Any | None = None
property fiber_decomposition_available: bool
property fiber_diagnostic_kind: str
property top_fiber_contribution: float | None
property top_fiber_contribution_share: float | None
property interval_contains_observed: bool
as_dict()[source]
Return type:

dict[str, Any]

witness_report(*, title='Adversarial Witness Report', top=20)[source]

Render the interval’s lower/upper endpoint witnesses as a report.

Parameters:
Return type:

WitnessReport

to_markdown()[source]
Return type:

str

updatesupport.report.public_descent_report(data, *, source_data=None, public=None, hidden=None, target=None, target_standard_error=None, weight=None, public_columns=None, hidden_columns=None, target_column=None, target_standard_error_column=None, weight_column=None, candidate_refinements=None, candidate_columns=None, top=10, min_cell_weight=1.0, title='Public Descent Report', target_description='target value', observed_label='Observed value', row_count=None, row_count_label='Rows', q=None, q_radius=None, target_confidence_multiplier=1.96, refinement_screening_backend=None, refinement_ambiguity_limit=None, refinement_screening_exact_fallback=True)[source]

Build an analyst-facing public-descent report.

data may be a raw dataframe/row iterable or a precompiled GroupedProblem. When data is precompiled, pass source_data to compute one-column refinement candidates.

target_standard_error supplies row-level target-estimator standard errors. The point-estimate transport interval is unchanged, and the report adds endpoint/conservative estimator-uncertainty-aware interval summaries.

Parameters:
Return type:

PublicDescentReport

updatesupport.report.witness_report(data, *, public=None, hidden=None, target=None, weight=None, public_columns=None, hidden_columns=None, target_column=None, weight_column=None, min_cell_weight=1.0, q='saturated', q_radius=None, title='Adversarial Witness Report', top=20)[source]

Build an adversarial lower-vs-upper witness report.

data may be a raw dataframe/row iterable, a precompiled GroupedProblem, or an existing PublicDescentReport.

Parameters:
Return type:

WitnessReport

updatesupport.report.audit_effects(data, *, source_data=None, public=None, hidden=None, effect=None, effect_standard_error=None, weight=None, public_columns=None, hidden_columns=None, effect_column=None, effect_standard_error_column=None, weight_column=None, candidate_refinements=None, candidate_columns=None, top=10, min_cell_weight=1.0, title='Causal Effect Representation Stability Audit', effect_description='estimated treatment effect', observed_label='Observed effect estimate', row_count=None, row_count_label='Rows', q=None, q_radius=None, effect_confidence_multiplier=1.96, refinement_screening_backend=None, refinement_ambiguity_limit=None, refinement_screening_exact_fallback=True)[source]

Audit whether public categories stably report estimated effects.

This is a convenience wrapper around public_descent_report() for causal or uplift workflows. A causal library should produce the row-level, subgroup-level, or hidden-cell-level effect target; this function audits the reporting representation for that supplied target.

Pass effect_standard_error when the causal estimator also supplies row-level or hidden-cell effect standard errors and the report should carry them into estimator-uncertainty-aware hidden-ambiguity summaries.

Parameters:
Return type:

PublicDescentReport

updatesupport.report.causal_reporting_stability(data, *, source_data=None, public=None, hidden=None, effect=None, effect_standard_error=None, weight=None, public_columns=None, hidden_columns=None, effect_column=None, effect_standard_error_column=None, weight_column=None, candidate_refinements=None, candidate_columns=None, min_cell_weight=1.0, q=None, q_radius=None, top=10, include_sensitivity=True, include_refinement_sensitivity=True, sensitivity_min_cell_weights=None, sensitivity_hidden_sets=None, sensitivity_q_presets=None, statistical_estimate=None, statistical_standard_error=None, statistical_interval=None, statistical_confidence_level=None, statistical_method=None, statistical_label='Statistical uncertainty', effect_confidence_multiplier=1.96, title='Causal Reporting Stability Suite', primary_title='Causal Effect Representation Stability Audit', raise_errors=False)[source]

Run the standard causal reporting-stability workflow.

This packages the main effect audit, optional Q/min-cell/hidden-set sensitivity grid, optional sensitivity-aware refinement ranking, and externally supplied statistical uncertainty metadata into one report object.

Parameters:
Return type:

CausalReportingStabilitySuite

updatesupport.report.public_fiber_diagnostics(grouped, *, top=10)[source]

Return public-fiber contribution or point-range diagnostics.

Parameters:
Return type:

tuple[PublicFiberDiagnostic, …]

updatesupport.report.recommend_refinements(data, *, public, hidden, target, candidate_refinements=None, candidate_columns=None, weight=None, min_cell_weight=1.0, q='saturated', q_radius=None, top=8, screening_backend=None, ambiguity_limit=None, screening_exact_fallback=True)[source]

Rank one-column public refinements by transport-ambiguity reduction.

Parameters:
Return type:

tuple[RefinementCandidate, …]

updatesupport.report.recommend_refinement_interactions(data, *, public, hidden, target, candidate_refinements=None, candidate_columns=None, weight=None, min_cell_weight=1.0, q='saturated', q_radius=None, max_order=2, top=8, max_evaluations=128, title='Interaction-Aware Refinement Search')[source]

Rank small refinement sets and expose interaction gains.

The ordinary refinement table tests one hidden column at a time. This search evaluates combinations up to max_order so analysts can detect cases where two or more individually weak refinements become strong together.

Parameters:
Return type:

InteractionRefinementReport

updatesupport.report.attribute_refinement_ambiguity(data, *, public, hidden, target, candidate_refinements=None, candidate_columns=None, weight=None, min_cell_weight=1.0, q='saturated', q_radius=None, max_exact_columns=8, n_permutations=None, seed=None, title='Refinement Ambiguity Attribution Report')[source]

Attribute joint ambiguity reduction to refinement columns.

The value function is the ambiguity reduction achieved by adding a set of hidden columns to the public representation. For small candidate sets this computes exact Shapley values by enumerating all coalitions. For larger candidate sets it defaults to permutation-sampled Shapley attribution.

Parameters:
Return type:

RefinementAttributionReport

updatesupport.report.recommend_refinements_sensitivity(data, *, public, hidden, target, candidate_refinements=None, candidate_columns=None, weight=None, min_cell_weights=(1.0,), hidden_sets=None, q_presets=None, top=8, title='Public Refinement Sensitivity Report', raise_errors=False)[source]

Aggregate one-column refinement rankings over a sensitivity grid.

Parameters:
Return type:

RefinementSensitivityReport

class updatesupport.report.SensitivityRow(scenario, q_name, q_description, min_cell_weight, hidden_columns, hidden_cells=None, public_cells=None, observed_value=None, lower=None, upper=None, ambiguity=None, public_adequate=None, status='ok', error=None)[source]

Bases: object

One robustness scenario in a sensitivity report.

Parameters:

  • scenario (str)

  • q_name (str)

  • q_description (str)

  • min_cell_weight (float)

  • hidden_columns (tuple[str, ...])

  • hidden_cells (int | None)

  • public_cells (int | None)

  • observed_value (float | None)

  • lower (float | None)

  • upper (float | None)

  • ambiguity (float | None)

  • public_adequate (bool | None)

  • status (str)

  • error (str | None)

scenario: str
q_name: str
q_description: str
min_cell_weight: float
hidden_columns: tuple[str, ...]
hidden_cells: int | None = None
public_cells: int | None = None
observed_value: float | None = None
lower: float | None = None
upper: float | None = None
ambiguity: float | None = None
public_adequate: bool | None = None
status: str = 'ok'
error: str | None = None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.SensitivitySummary(scenario_count, successful_scenarios, failed_scenarios, baseline_scenario, lowest_ambiguity_scenario, highest_ambiguity_scenario, min_ambiguity, max_ambiguity, ambiguity_span, public_adequacy_pattern, observed_min, observed_max, observed_span)[source]

Bases: object

Aggregate summary of a sensitivity-report scenario grid.

Parameters:

  • scenario_count (int)

  • successful_scenarios (int)

  • failed_scenarios (int)

  • baseline_scenario (str | None)

  • lowest_ambiguity_scenario (str | None)

  • highest_ambiguity_scenario (str | None)

  • min_ambiguity (float | None)

  • max_ambiguity (float | None)

  • ambiguity_span (float | None)

  • public_adequacy_pattern (str)

  • observed_min (float | None)

  • observed_max (float | None)

  • observed_span (float | None)

scenario_count: int
successful_scenarios: int
failed_scenarios: int
baseline_scenario: str | None
lowest_ambiguity_scenario: str | None
highest_ambiguity_scenario: str | None
min_ambiguity: float | None
max_ambiguity: float | None
ambiguity_span: float | None
public_adequacy_pattern: str
observed_min: float | None
observed_max: float | None
observed_span: float | None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.report.SensitivityReport(rows, title='Public Descent Sensitivity Report', row_count=None)[source]

Bases: ReportArtifactMixin

Robustness grid over Q presets, hidden sets, and min-cell thresholds.

Parameters:
rows: tuple[SensitivityRow, ...]
title: str = 'Public Descent Sensitivity Report'
row_count: int | None = None
property successful_rows: tuple[SensitivityRow, ...]
property failed_rows: tuple[SensitivityRow, ...]
property summary: SensitivitySummary
as_dict()[source]
Return type:

dict[str, Any]

to_markdown()[source]
Return type:

str

updatesupport.report.sensitivity_report(data, *, public, hidden, target, weight=None, min_cell_weights=(1.0,), hidden_sets=None, q_presets=None, title='Public Descent Sensitivity Report', raise_errors=False)[source]

Run robustness checks over Q presets, hidden sets, and cell thresholds.

Parameters:
Return type:

SensitivityReport

Representation-stability certification over frontier search results.

class updatesupport.certificate.RepresentationStabilityCertificate(frontier, selected_candidate, status, exact_required=True, title='Representation Stability Certificate', reasons=(), limitations=())[source]

Bases: ReportArtifactMixin

Review-ready decision artifact for a public reporting representation.

Parameters:
frontier: PublicRepresentationFrontier
selected_candidate: PublicRepresentationCandidate | None
status: str
exact_required: bool = True
title: str = 'Representation Stability Certificate'
reasons: tuple[str, ...] = ()
limitations: tuple[str, ...] = ()
property passed: bool

Whether the selected representation is certified under the spec.

property inconclusive: bool

Whether the run found evidence but cannot certify it as conclusive.

property failed: bool

Whether no evaluated representation satisfied the certificate.

property search_exact: bool

Whether the frontier searched exact endpoint values throughout.

property certified_candidate: PublicRepresentationCandidate | None

Return the selected candidate only when the certificate passed.

property best_evaluated_candidate: PublicRepresentationCandidate | None

Most stable evaluated representation, regardless of certification.

as_dict()[source]
Return type:

dict[str, Any]

to_markdown()[source]
Return type:

str

updatesupport.certificate.certify_public_representation(data, *, ambiguity_limit, exact_required=True, require_exact=None, screening_backend=None, screening_exact_fallback=True, title='Representation Stability Certificate', frontier_title='Public Representation Frontier Evidence', **frontier_kwargs)[source]

Certify a public representation against a frontier stress-test search.

The certificate passes when the frontier finds an evaluated representation whose worst-case ambiguity is no larger than ambiguity_limit and whose public-cell count is within bucket_budget when a budget is supplied. By default, heuristic frontier searches are marked inconclusive rather than passed; set exact_required=False to allow heuristic certificates.

Parameters:

  • data (Any)

  • ambiguity_limit (float)

  • exact_required (bool)

  • require_exact (bool | None)

  • screening_backend (str | None)

  • screening_exact_fallback (bool)

  • title (str)

  • frontier_title (str)

  • frontier_kwargs (Any)

Return type:

RepresentationStabilityCertificate