Claim Audits

Claim-level reporting-stability audits.

class updatesupport.claim.ClaimAudit(claim, primary, certificate=None, witness=None, model_assisted=None, decision=None, decision_repair_candidate=None, decision_repair_search_exact=None, screening=None, status='inconclusive', reasons=(), limitations=(), title='Claim Audit')[source]

Bases: ReportArtifactMixin

Review artifact that certifies, breaks, or repairs a reporting claim.

Parameters:
claim: ClaimSpec
primary: PublicDescentReport
certificate: RepresentationStabilityCertificate | None = None
witness: WitnessReport | None = None
model_assisted: ModelAssistedStabilitySummary | None = None
decision: DecisionResult | None = None
decision_repair_candidate: PublicRepresentationCandidate | None = None
decision_repair_search_exact: bool | None = None
screening: ClaimScreeningResult | None = None
status: str = 'inconclusive'
reasons: tuple[str, ...] = ()
limitations: tuple[str, ...] = ()
title: str = 'Claim Audit'
property passed: bool
property failed: bool
property inconclusive: bool
property repair_candidate: PublicRepresentationCandidate | None
property observed_value: float

Reported value audited by this claim.

property interval

Primary hidden-composition interval.

property ambiguity: float

Primary hidden-composition ambiguity width.

property refinement_recommendations: tuple[ClaimRefinementRecommendation, ...]

Rank refinements by their role in stabilizing this claim.

recommend_refinements(*, top=None)[source]

Return claim-centered public-refinement recommendations.

This is intentionally different from the lower-level updatesupport.recommend_refinements(): it annotates each candidate with claim-specific repair signals such as whether it satisfies the ambiguity limit or is the selected decision-invariant repair.

Parameters:

top (int | None)

Return type:

tuple[ClaimRefinementRecommendation, …]

repair_plan(*, action_costs=None, top=None, title='Claim Repair Plan')[source]

Return a cost-aware repair plan for this claim audit.

Parameters:
Return type:

ClaimRepairPlan

breaking_witness(**kwargs)[source]

Find the closest decision-breaking recomposition for this audit.

Parameters:

kwargs (Any)

Return type:

MinimumClaimBreakingWitnessReport

as_dict()[source]
Return type:

dict[str, Any]

to_markdown()[source]
Return type:

str

class updatesupport.claim.ClaimNode(claim, children=(), name=None, role=None, metadata=<factory>)[source]

Bases: object

One node in a nested claim tree.

A node wraps an ordinary ClaimSpec and optional child nodes. This keeps hierarchical audits as an orchestration/reporting concern: each node is still audited by the same single-claim machinery.

Parameters:
claim: ClaimSpec | Mapping[str, Any]
children: Sequence[ClaimNode | ClaimSpec | Mapping[str, Any]] = ()
name: str | None = None
role: str | None = None
metadata: Mapping[str, Any]
classmethod from_dict(payload)[source]

Build a claim node from a JSON-compatible mapping.

Parameters:

payload (Mapping[str, Any])

Return type:

ClaimNode

property label: str
audit(data, **kwargs)[source]

Audit this node and its descendants against tabular data.

Parameters:
Return type:

ClaimNodeAudit

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.ClaimNodeAudit(node, audit, children=(), path=(), depth=0)[source]

Bases: object

Audit result for one claim-tree node and its descendants.

Parameters:
node: ClaimNode
audit: ClaimAudit
children: Sequence[ClaimNodeAudit] = ()
path: Sequence[str] = ()
depth: int = 0
property label: str
property branch: str
property status: str
property ambiguity: float
property passed: bool
property failed: bool
property inconclusive: bool
walk()[source]
Return type:

tuple[ClaimNodeAudit, …]

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.ClaimRepairOption(rank, columns, source, cost, before_ambiguity, after_ambiguity, reduction, reduction_percent, public_cells, satisfies_ambiguity_limit=None, certifies_claim=False, selected_repair=False, decision_repair=False, reason='')[source]

Bases: object

One candidate public-representation repair for a claim.

Parameters:

  • rank (int)

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

  • source (str)

  • cost (float)

  • before_ambiguity (float | None)

  • after_ambiguity (float)

  • reduction (float | None)

  • reduction_percent (float | None)

  • public_cells (int)

  • satisfies_ambiguity_limit (bool | None)

  • certifies_claim (bool)

  • selected_repair (bool)

  • decision_repair (bool)

  • reason (str)

