Results

PartitionResult dataclass

PartitionResult(
    labels: ndarray,
    training_scores: ndarray,
    cell_weights: ndarray,
    cell_score_sums: ndarray,
    cell_score_means: ndarray,
    information_full: ndarray,
    information_partitioned: ndarray,
    objective: float,
    transform: FisherTransform,
    transformed_centers: ndarray | None,
    metric: ndarray | None,
    criterion: DOptimality | ProfiledDOptimality,
    config: PartitionConfig,
    execution: ExecutionConfig,
    train_report: InformationReport,
    provenance: ScoreProvenance,
    accepted_moves: int,
    scans: int,
    exchange_stable: bool,
    best_remaining_gain: float,
    objective_history: ndarray,
    positive_weight_mask: ndarray,
    lloyd_iterations: int = 0,
    accepted_lloyd_steps: int = 0,
    geometry: GeometryReport | None = None,
    profiled_report: ProfiledInformationReport
    | None = None,
    profiled_geometry: ProfiledGeometryReport | None = None,
    schema: ScoreSchema | None = None,
)

Represent optimized labels of one fixed weighted score table.

The solver counters are reported separately and never merged: scans and accepted_moves describe exchange work, while lloyd_iterations and accepted_lloyd_steps describe guarded batch relabelings. Both stay zero for a solver that performs neither. objective_history records every accepted step of every phase in order and is strictly increasing.

Geometry diagnostics are criterion-specific and never shared: a DOptimality result carries geometry and no profiled_geometry, a ProfiledDOptimality result carries profiled_geometry and no geometry. The two measure different objects — a strict Mahalanobis Voronoi rule that exchange stability guarantees, and an efficient semimetric whose Voronoi rule a stable profiled partition may violate — so one name for both would claim an implication that does not hold.

exchange_stable and geometry are verdicts at config.gain_tolerance, which GeometryReport records, and never claims at tolerance zero. A finite solver stops at that threshold, so verifying its output against a stricter one would reject partitions it legitimately converged on.

n_bins property

n_bins: int

Return the number of nonempty requested cells.

rank property

rank: int

Return the numerically informative score-space rank.

information_kind property

information_kind: InformationKind

Describe whether supplied-score matrices justify exact Fisher language.

"supplied_score_surrogate" means the reported matrices measure Var(E[s_hat | q]) for the supplied vectors s_hat, which is the model's Fisher information only when s_hat equals the model score.

report

report() -> InformationReport

Return supplied-score information for the fixed partition.

compile_quantizer

compile_quantizer(
    *, execution: ExecutionConfig | None = None
) -> Quantizer

Compile an exchange-stable D partition into its canonical rule.

Theorem 3 makes a one-point-exchange-stable, nonsingular D partition a self-consistent \(I^{-1}\)-Mahalanobis Voronoi partition of the observed rows, so the compiled rule \(\hat q(s)=\arg\min_b (s-\mu_b)^\top I^{-1}(s-\mu_b)\) is bookkeeping rather than a new fit. The theorem is exact; the partition behind it is not. A finite solver stops at config.gain_tolerance, so the guarantee this method can offer is self-consistency at that tolerance: each admissible individual prediction disagreement has relocation gain at most gain_tolerance, priced against the original partition. Successful solver result construction separately checks that every positive-weight disagreement is admissible. Positive tolerance alone does not guarantee compilability: a singleton tie can be refused (CE-D-COMPILE-SINGLETON-TIE-001). No bound on simultaneous relabeling, global suboptimality or population loss follows from the tolerance (CE-D-COMPILE-BATCH-TOLERANCE-001). These are numerical exact-formula diagnostics in the retained score subspace, not interval arithmetic.

Boundary ties are never resolved here. predict_scores keeps the ordinary argmin rule, which is deterministic and breaks a tie toward the lowest cell index; the tolerance governs verification, not assignment.

Returns:

