Changelog#

Changelog#

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Changes are managed using towncrier and stored in the changelog.d/ directory. See changelog.d/README.md for instructions on adding changelog fragments.

v0.1.0a13 (2026-07-10)#

Changed#

  • Breaking: dimension parameter naming unification. All dimension parameters renamed from plural *_dims to singular *_dim (e.g., input_dims -> input_dim, hidden_dims -> hidden_dim, output_dims -> representation_dim). The encode-output width parameter is now uniformly representation_dim across all 10 models. RepresentationBackbone protocol updated to list all implementers and define representation_dim as the feature dim of encode() output. CONTRIBUTING.md updated with canonical singular names table and keyword-only signature convention. (#67)

  • Refactor: move distances to utils. Distance modules (e.g., SoftDTW) relocated from chronocratic.models.distances to chronocratic.models.utils.distances. Import paths updated accordingly.

Breaking Changes#

Full old -> new rename map for dimension parameters:

Old Name

New Name

Scope

input_dims

input_dim

All models

hidden_dims

hidden_dim

All models

feedforward_dims

feedforward_dim

TST, Series2Vec

embedding_dims

embedding_dim

Series2Vec

projection_dims

projection_dim

MCL

output_dims

representation_dim

MCL, TSTCC, TS2Vec, AutoTCL, CoST

representation_dims

representation_dim

Series2Vec

component_dims

component_dim

CoST (internal)

branch_dims

branch_dim

Series2Vec (internal)

_hidden_dims

_hidden_dim

TimeNet (private attr)

_input_dims

_input_dim

Private attrs

Names that did NOT change: latent_dim (TimeVAE — stochastic bottleneck), layers (RecurrentAE — genuine tuple), temporal_contrast_hidden_dim (TSTCC).

Pretrained checkpoints saved with old hyperparameter names will not reload cleanly. This is expected for an alpha release.

v0.1.0a12 (2026-07-07)#

Changed#

  • refactor(models): replace norm: str with NormalizationLayerType enum: Audited default hyperparameters across 10 models against upstream source repositories (7 models fixed), replaced duplicated norm: str parameter with type-safe NormalizationLayerType(StrEnum) enum, added missing Args docstrings to 8 model classes, and updated contributing guide with dataclass docstring and shared enum guidelines. (#64)

v0.1.0a11 (2026-07-03)#

Fixed#

  • fix(series2vec): Series2Vec batch_size=1 crash + representation_dim consistency: Fixes Series2Vec training crashes at batch_size=1 and aligns representation_dims with actual encoding output. Adds norm strategy toggle and reorganizes test files. (#61)

v0.1.0a10 (2026-07-02)#

Fixed#

  • fix(11): Series2Vec distance normalizer fix + batch_size=1 gradient safety across MCL/TSTCC/S2V: Fixed Series2Vec _distance_normalizer gradient break at batch_size=1, added norm parameter with GroupNorm default to MCL, TSTCC, and Series2Vec encoders for batch_size=1 safety, and created 40 parametrized gradient flow tests across all 10 models. (#57)

v0.1.0a9 (2026-07-01)#

Added#

  • feat(models): encoding output shape contract (VECTOR/SEQUENCE) across 10 models: Introduces a typed EncodingOutputShape contract (VECTOR / SEQUENCE) across all 10 models, so encode() can return a flat vector (B, D) or a full sequence (B, T, D) / (B, L', C) depending on model architecture. Adds supported_outputs to each mixin, _encode_batch output branching on 7 models, a _warn_sequence_fallback helper for Tier-C models with no native temporal axis, and a utils/ package split. Includes 2892 lines of new code (16 new test files, 10 model/mixin edits) and renames FCN → MCL. (#54)

v0.1.0a8 (2026-06-29)#

Added#

  • Add encode_batch() public API for DataLoader-free single-batch encoding. (#51)

v0.1.0a7 (2026-06-26)#

Fixed#

  • Align default parameters with source repositories. (#46)

v0.1.0a6 (2026-06-25)#

Added#

  • Conv1D encoder fix, mixin refactor, GPU/MPS hardening. (#43)

v0.1.0a5 (2026-06-23)#

Changed#

  • Standardize batch extraction across all models. (#39)

  • Strip supervision leakage from TSTCC core model. (#40)

v0.1.0a4 (2026-06-22)#

Added#

  • Add RecurrentAutoEncoder. (#20)

Changed#

  • Remove BC code, standardize *Producer naming, add parameter docs. (#34)

v0.1.0a3 (2026-06-18)#

Changed#

  • Standardize hyperparameter naming and defaults across all models. (#31)

v0.1.0a2 (2026-06-17)#

Added#

  • Standardize encoder/decoder access with HasEncoder/HasDecoder. (#25)

Changed#

  • Phase 06: prepare chronocratic-models for PyPI publication. (#21)

Fixed#

  • Correct Quick Start example and pin build badge to main. (#26)

v0.1.0a1 (2026-06-15) — First Alpha Release#

The first pre-release of chronocratic-models.

This alpha introduces the complete set of self-supervised time series models, the polymorphic augmentation framework, supervised fine-tuning infrastructure, and the Sphinx-based documentation.

Expect breaking changes before the 1.0 release.

Added#

  • Convolutional (Dilated) models: TS2Vec, CoST, AutoTCL — multi-scale representation learning via dilated convolutions, with PoolingEncodingMixin for sliding-window encoding.

  • Convolutional (Standard) models: Series2Vec, TSTCC, FCN — contrastive and clustering-based pretraining with BasicEncodingMixin.

  • Transformer model: TST — masked-reconstruction pretraining with configurable encoder depth and positional encoding.

  • Recurrent model: TimeNet — GRU-based encoder-decoder with autoencoder pretraining.

  • Generative model: TimeVAE — variational autoencoder with KL divergence + reconstruction loss.

  • Polymorphic augmentation producer contract: Models accept any augmentation through {AugmentationProducer} protocols, eliminating enum-based branching.

  • Augmentation primitives: Jitter, Scaling, Permutation, ComposeAugmentation with configurable *Parameters dataclasses.

  • Augmentation producers: SingleViewProducer, IndependentPair, RolePair, FullOverlapPair.

  • Trainable augmentation support: TrainableAugmentationProducer ABC and maybe_train_augmentation / maybe_configure_augmentation_optimizer utilities.

  • Supervised fine-tuning: SupervisedModule wrapper with four modes — linear probe, full fine-tune, gradual unfreeze, supervised-from-scratch.

  • Factory functions: make_tst_supervised, make_series2vec_supervised, make_tstcc_supervised for quick backbone + head setup.

  • BackboneUnfreeze callback: Lightning callback for gradual unfreezing of pretrained encoders.

  • ModelParameters dataclasses: One per model, with kw_only=True and Google-style Args: docstrings.

  • Shared layers: BandedFourierLayer, LevelModel, ResidualConnection, SeasonalLayer, TrendLayer.

  • Distance metrics: SoftDTW (differentiable dynamic time warping).

  • Encoding mixins: BasicEncodingMixin and PoolingEncodingMixin.

  • Sphinx documentation with autodoc-generated API reference per model family.

  • BSD 3-Clause license.

Notes#

  • Namespace is chronocratic.models (PyPI name is chronocratic-models).

  • Requires Python 3.12+.

  • Uses PyTorch and PyTorch Lightning as the primary framework.