mixle.represent.generative module

Generative objective for fitting embeddings and optional codebooks.

Rather than tune the encoder to a label, train it to reconstruct its input as an autoencoder over units. The shared-space vector must retain enough information to rebuild the unit, so the representation has an explicit generative objective. Add a VectorQuantizer and the model becomes a VQ-VAE: encode -> quantize (straight-through) -> decode, with the codebook periodically refit on the current embeddings. The learned vocabulary is then selected by reconstruction quality instead of being fixed by a tokenizer chosen outside the model.

fit_autoencoder returns the trained encoder + decoder (+ codebook) and the reconstruction-loss history. It is modality-agnostic: feed it the unit-feature array from any continuous segmenter (patches, windows, atoms, …).

class AutoencoderResult(encoder, decoder, quantizer, losses=<factory>)[source]

Bases: object

A reconstruction-trained representation with encoder, decoder, optional codebook, and loss curve.

Parameters:

  • encoder (FeatureEmbedding)

  • decoder (Any)

  • quantizer (VectorQuantizer | None)

  • losses (list[float])

encode(units)[source]

Encode units through the trained autoencoder encoder.

Parameters:

units (ndarray)

Return type:

ndarray

fit_autoencoder(units, dim, *, hidden=(), quantizer=None, epochs=200, lr=1e-2, refit_codebook_every=25, commitment=0.25, seed=0)[source]

Train an encoder+decoder to reconstruct units (N, in_features) with an optional VQ bottleneck.

Without quantizer this is a standard autoencoder. With one, it is a VQ-VAE: the encoder’s vectors are quantized (straight-through) before decoding and the codebook is refit every refit_codebook_every epochs on the current embeddings. commitment weights the VQ codebook-commitment term.

Parameters:
Return type:

AutoencoderResult