• Quantizer –

  The deployable rule itself -- the partition's centers, metric and transform. It is a rule, not a new fit, so it carries no labels, reports or history; those already belong to this partition.

Raises:

• ContractError –

  When the compilation geometry is missing.

• RefusalError –

  When the criterion is not DOptimality, when the partition is not exchange-stable, or when the rule relabels a training row by more than gain_tolerance.

to_dict

to_dict() -> dict[str, JsonValue]

Return the fixed-sample result as JSON-ready data.

QuantizerResult dataclass

QuantizerResult(
    quantizer: Quantizer,
    criterion: Criterion,
    config: QuantizerConfig,
    execution: ExecutionConfig,
    trace: OptimizationTrace,
    labels: ndarray,
    train_report: InformationReport,
    validation_report: InformationReport | None,
    provenance: ScoreProvenance,
    hardening_gap: float | None = None,
    source_kind: SourceKind = "score_sample",
    train_profiled_report: ProfiledInformationReport
    | None = None,
    validation_profiled_report: ProfiledInformationReport
    | None = None,
)

Represent a reusable hard rule on raw score vectors.

centers property

centers: ndarray

Return the frozen cell centers in transformed coordinates.

metric property

metric: ndarray | None

Return the frozen common Mahalanobis metric, if the rule carries one.

transform property

transform: FisherTransform

Return the informative-subspace projection the rule was fitted in.

schema property

schema: ScoreSchema | None

Return the names of the raw score coordinates, when they were declared.

n_bins property

n_bins: int

Return the number of hard output labels.

rank property

rank: int

Return the numerically informative score-space rank.

information_kind property

information_kind: InformationKind

Describe whether supplied-score matrices justify exact Fisher language.

"supplied_score_surrogate" means the reported matrices measure Var(E[s_hat | q]) for the supplied vectors s_hat, which is the model's Fisher information only when s_hat equals the model score.

predict_scores

predict_scores(
    scores: ArrayLike,
    *,
    execution: ExecutionConfig | None = None,
) -> ndarray

Assign raw score rows with the frozen score-space rule.

Rows are assigned in memory-bounded chunks so that predicting on a large sample never materializes the full [n_rows, n_bins, rank] distance tensor at once; each row's distance and nearest-center argmin are independent of every other row, so chunking is bit-identical to the unchunked computation.

evaluate_scores

evaluate_scores(
    scores: ArrayLike,
    weights: ArrayLike | None = None,
    *,
    execution: ExecutionConfig | None = None,
) -> InformationReport

Evaluate the frozen rule on a new weighted score sample.

report

report() -> InformationReport

Return final hard training-sample diagnostics.

to_dict

to_dict() -> dict[str, JsonValue]

Return JSON-ready in-memory state, not a versioned artifact format.

plot_summary

plot_summary(
    scores: ArrayLike, weights: ArrayLike | None = None
) -> Figure

Create the optional score-space summary figure.

Quantizer dataclass

Quantizer(
    transform: FisherTransform,
    centers: ndarray,
    metric: ndarray | None,
    schema: ScoreSchema | None,
    provenance: ScoreProvenance,
    criterion: Criterion,
    execution: ExecutionConfig,
)

A frozen hard rule on score space.

This is what a fit is for: the object that turns a future score vector into a bin. It holds no training labels, no reports and no history -- those stay on :class:~scorequant.QuantizerResult, which exposes the rule as result.quantizer.

Attributes:

• transform (FisherTransform) –

  Projection onto the informative score subspace the rule was fitted in.

• centers (ndarray) –

  Cell centers in transformed coordinates, shape [K, R].

• metric (ndarray | None) –

  Optional common Mahalanobis metric, shape [R, R]. None means the ordinary Euclidean nearest-center rule in transformed coordinates.

• schema (ScoreSchema | None) –

  Optional names of the raw score coordinates the rule expects.

• provenance (ScoreProvenance) –

  How the scores the rule was fitted on were obtained.

