mixle.reason.cycle_consistency module

Cycle-consistency diagnostics for cross-modal calibration and abstention.

A forward transport’s reported confidence can miss an observation function that maps several latent states to the same observed value. Round-trip closure adds a self-supervised check: draw independent posterior samples of the latent given the observation, project them through the invariant content, and measure self-agreement. Low self-agreement indicates a region where the transport should abstain or escalate even if its marginal confidence is high.

The diagnostic uses NeuralConditionalDensity and build_mdn fitted via mixle.inference.optimize(); it does not add a new transport family.

fit_cycle_transport(given, target, *, k=3, hidden=32, layers=2, max_its=30, m_steps=80, lr=3e-3, seed=0, delta=1.0e-9, reuse_estep_ll=True)[source]

Fit p(target | given) via a mixture density network.

given/target are (n, d) arrays of paired observations. delta/reuse_estep_ll default to optimize()’s own early-stopping; pass delta=None, reuse_estep_ll=False for a harder, more multimodal target.

Parameters:
Return type:

Any

cycle_inconsistency(sampler, given_value, *, n_draws=20, forward, scale)[source]

Return scaled A -> B -> A round-trip inconsistency for one observation.

sampler draws B conditioned on the originating A value and forward maps each B draw back into A space. scale supplies the positive, unit-aware residual scale for A. A constant but wrong forward map therefore receives a nonzero error instead of a falsely perfect dispersion score.

This answers “is the forward map right here”, NOT “is B determined here”. Closure error cannot see posterior ambiguity, and on a collapsing observation map it is anti-correlated with it: where many B values share one A value, every draw round-trips back onto that same A, so the cycle closes perfectly exactly where B is least identified. Use posterior_ambiguity for that question.

Parameters:
Return type:

float

posterior_ambiguity(sampler, given_value, *, n_draws=20, target_scale)[source]

Return the standardized spread of the B draws for one A observation.

A well-determined posterior yields draws that agree closely; an observation in a collapsed region – where many B values produce the same A – yields draws that disagree, without needing the true B. target_scale supplies the positive, unit-aware scale for B.

This is the abstention signal, and it is deliberately NOT folded into cycle_inconsistency. The two answer different questions and disagree by construction: on a collapsing observation map every draw round-trips back onto the same A, so closure error is LOWEST exactly where B is least determined. Summing them lets the anti-correlated closure term outvote the spread. Use cycle_inconsistency to ask whether the forward map is right, and this to ask whether B is pinned down.

Parameters:
Return type:

float

posterior_mean_estimate(sampler, given_value, *, n_draws=20)[source]

Return the posterior-sample mean of the target given given_value.

Parameters:
Return type:

ndarray

class CycleKLReceipt(source, target, raw_estimate, standard_error, confidence_interval, sample_count, nonnegative_estimate, clipped_to_nonnegative)[source]

Bases: object

Monte Carlo evidence for a probabilistic round-trip comparison.

Parameters:
joint_cycle_consistency_receipt(joint, source, target, *, backward_joint=None, n_round_trip=300, n_kl_samples=500, seed=0)[source]

Cross-modal generalization (workstream L2) of this module’s round-trip closure signal.

cycle_inconsistency above measures round-trip closure (A -> B -> A) for a NEURAL transport, where the true target is unknown at serving time and self-AGREEMENT among repeated draws is the only available proxy. A CrossModalJoint is a typed grammar object, not an opaque transport: its true marginal p(source) is available in closed form (CrossModalJoint.infer() with no observations), so the round-trip receipt here compares the round-trip estimate DIRECTLY against that true marginal, rather than against itself.

Two ways to arrive at a belief about source through the joint: (1) directly, its own marginal p(source); (2) via a round trip, p(source) -> infer p(target | source) -> infer p(source | target) back, averaged over many draws into one aggregate “round-trip” belief. This receipt is a Monte-Carlo KL-divergence estimate between (2) and (1); a well-specified joint recovers its own marginal on a round trip (the receipt is ~0 up to Monte-Carlo noise), while a deliberately mis-specified backward projection (backward_joint – e.g. a joint whose target-given-regime distributions have been shuffled relative to joint’s, standing in for a broken/incompatible A<-B projection) breaks that identity and the receipt becomes clearly, measurably elevated.

Parameters:

  • joint (CrossModalJoint)

  • source (str)

  • target (str)

  • backward_joint (CrossModalJoint | None)

  • n_round_trip (int)

  • n_kl_samples (int)

  • seed (int)

Return type:

CycleKLReceipt

selective_error(errors, abstain_scores, keep_frac)[source]

Return mean error on examples kept by the lowest abstention scores.

Lower is better: a useful abstention signal keeps examples the policy can answer and escalates examples with higher expected error.

Parameters:
Return type:

float