rank: int
columns: tuple[str, ...]
source: str
cost: float
before_ambiguity: float | None
after_ambiguity: float
reduction: float | None
reduction_percent: float | None
public_cells: int
satisfies_ambiguity_limit: bool | None = None
certifies_claim: bool = False
selected_repair: bool = False
decision_repair: bool = False
reason: str = ''
property label: str
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.ClaimRepairPlan(audit, options, action_costs=<factory>, title='Claim Repair Plan')[source]

Bases: ReportArtifactMixin

Cost-aware consolidation of claim repair and refinement evidence.

Parameters:
audit: ClaimAudit
options: tuple[ClaimRepairOption, ...]
action_costs: Mapping[str, float]
title: str = 'Claim Repair Plan'
property recommended: ClaimRepairOption | None
property certifying_options: tuple[ClaimRepairOption, ...]
property non_certifying_options: tuple[ClaimRepairOption, ...]
property status: str
property recommended_label: str | None
as_dict()[source]
Return type:

dict[str, Any]

to_tables()[source]
Return type:

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

to_markdown()[source]
Return type:

str

class updatesupport.claim.ClaimRefinementRecommendation(columns, source, before_ambiguity, after_ambiguity, reduction, reduction_percent, public_cells, meets_ambiguity_limit=None, selected_repair=False, decision_repair=False, reason='')[source]

Bases: object

Claim-centered public-refinement recommendation.

Parameters:

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

  • source (str)

  • before_ambiguity (float | None)

  • after_ambiguity (float)

  • reduction (float | None)

  • reduction_percent (float | None)

  • public_cells (int)

  • meets_ambiguity_limit (bool | None)

  • selected_repair (bool)

  • decision_repair (bool)

  • reason (str)

columns: tuple[str, ...]
source: str
before_ambiguity: float | None
after_ambiguity: float
reduction: float | None
reduction_percent: float | None
public_cells: int
meets_ambiguity_limit: bool | None = None
selected_repair: bool = False
decision_repair: bool = False
reason: str = ''
property label: str
property column: str

Compatibility label for one-column recommendation tables.

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.ClaimScreeningResult(backend, attempted, used, certified, fallback_required, exact_solve_avoided, reason, observed_value=None, lower=None, upper=None, ambiguity=None, decision_invariant=None, ambiguity_limit_met=None, q_name=None, conservative=True, compiled_templates_built=0, support_solves=0, error=None)[source]

Bases: object

Optional conservative pre-screen used before an exact claim audit.

Parameters:

  • backend (str)

  • attempted (bool)

  • used (bool)

  • certified (bool)

  • fallback_required (bool)

  • exact_solve_avoided (bool)

  • reason (str)

  • observed_value (float | None)

  • lower (float | None)

  • upper (float | None)

  • ambiguity (float | None)

  • decision_invariant (bool | None)

  • ambiguity_limit_met (bool | None)

  • q_name (str | None)

  • conservative (bool)

  • compiled_templates_built (int)

  • support_solves (int)

  • error (str | None)

backend: str
attempted: bool
used: bool
certified: bool
fallback_required: bool
exact_solve_avoided: bool
reason: str
observed_value: float | None = None
lower: float | None = None
upper: float | None = None
ambiguity: float | None = None
decision_invariant: bool | None = None
ambiguity_limit_met: bool | None = None
q_name: str | None = None
conservative: bool = True
compiled_templates_built: int = 0
support_solves: int = 0
error: str | None = None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.ClaimSpec(estimate_name, public, hidden, target, weight=None, q=None, q_presets=('saturated',), candidate_refinements=(), ambiguity_limit=None, bucket_budget=None, decision=None, statistical_interval=None, statistical_uncertainty=None, min_cell_weight=1.0, min_cell_weights=None, hidden_sets=None, top=10, witness_top=20, search='exhaustive', max_added_columns=None, beam_width=12, max_evaluations=None, must_include=(), must_exclude=(), enforce_bucket_budget=False, include_base=True, exact_required=True, title=None, target_description=None, observed_label='Reported estimate', screening_backend=None, refinement_screening_backend=None, refinement_screening_exact_fallback=True)[source]

Bases: object

Declarative claim that a reported aggregate is stable enough to defend.

Parameters:
estimate_name: str
public: Sequence[str]
hidden: Sequence[str]
target: str | RowMetric | ProcedureTarget
weight: str | None = None
q: Any | None = None
q_presets: Sequence[Any] = ('saturated',)
candidate_refinements: Sequence[str] = ()
ambiguity_limit: float | None = None
bucket_budget: int | None = None
decision: DecisionRule | Mapping[str, Any] | None = None
statistical_interval: tuple[float, float] | None = None
statistical_uncertainty: StatisticalUncertainty | Mapping[str, Any] | None = None
min_cell_weight: float = 1.0
min_cell_weights: Sequence[float] | None = None
hidden_sets: Sequence[Sequence[str]] | None = None
top: int = 10
witness_top: int = 20
search: str = 'exhaustive'
max_added_columns: int | None = None
beam_width: int = 12
max_evaluations: int | None = None
must_include: Sequence[str] = ()
must_exclude: Sequence[str] = ()
enforce_bucket_budget: bool = False
include_base: bool = True
exact_required: bool = True
title: str | None = None
target_description: str | None = None
observed_label: str = 'Reported estimate'
screening_backend: str | None = None
refinement_screening_backend: str | None = None
refinement_screening_exact_fallback: bool = True
classmethod from_dict(payload)[source]