• criterion (Criterion) –

  The objective the rule was optimized for, recorded so a loaded artifact can still say what it was built to preserve.

• execution (ExecutionConfig) –

  The backend the rule was fitted under, reused for prediction unless overridden.

n_bins property

n_bins: int

Return the number of hard output labels.

rank property

rank: int

Return the numerically informative score-space rank.

input_dim property

input_dim: int

Return the raw score dimension the rule accepts.

information_kind property

information_kind: InformationKind

Describe whether supplied-score matrices justify exact Fisher language.

predict_scores

predict_scores(
    scores: ArrayLike,
    *,
    execution: ExecutionConfig | None = None,
) -> ndarray

Assign raw score rows with the frozen rule.

Rows are assigned in memory-bounded chunks, so predicting on a large sample never materializes the full [n_rows, n_bins, rank] distance tensor at once. Each row's nearest-center argmin is independent of every other row, so chunking is bit-identical to the unchunked computation.

evaluate_scores

evaluate_scores(
    scores: ArrayLike,
    weights: ArrayLike | None = None,
    *,
    rank_rtol: float | None = None,
    execution: ExecutionConfig | None = None,
) -> InformationReport

Measure the information this rule retains on a new weighted sample.

This is a property of the rule rather than of the fit that produced it, so a loaded artifact can be scored against fresh data without the training result being present.

Parameters:

• rank_rtol (float | None, default: None ) –

  Relative rank threshold for the report. Defaults to the one the rule's own transform was built with.

to_dict

to_dict() -> dict[str, JsonValue]

Return JSON-ready rule state.

Unlike the diagnostic to_dict on the result types, this one is the readable face of a versioned format: :meth:save writes exactly these fields, with the arrays moved out to .npy members.

save

save(path: str | Path) -> Path

Write the rule to a versioned, non-pickle artifact.

The file is a zip archive holding one manifest.json and one .npy member per array. Nothing is pickled, so loading it executes no code from the file, and reading it back needs neither JAX nor the solver that produced it.

Parameters:

• path (str | Path) –

  Destination path. .sqz is appended when the path has no suffix.

Returns:

• Path –

  The path actually written.

load classmethod

load(path: str | Path) -> Quantizer

Read a rule written by :meth:save.

Raises:

• ValueError –

  When the file is not a ScoreQuant artifact, or declares a format_version this build does not know. An unknown version is refused by name rather than partially interpreted.

InformationReport dataclass

InformationReport(
    fisher_unbinned: ndarray,
    fisher_binned: ndarray,
    retained_matrix: ndarray,
    retained_eigenvalues: ndarray,
    arithmetic_mean_retention: float,
    geometric_mean_retention: float,
    logdet_retention: float,
    bin_weights: ndarray,
    bin_counts: ndarray,
    bin_effective_sample_sizes: ndarray,
    effective_rank: int,
    rank_threshold: float,
    psd_residual_min_eigenvalue: float,
)

Report supplied-score retention and per-bin diagnostics for one sample.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible representation.

__str__

__str__() -> str

Format headline supplied-score diagnostics.

ProfiledInformationReport dataclass

ProfiledInformationReport(
    interest: tuple[int, ...],
    nuisance: tuple[int, ...],
    schur_unbinned: ndarray,
    schur_binned: ndarray,
    nuisance_unbinned: ndarray,
    nuisance_binned: ndarray,
    objective: float,
    logdet_retention: float,
    geometric_mean_retention: float,
    interest_rank: int,
    nuisance_rank: int,
    schema: ScoreSchema | None = None,
)

Report same-label profiled information for interest and nuisance blocks.

interest_names property

interest_names: tuple[str, ...] | None

Return the names of the parameters of interest, when they were declared.

nuisance_names property

nuisance_names: tuple[str, ...] | None

Return the names of the profiled nuisance parameters, when declared.

describe

describe() -> str

Summarize the profiling split in one line, by name when one is available.

