Harden and complete the autoencoder API

[sergioald]

Summary

This PR hardens the existing autoencoder training path and completes the public
autoencoder API.

It combines four related improvements:

1. Training and input robustness
2. Convenience access to the shared reconstruction metrics
3. Explicit latent decoding
4. Self-describing PyTorch model checkpoints

Changes

Training and input robustness

• Validate the leading sample dimension and target length
• Validate validation_split, batch_size, epochs, and patience
• Require at least two training samples and one validation sample
• Correct the documented tabular-input contract: training data must include
  a leading sample dimension
• Detect models containing BatchNorm1d
• Reject batch_size=1 clearly for those models instead of failing inside
  PyTorch
• Rebalance only a final singleton training batch while preserving every
  sample
• Preserve batch_size=1 for models that do not contain BatchNorm1d
• Make LatentDecorr neutral when sample covariance is undefined for a
  one-sample batch
• Reject incompatible per-sample shapes when fitting an already built model
• Require training criteria to return scalar losses
• Validate prediction, encoding, decoding, and reconstruction-evaluation
  batch sizes

The existing train/validation loss-history aggregation semantics are retained.

Reconstruction convenience API

• Add model.reconstruction_error(...)
• Add model.evaluate_reconstruction(...)
• Add model.evaluate(...) as a concise alias
• Reuse the accepted functions in bluemath_tk.deeplearning.metrics
• Preserve the documented final-frame targets for
  ConvLSTMAutoencoder and
  HybridConvLSTMTransformerAutoencoder

Decode API

• Add model.decode(Z)
• Add decode_forward() implementations for all seven existing
  autoencoders
• Support batched latent decoding
• Support a single one-dimensional latent vector
• Test that decode(encode(X)) reproduces the same inference path as
  predict(X)

Checkpoint improvements

• Save the constructor configuration and model-building input shape
• Add a checkpoint format version
• Keep instance-based load_pytorch_model(...)
• Build an uninitialised instance automatically from saved metadata
• Add ClassName.from_pytorch_model(...) for one-step restoration
• Validate checkpoint/model class compatibility
• Detect constructor parameters that cannot be captured automatically
• Retain a clear path for loading legacy checkpoints into an already built
  model

These are model checkpoints; optimizer state is intentionally outside this
PR's scope.

Tests

• Encode/decode shape coverage for all seven autoencoders
• Equivalence checks between predict(X) and decode(encode(X))
• Regression coverage for final singleton training batches
• Explicit batch_size=1 behaviour with and without BatchNorm1d
• Singleton-validation coverage for latent decorrelation
• Input and repeated-fit shape validation
• Inference batch-size validation
• Shared reconstruction-metric convenience checks
• ConvLSTM final-frame metric semantics
• Standard and ConvLSTM checkpoint round trips
• Single-vector decoding
• Updated instructions in the moved autoencoder smoke-test file

Scope

This PR does not add a new model architecture and does not change the
mathematical definition of the accepted reconstruction metrics. It makes the
existing autoencoders safer to train, easier to evaluate and decode, and
portable between sessions.

Local validation

compileall: passed
focused Ruff checks: passed
autoencoder smoke tests: 8 passed
autoencoder API tests: 20 passed
metrics tests: 8 passed
full suite: 241 passed, 113 warnings

The warnings are existing dependency and project warnings, primarily from
cmocean/Matplotlib, Shapely, GPyTorch, and interpolation tests. No test failed.

[sergioald]

Ruff note: the new API code and the critical syntax/undefined-name checks for the modified architecture files pass successfully. A full Ruff run over bluemath_tk/deeplearning still reports pre-existing style issues in develop, mainly in autoencoders.py, layers.py, metrics.py, unet.py, and some existing tests. I have therefore avoided mixing this PR with an unrelated package-wide lint cleanup. The focused checks pass, and the full test suite completes successfully with 241 tests passed.