Build a claim from a JSON-compatible mapping.

Parameters:

payload (Mapping[str, Any])

Return type:

ClaimSpec

property primary_q: Any

Q preset used for the primary public-descent report.

as_dict()[source]
Return type:

dict[str, Any]

to_dict()[source]

Alias for as_dict().

Return type:

dict[str, Any]

audit(data, **kwargs)[source]

Audit this claim against tabular data.

Parameters:
Return type:

ClaimAudit

design(data, **kwargs)[source]

Design the smallest defensible public report for this claim.

Parameters:
Return type:

PublicReportDesign

calibrate_tv(data, **kwargs)[source]

Calibrate a TV stress radius from historical period transitions.

Parameters:

  • data (Any)

  • kwargs (Any)

Return type:

HistoricalTVCalibrationReport

design_calibrated(historical_data, current_data, **kwargs)[source]

Design a public report under historically calibrated TV stress.

Parameters:

  • historical_data (Any)

  • current_data (Any)

  • kwargs (Any)

Return type:

CalibratedPublicReportDesign

design_categorical_rollup(data, **kwargs)[source]

Design an exact one-column categorical rollup under saturated Q.

Parameters:

  • data (Any)

  • kwargs (Any)

Return type:

CategoricalRollupDesign

breaking_witness(data, **kwargs)[source]

Find the closest fixed-public recomposition that fails this claim.

Parameters:

  • data (Any)

  • kwargs (Any)

Return type:

MinimumClaimBreakingWitnessReport

class updatesupport.claim.ClaimTree(root, name='Nested Claim Audit', description=None)[source]

Bases: object

Nested collection of claims audited as one hierarchy.

Parameters:
root: ClaimNode | ClaimSpec | Mapping[str, Any]
name: str = 'Nested Claim Audit'
description: str | None = None
classmethod from_dict(payload)[source]

Build a claim tree from a JSON-compatible mapping.

Parameters:

payload (Mapping[str, Any])

Return type:

ClaimTree

audit(data, **kwargs)[source]

Audit every node in the claim tree against tabular data.

Parameters:
Return type:

ClaimTreeAudit

as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.ClaimTreeAudit(tree, root, title='Nested Claim Audit')[source]

Bases: ReportArtifactMixin

Nested claim report for hierarchical or multi-level review workflows.

Parameters:
tree: ClaimTree
root: ClaimNodeAudit
title: str = 'Nested Claim Audit'
property nodes: tuple[ClaimNodeAudit, ...]
property node_count: int
property leaf_count: int
property pass_count: int
property fail_count: int
property inconclusive_count: int
property status: str
property passed: bool
property failed: bool
property inconclusive: bool
property max_ambiguity: float
worst_nodes(*, top=5, statuses=('fail', 'inconclusive'))[source]

Return the highest-risk claim nodes by status and ambiguity.

Parameters:
Return type:

tuple[ClaimNodeAudit, …]

as_dict()[source]
Return type:

dict[str, Any]

to_tables()[source]
Return type:

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

to_markdown()[source]
Return type:

str

class updatesupport.claim.DecisionResult(rule, observed_value, lower, upper, observed_decision, lower_decision, upper_decision, invariant, certified_decision, threshold_crossed, reason)[source]

Bases: object

Decision-rule evaluation over a hidden-composition interval.

Parameters:
rule: DecisionRule
observed_value: float
lower: float
upper: float
observed_decision: str
lower_decision: str
upper_decision: str
invariant: bool
certified_decision: str | None
threshold_crossed: bool
reason: str
property status: str
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.DecisionRule(operator, threshold, label=None, pass_label='pass', fail_label='fail')[source]

Bases: object

Threshold decision rule for a reported scalar estimate.

Parameters:

  • operator (str)

  • threshold (float)

  • label (str | None)

  • pass_label (str)

  • fail_label (str)

operator: str
threshold: float
label: str | None = None
pass_label: str = 'pass'
fail_label: str = 'fail'
property name: str
evaluate(value)[source]
Parameters:

value (float)

Return type:

str