interest: HSPCs says what was optimized; interest: (4,) requires the reader to remember the column order.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible profiled-information representation.

RetentionUncertainty dataclass

RetentionUncertainty(
    estimate: float | None,
    standard_error: float | None,
    confidence_interval: tuple[float, float] | None,
    confidence_level: float,
    n_observations: int,
    status: RetentionUncertaintyStatus,
)

Sampling uncertainty of a frozen rule's geometric-mean retention on held-out true scores.

Produced by retention_uncertainty. The point estimate is the same uncentred plug-in \(\hat\eta_D=(\det\hat I_Z/\det\hat V)^{1/d}\) that information_report reports as geometric_mean_retention on a full-rank sample; the standard error is the influence-function estimate of RETENTION-PLUGIN-CLT-FROZEN-VECTOR (scalar case RETENTION-PLUGIN-CLT-FROZEN-SCALAR), and the interval is the untruncated two-sided Wald interval \(\hat\eta_D\pm z_{1-\alpha/2}\,\widehat{\mathrm{SE}}\). It is never clipped, so an endpoint can fall below zero or above one; that is a property of the first-order interval, not a claim about the retention.

The interval covers sampling variability only: the rule is frozen, the rows are independent and equally weighted draws from the reference law, and the scores are the model's true scores. A classifier or other estimated score adds a separate reporting bias that no error bar on the proxy sample measures.

Attributes:

• estimate (float | None) –

  Plug-in geometric-mean retention, None when the rule declares too few cells or the full moment matrix is rank deficient, and exactly 0.0 by convention when the retained matrix is numerically rank deficient.

• standard_error (float | None) –

  Influence-function standard error, 0.0 when the influence values cancel to rounding noise, and None whenever no first-order theory applies.

• confidence_interval (tuple[float, float] | None) –

  (lower, upper) Wald endpoints, or None when the interval is unavailable.

• confidence_level (float) –

  Nominal two-sided level the interval was built for.

• n_observations (int) –

  Number of evaluation rows the moments were formed from.

• status (RetentionUncertaintyStatus) –

  "ok": estimate, standard error and interval are all available. "insufficient_cells": the rule declares at most d cells, so the population retention is zero at the reference law (FI-RANK-CEILING) and the plug-in is the biased endpoint estimator; nothing is reported. "singular_full_information": the supplied scores lose a direction at the rank threshold, so the geometric-mean retention of all d directions is undefined and nothing is reported rather than a silently projected surrogate. "singular_retained_information": the full matrix is regular but the between-cell matrix is numerically rank deficient on this sample, so the diagnostic reports zero by its numerical-rank convention and withholds the interval. The exact plug-in can still be positive below the threshold; the verdict does not identify the population rank (RETENTION-PLUGIN-SINGULAR-ENDPOINT-RATE). "degenerate_variance": the influence values vanish to rounding, so the interval is withheld; this is a numerical guard and does not assert that the population variance is zero.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible representation without non-finite sentinels.

__str__

__str__() -> str

Format the estimate, its standard error and the interval, when available.

GeometryReport dataclass

GeometryReport(
    maximum_voronoi_violation: float,
    guaranteed_violation_gain: float,
    maximum_violation_gain: float,
    maximum_separation_residual: float,
    violating_moves: int,
    evaluated_moves: int,
    voronoi_consistent: bool,
    separation_certified: bool,
    gain_tolerance: float,
)

Certify the self-consistent Voronoi geometry of a finite D partition.

At a one-point-exchange-stable, positive-definite D partition every admissible move that violates the Mahalanobis-Voronoi rule of the terminal metric \(I^{-1}\) would raise the log determinant by at least \(\log(1+\alpha\beta q_\delta^2/4)>0\), where \(q_\delta=(\mu_a-\mu_b)^\top I^{-1}(\mu_a-\mu_b)\) separates the two cell means. Exact zero-tolerance stability under the merged-atom hypotheses therefore forces strict Voronoi geometry, which is what makes PartitionResult.compile_quantizer well posed. This report measures both sides of that statement on the terminal state instead of assuming them.

