mixle.reason.zero_shot_bootstrap module

Zero-shot modality bootstrap (workstream L3): a brand-new data type joins a cross-modal joint with NO retraining of anything already fitted.

Three pieces, in dependency order:

  1. induce_leaf_for_unseen_type() extends the automatic profiler (mixle.utils.automatic, see B-series work) with a real fallback chain for a genuinely unrecognized data type: try the profiler’s own classical-family induction first (it already covers numeric/categorical/ embedding/image/sequence shapes); if that abstains (IgnoredDistribution), fall back to classical (Gaussian/MVN) for simple numeric payloads, a generic GradLeaf-wrapped neural density for complex/high-dimensional numeric payloads, or a graph model / sequence model when the data carries that structure.

  2. resonance_embedding() scores a brand-new-modality sample against an existing, already- fitted model zoo – one generic “typicality” coordinate per zoo model, read off each model’s own capability surface (mixle.capability’s HasCDF/HasMoments): where does a generic scalar reduction of the new sample fall relative to THIS model’s own typical range? Evaluation only – no gradient steps, no fitting – hence “zero training.”

  3. resonance_adequacy_gate() reuses the separation statistic behind mixle.utils.hvis.topology.model_fit_health()’s merged-regime detector (a deterministic 2-means-style projected separation ratio, thresholded at the same measured finite-sample correction 2.65 + 6/sqrt(n)) to decide: is the resonance embedding’s class separation good enough to use as a lightweight, training-free proxy representation, or should the modality GRADUATE to a real native leaf (piece 1)?

add_modality_to_joint() plugs a new per-regime leaf (a native induced leaf, or a lightweight fit over resonance coordinates) into an existing CrossModalJoint by rebuilding each regime’s CompositeDistribution with the OLD per-modality distributions reused BY REFERENCE (never refit, never copied) plus the one new field – so every other modality’s fitted parameters are bitwise identical before and after.

induce_leaf_for_unseen_type(samples, *, rng=None, max_its=30)[source]

Induce and FIT a reasonable leaf distribution for samples of a data type the caller has never modeled before.

Tries, in order: (a) the existing automatic profiler’s own structural induction (numeric, categorical, embedding, image, sequence – whatever it already recognizes); (b) for data the profiler abstains on (IgnoredDistribution: e.g. arbitrary Python objects with no scalar or container structure it parses), a classical family (Gaussian / multivariate Gaussian) when a numeric feature vector can be extracted and is low/moderate-dimensional; (c) a generic GradLeaf-wrapped neural density when the extracted numeric payload is high-dimensional; (d) a graph model when samples carry adjacency/graph structure; (e) a sequence model when samples are variable-length collections of otherwise-inducible elements.

Parameters:
Return type:

SequenceEncodableProbabilityDistribution

resonance_embedding(new_modality_samples, model_zoo)[source]

K-dim (K = len(model_zoo)) embedding of each brand-new-modality sample, obtained by EVALUATION ONLY against every existing, already-fitted zoo model (regardless of the modality it was originally fitted to): coordinate k is how atypical a generic scalar reduction of the sample looks under zoo model k’s own closed-form typical range (its CDF/quantile position, or a moment-normalized z-score when no CDF is exposed). No gradient steps, no fitting – “zero training.”

Parameters:

  • new_modality_samples (Sequence[Any])

  • model_zoo (Sequence[SequenceEncodableProbabilityDistribution])

Return type:

ndarray

resonance_adequacy_gate(embedding_samples, labels_or_structure=None, *, threshold=None)[source]

Reuse the fit-health merged-regime separation statistic (see mixle.utils.hvis.topology.model_fit_health()) to decide whether the resonance embedding’s class separation is adequate to use as a lightweight, training-free proxy representation indefinitely (True), or whether the modality should GRADUATE to a real native leaf (False).

labels_or_structure, when given, is the known class/cluster label per embedding row; the worst (minimum) pairwise separation across classes is compared against the SAME finite-sample threshold model_fit_health uses for its own merged/unmerged call: 2.65 + 6/sqrt(n) (population value ~2.65 for a unimodal normal, inflated at small n). Without labels, the same deterministic 2-means split model_fit_health runs internally is used to discover a candidate 2-way structure and test whether IT is well separated.

Parameters:
Return type:

bool

add_modality_to_joint(joint, name, per_regime_leaves)[source]

Return a NEW CrossModalJoint with modality name added, one leaf per existing regime, WITHOUT touching any other modality’s fitted parameters.

Every existing per-regime CompositeDistribution is rebuilt with its OLD field distributions reused by reference (never copied, never refit) plus the one new field appended; the mixture weights are reused unchanged. per_regime_leaves can be the modality’s induced native leaf (see induce_leaf_for_unseen_type()) replicated across regimes, or per-regime leaves fit only over resonance-embedding coordinates (see fit_resonance_leaves()) – either way, this function itself performs no fitting at all.

Parameters:

  • joint (CrossModalJoint)

  • name (str)

  • per_regime_leaves (Sequence[SequenceEncodableProbabilityDistribution])

Return type:

CrossModalJoint

fit_resonance_leaves(resonance_embeddings, regime_labels, num_regimes)[source]

Fit one lightweight per-regime leaf directly over the K-dim resonance-embedding coordinates (a closed-form multivariate Gaussian, or a univariate Gaussian when K == 1), using known/assigned regime labels for the new-modality samples.

This fit touches ONLY the new modality’s own (yet-to-exist) leaf – it never reads or writes any other modality’s parameters, so combining its output with add_modality_to_joint() cannot retrain the rest of the joint.

Parameters:
Return type:

list[SequenceEncodableProbabilityDistribution]