interval_result(*, observed_value, lower, upper)[source]
Parameters:
Return type:

DecisionResult

as_dict()[source]
Return type:

dict[str, Any]

classmethod from_value(value)[source]
Parameters:

value (DecisionRule | Mapping[str, Any])

Return type:

DecisionRule

class updatesupport.claim.ModelAssistedDrawResult(draw_index, observed_value, lower, upper, ambiguity, public_adequate, status, error=None)[source]

Bases: object

One model-assisted joint-composition draw evaluated for stability.

Parameters:

  • draw_index (int)

  • observed_value (float | None)

  • lower (float | None)

  • upper (float | None)

  • ambiguity (float | None)

  • public_adequate (bool | None)

  • status (str)

  • error (str | None)

draw_index: int
observed_value: float | None
lower: float | None
upper: float | None
ambiguity: float | None
public_adequate: bool | None
status: str
error: str | None = None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.ModelAssistedStabilitySummary(joint_model, rows, ambiguity_limit=None, seed=None, uncertainty_report=None)[source]

Bases: object

Stability summary over fitted-joint distribution draws.

Parameters:
joint_model: NonparametricJointDistribution
rows: tuple[ModelAssistedDrawResult, ...]
ambiguity_limit: float | None = None
seed: int | None = None
uncertainty_report: HiddenCompositionUncertaintyReport | None = None
property draw_count: int
property successful_draws: int
property failed_draws: int
property error_count: int
property failure_rate: float | None
property public_adequate_rate: float | None
property ambiguities: tuple[float, ...]
property ambiguity_min: float | None
property ambiguity_max: float | None
property ambiguity_mean: float | None
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.claim.PublicReportDesign(audit, repair_plan, certificate=None, frontier=None, attribution=None, title='Public Report Design')[source]

Bases: ReportArtifactMixin

One-stop design artifact for the smallest defensible public report.

Parameters:
audit: ClaimAudit
repair_plan: ClaimRepairPlan
certificate: RepresentationStabilityCertificate | None = None
frontier: Any | None = None
attribution: RefinementAttributionReport | None = None
title: str = 'Public Report Design'
property status: str
property recommended_option: ClaimRepairOption | None
property selected_candidate: PublicRepresentationCandidate | None
property recommended_public: tuple[str, ...] | None
property recommended_label: str | None
as_dict()[source]
Return type:

dict[str, Any]

to_tables()[source]
Return type:

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

to_markdown()[source]
Return type:

str

updatesupport.claim.audit_claim(data, claim, *, joint_model=None, joint_draws=0, joint_seed=None, **overrides)[source]

Audit a declared reporting claim against tabular data.

Parameters:
Return type:

ClaimAudit

updatesupport.claim.audit_claim_tree(data, tree, **kwargs)[source]

Audit a nested claim tree against tabular data.

Parameters:
Return type:

ClaimTreeAudit

updatesupport.claim.claim(estimate_name, *, public, hidden, target, **kwargs)[source]

Create a claim spec using the simplified claim-first API.

Parameters:
Return type:

ClaimSpec

updatesupport.claim.claim_tree(root, *, children=(), name='Nested Claim Audit', description=None)[source]

Create a nested claim tree from a root claim and optional children.

Parameters:
Return type:

ClaimTree

updatesupport.claim.design_public_report(claim_or_audit, data=None, *, action_costs=None, top=None, include_attribution=False, attribution_max_exact_columns=8, attribution_permutations=None, attribution_seed=None, title='Public Report Design', **audit_overrides)[source]

Design a defensible public representation for a declared claim.

This is the claim-first orchestration layer. It audits the claim, reuses the embedded certificate/frontier search, packages a cost-aware repair plan, and optionally adds Shapley-style refinement attribution.

Parameters:
Return type:

PublicReportDesign

updatesupport.claim.plan_claim_repair(claim_or_audit, data=None, *, action_costs=None, top=None, title='Claim Repair Plan', **audit_overrides)[source]

Build a cost-aware repair plan from a claim audit or claim spec.

This is a consolidation layer over existing claim evidence. If a ClaimAudit is supplied, no additional solve is run. If a ClaimSpec or mapping is supplied, data is audited first and the repair plan is built from that audit.

Parameters:
Return type:

ClaimRepairPlan

updatesupport.claim.threshold_decision(operator=None, threshold=None, *, pass_if=None, label=None, pass_label='pass', fail_label='fail')[source]

Create a threshold decision rule for claim audits.

Parameters:

  • operator (str | None)

  • threshold (float | None)

  • pass_if (str | None)

  • label (str | None)

  • pass_label (str)

  • fail_label (str)

Return type:

DecisionRule