A finite solver stops at a tolerance, so this certificate states one too. The theorem is exact, but the guaranteed gain of a violation shrinks with the cell separation, and on a large sample \(q_\delta\) shrinks with the sample size: once \(\log(1+\alpha\beta q_\delta^2/4)\) falls below the solver's gain_tolerance, exchange stability at that tolerance no longer forbids a row from sitting a hair past a cell boundary. Verifying such a state at tolerance zero rejects a partition the solver never claimed to have refined further, so every field below is judged against gain_tolerance instead.

At positive tolerance this report covers admissible individual moves only. It does not certify that every prediction disagreement is admissible; the solver checks that separately and refuses singleton disagreements. It also supplies no bound on simultaneous relabeling or population loss.

All quadratic forms use the same metric and cell means the solver ended with, evaluated over the distinct positive-weight score atoms.

Attributes:

• maximum_voronoi_violation (float) –

  Largest value over rows of the own-cell distance minus the smallest other-cell distance. A nonpositive value means every row already sits in its nearest cell under the terminal metric. It is -inf for a single-cell partition, which has no alternative destination. This is a Mahalanobis distance gap, not a criterion gain, so it is a diagnostic and never the verdict.

• guaranteed_violation_gain (float) –

  Largest Theorem-3 lower bound \(\log(1+\alpha\beta q_\delta^2/4)\) over admissible Voronoi-violating moves, and exactly 0.0 when no such move exists.

• maximum_violation_gain (float) –

  Largest exact log-determinant gain over the same admissible Voronoi-violating moves, and exactly 0.0 when none exists. Theorem 3 bounds this from below, so guaranteed_violation_gain <= maximum_violation_gain always holds. This is the quantity the solver drives below its tolerance, so it is the one the verdict uses.

• maximum_separation_residual (float) –

  Largest value over unordered cell pairs of \(q_\delta-(1/W_a+1/W_b)\). The leverage lemma makes this nonpositive for every labeling, so a positive value indicates numerical trouble rather than a better partition. It is -inf for a single-cell partition.

• violating_moves, evaluated_moves –

  Number of admissible Voronoi-violating moves and of admissible moves. A move is admissible when its source cell keeps positive weight and its destination differs from its source.

• voronoi_consistent (bool) –

  Whether maximum_violation_gain is at most gain_tolerance: no Voronoi violation is worth more than the solver's own stopping threshold. It is True whenever no row is misplaced at all.

• separation_certified (bool) –

  Whether maximum_separation_residual respects the leverage lemma up to a small relative floating-point tolerance.

• gain_tolerance (float) –

  Log-determinant gain tolerance this certificate holds at, taken from the configuration that produced the labels. voronoi_consistent means self-consistent at this tolerance and claims nothing at tolerance zero.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible Voronoi-geometry representation.

ProfiledGeometryReport dataclass

ProfiledGeometryReport(
    metric: ndarray,
    maximum_positive_violation: float,
    maximum_theoretical_bound: float,
    maximum_bound_residual: float,
    violating_moves: int,
    evaluated_moves: int,
    bound_certified: bool,
)

Diagnose the finite efficient-semimetric gap of a profiled partition.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible geometry-gap representation.

EfficientScoreBound dataclass

EfficientScoreBound(
    upper_bound: float,
    labels: ndarray,
    efficient_scores: ndarray,
    n_bins: int,
    interest: tuple[int, ...],
)

Certify a ceiling on profiled information from the full-data efficient score.

Let \(\hat s=s_\psi-B^\ast s_\lambda\) be the efficient score built from the full-data information matrix, and let \(q\) be any hard rule with at most n_bins cells. Efficient-score domination states

\[ \mathrm{Schur}_\psi\!\left(I_q\right)\;\preceq\; \mathbb{E}\!\left[\hat s \mid q\right]\text{-between-cell information}, \]

so maximizing the right-hand side over all n_bins-cell rules of \(\hat s\) upper-bounds the profiled objective of every n_bins-cell rule of the full score space. For one parameter of interest the right-hand side is scalar, the maximizer has ordered interval cells, and the exact weighted interval dynamic program attains it. upper_bound is the logarithm of that maximum, in the same convention as PartitionResult.objective under ProfiledDOptimality: an uncentered between-cell second moment of raw score columns, never a mean-centered variance.

Attributes:

• upper_bound (float) –

  Log-scale certified ceiling on the profiled objective.

• labels (ndarray) –

  Interval labels of the efficient score, defined for every input row. Zero-weight rows carry the label of their nearest cell mean and never influence the bound. These labels are also a strong initializer: pass them as initial_labels to optimize_partition under ProfiledDOptimality.

• efficient_scores (ndarray) –

  Full-information efficient scores with shape [N, 1].

• n_bins, interest –

  Cell budget and interest columns the bound was certified for.

Notes

The bound is a property of one weighted score table. Comparing it to a partition of different scores or weights is meaningless, and gap_to cannot detect that mismatch; it only checks the criterion convention and the cell budget. Refinement monotonicity makes the bound valid for any partition with at most n_bins cells.

gap_to

gap_to(partition_result: PartitionResult) -> float

Return the certified slack between the bound and an achieved objective.

Parameters:

• partition_result (PartitionResult) –

  Profiled-\(D_s\) result on the same weighted score table, with the same interest columns and at most n_bins cells.

Returns:

• float –

  upper_bound minus the achieved profiled objective. The value is nonnegative up to floating-point error on valid inputs.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible representation of the certified bound.

OptimizationTrace dataclass

OptimizationTrace(
    steps: ndarray,
    centers: ndarray,
    objective: ndarray,
    bin_weights: ndarray,
    train_hard_retention: ndarray,
    objective_label: str,
    validation_hard_retention: ndarray | None = None,
    soft_retention: ndarray | None = None,
    temperatures: ndarray | None = None,
    gradient_norms: ndarray | None = None,
)

Store aggregate quantizer optimization history.

Attributes:

• objective_label (str) –

  Units of objective. Solvers do not share one objective convention: "whitened_sse" is a minimized weighted within-cell squared error in Fisher-whitened coordinates, "logdet_retained" is a maximized retained log determinant, and "profiled_logdet" is a maximized profiled log determinant. Never compare two traces across labels.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible representation.

ScoreProvenance dataclass

ScoreProvenance(
    kind: ScoreKind = "unknown",
    description: str | None = None,
    reference_point: tuple[float, ...] | None = None,
    metadata: Mapping[str, JsonValue] = dict(),
    ratio: RatioProvenance | None = None,
)

Describe where supplied score coordinates came from.

exact_fisher is derived from kind rather than accepted as an independent flag, so estimated scores cannot accidentally claim exact Fisher semantics. Scores built from model density ratios additionally carry a ratio record describing how the ratios were obtained.

exact_fisher property

exact_fisher: bool

Return whether exact-Fisher language is permitted.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible provenance mapping.

ScoreQuantError

Bases: Exception

Base of every exception ScoreQuant raises deliberately.

ContractError

Bases: ScoreQuantError, ValueError

The caller violated an input, shape, range, or pairing contract.

Detectable from the arguments alone; the remedy is to change the call. Subclasses ValueError so existing except ValueError handlers keep working.

RefusalError

RefusalError(message: str, counterexample: str)

Bases: ScoreQuantError, RuntimeError

The library declines a valid request because a theorem-backed condition fails on the data.

Parameters:

• message (str) –

  Plain-English refusal, unchanged from the pre-hierarchy message text.

• counterexample (str) –

  Registry id (agenticresearch/COUNTEREXAMPLES/<id>.json) of the counterexample that forces the refusal. Always a string literal at the raise site.