Skip to content

Releases

v6.0.1

Choose a tag to compare

@github-actions github-actions released this 25 Sep 15:36

6.0.1 (2026-09-25)

📔 Docs

  • agents: point the issue tracker at structcast-model [skip ci] (5c6415c)

🔧 Fixes

  • torch: print a failing rank's traceback and abort its process group (5880169), closes #34

🚨 Tests

  • flax: reject a non-callable tensor initializer (59b564d), closes #22

v6.0.0

Choose a tag to compare

@github-actions github-actions released this 25 Sep 09:29

6.0.0 (2026-09-25)

⚠ BREAKING CHANGES

  • structcast_model.torch.TensorInitializer,
    structcast_model.torch.types.TensorInitializer,
    structcast_model.flax.TensorInitializer and
    structcast_model.keras.TensorInitializer are removed; import
    TensorInitializer from structcast_model.base_trainer instead.

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_015K4E7Ft7T57yLYon1je361

  • builders: templates relying on automatic dtype/param_dtype
    injection into third-party layers must now write it in the layer's
    call (e.g. dtype: "eval: dtype", param_dtype: "eval: param_dtype").

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_015K4E7Ft7T57yLYon1je361

  • cfg: scm keras time -c cfg/keras/others/compile_default.yaml
    no longer resolves; pass --compile true or a backend-specific mapping.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

  • keras: keras learners run their steps eagerly unless
    scm keras train --compile is given; the torch backend refuses the flag.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

  • flax: scm flax train runs its steps eagerly unless --compile is
    given, and --compile none is no longer accepted.

Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com

  • cfg: clip_grad_norm on the torch learner templates previously
    selected the p-norm order with the clipping threshold fixed at 1.0. It is now the
    L2 threshold the global gradient norm is scaled down to, matching the Flax and
    Keras templates. Anyone who set it must re-read their value: clip_grad_norm: 2.0
    used to clip at 1.0 under an L2 norm and now clips at 2.0.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • DistributedStrategy gains data_rank/data_world_size,
    so external strategy implementations must add both properties before
    isinstance checks against the protocol accept them again.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • trainer: Learner implementations must expose flow_functions;
    under MirroredStrategy an empty mapping is an error, not a fallback.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • trainer: Learner implementations must replace update(step)
    with the steps/updates/has_updated properties and restore_counters.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • schema: keras and flax templates carrying ACCUMULATE_GRADIENTS
    fail validation; declare the window on the optimizer instead.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • flax: flax learners no longer honor ACCUMULATE_GRADIENTS;
    wrap the tx in optax.MultiSteps(every_k_schedule=k) instead.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • keras: keras learners no longer honor ACCUMULATE_GRADIENTS;
    declare gradient_accumulation_steps on the optimizer instead.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • keras: UserDefinedLearner no longer carries CLIP or the mixed
    precision fields, and LearnerIntermediate.flow carries OptimizerSegment
    instances instead of 6-tuples; torch consumers migrate to the
    TorchLearnerBuilder class family.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • feat(flax): generate NNX learners from the shared learner DSL

FlaxLearnerBuilder and FlaxLearnerIntermediate emit a module-level
training step with one nnx.value_and_grad per optimizer segment (the
segment's owned modules as the differentiated container, other models
as plain arguments), a manual gradient-accumulation State gated by the
host-side update(step) flag, and nnx.view-based deterministic inference.
The YAML OPTIMIZER pattern builds flax.nnx.Optimizer directly; the
builder appends the owned-module container and a wrt=Param default, and
rewrites the learning-rate-carrying factory with
optax.inject_hyperparams(static_args=...) so the generated step reports
the applied rate through an auxiliary output.
structcast_model.flax.optimizers ships get_learning_rate (optax
tree_get over the injected hyperparams, NaN when absent) and
no_weight_decay_mask (path-regex mask for optax). Generation-time
guards reject read-before-store segment flows and container-name
collisions; the aux tuple carries only values that leave the closure,
and flow_functions exposes the torch-compatible compile seam.
Emitted torch learner code stays byte-identical (statement_names moved

  • flax: UserDefinedLearner no longer carries CLIP or the mixed
    precision fields, and LearnerIntermediate.flow carries OptimizerSegment
    instances instead of 6-tuples; torch consumers migrate to the
    TorchLearnerBuilder class family.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • feat(flax): generate NNX learners from the shared learner DSL

FlaxLearnerBuilder and FlaxLearnerIntermediate emit a module-level
training step with one nnx.value_and_grad per optimizer segment (the
segment's owned modules as the differentiated container, other models
as plain arguments), a manual gradient-accumulation State gated by the
host-side update(step) flag, and nnx.view-based deterministic inference.
The YAML OPTIMIZER pattern builds flax.nnx.Optimizer directly; the
builder appends the owned-module container and a wrt=Param default, and
rewrites the learning-rate-carrying factory with
optax.inject_hyperparams(static_args=...) so the generated step reports
the applied rate through an auxiliary output.
structcast_model.flax.optimizers ships get_learning_rate (optax
tree_get over the injected hyperparams, NaN when absent) and
no_weight_decay_mask (path-regex mask for optax). Generation-time
guards reject read-before-store segment flows and container-name
collisions; the aux tuple carries only values that leave the closure,
and flow_functions exposes the torch-compatible compile seam.
Emitted torch learner code stays byte-identical (statement_names moved

  • flax: DistributedStrategy drops the grad_scaler_creator
    member; custom strategies relying on it construct their scaler inside
    wrap/compile instead, and generated learners no longer accept
    grad_scaler_creator.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • refactor(flax,builders): route contract warnings through logging

The generation-time no-learning-rate notice and the resume drift
notices move from warnings.warn to the house logger pattern
(getLogger(name), lazy %-style args); flax/trainer names its
module logger _logger because restore_training_state's public
signature already takes a Logger parameter named logger. The tests pin
the channel through caplog, keeping the quiet-path assertions scoped
to structcast_model loggers, and the jax donation-warning checks stay
on the warnings machinery they actually test.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • refactor(flax): publish ShardedDataset and flatten the flax CLI bindings

The batch-sharding dataset adapter moves from a cmd_flax private into
structcast_model.flax.trainer as public API (unit-tested for length
passthrough, per-epoch re-iteration, and event-protocol visibility),
the CLI consumes the flax package through one lazy scm_flax binding
with all thirteen call sites flattened, and restore_training_state
logs the --start-epoch override at INFO instead of printing.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • builders: builder modules are now
    structcast_model.builders.{base,flax,keras,torch}.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • loggers: the logger modules moved from
    structcast_model.torch.{logger,mlflow_logger,wandb_logger} to
    structcast_model.loggers.{base,mlflow,wandb}.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • commands: create model/create learner no longer accept -c for
    --classname (use -n) and create model no longer accepts -s for
    --sublayer (use the long flag).

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

💥 Breaking Changes

  • builders: drop the framework suffixes from the builder modules (315031f)
  • builders: pass flax learner state by name and empty the module scope (3134bfc)
  • cfg: drop cfg/keras/others/compile_default.yaml (a38bb14)
  • commands: reserve -c and -s for --compile and --shape (1a89254)
  • flax: default --compile to off and drop the none spelling (a7628e8)
  • keras: add --compile to train and stop compiling unconditionally (920db62)
  • keras: take the batch by name through the adapter boundary (5f02922)
  • loggers: move the torch loggers into a framework-agnostic package (c7e6401)
  • schema: move ACCUMULATE_GRADIENTS onto the torch learner schema (52b0e28)
  • ship gradient checkpointing, EMA and tensor parallelism across the frameworks (ad77f87)
  • trainer: flow_functions joins the learner protocol (43b2dce)
  • trainer: the learner owns the training counters ([8560d1b](https...
Read more

v5.0.0

Choose a tag to compare

@github-actions github-actions released this 16 Aug 17:25

5.0.0 (2026-08-16)

⚠ BREAKING CHANGES

  • base-trainer: hand-written learners must expose optimizer_models;
    a learner without it raises AttributeError when training state is
    saved at epoch end or restored on resume. Generated learners are
    unaffected.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

👷 Build

  • deps: upgrade locked dependencies (95b94dc)
  • mypy: drop the structcast override and the python_version pin (cfd3ba9), closes #26
  • mypy: resolve tests against src and enable dependency types (eb06700), closes #25

💎 Features

  • base-trainer: require optimizer_models on the Learner protocol (cd7060a)

🔧 Fixes

  • protocols: import TensorInitializer protocols from typing_extensions (1e57dab)
  • torch: convert incoming criteria values to the buffer device (30bcc64)
  • torch: resolve criteria buffers live instead of caching them (f32dfdd)

🔨 Refactor

  • align src annotations with real dependency types (b691886)
  • instantiate initializers and compile_kw directly in the _assemble_learner call (30d4af0)

🚨 Tests

  • mypy: add protocol-conformance canary (f5b563c), closes #25

v4.0.0

Choose a tag to compare

@github-actions github-actions released this 15 Aug 20:16

4.0.0 (2026-08-15)

⚠ BREAKING CHANGES

  • base-trainer: lifecycle events no longer pass **models keyword
    arguments; every handler signature is on_*(info) and
    on_best(info, best), with models read from info.models. on_best's
    criterion parameter tightens from BestCriterion[Any] to
    BestCriterion[ModelT].

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • torch: --resume must match the active --logger; resuming from the
    other service's reference (e.g. --logger wandb with runs:/...) now fails
    with a ValueError. Download the artifact and resume from a local path
    instead.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

📔 Docs

  • reference: correct CFG and TYPE sublayer semantics (fdb72be)

🔧 Fixes

  • base-trainer: cache the provider step counts on first read (25f4c2a)

🔨 Refactor

  • base-trainer: move models onto the info object (38e05dd)
  • builders: move resolver utilities (c42f5a1)
  • torch: move training-state fetching into the loggers (a4daee6)

🚨 Tests

  • use canonical cfg configs and move fixtures under tests/fixtures (c58a5fa)

v3.0.0

Choose a tag to compare

@github-actions github-actions released this 15 Aug 11:41

3.0.0 (2026-08-15)

⚠ BREAKING CHANGES

  • torch: TorchTrainer.no_sync, _unwrap_ddp, and _get_state_dict are
    gone; TrainingStateSaver and TorchBestCriterion.from_criteria require a
    strategy and accept a None logger; interrupt-time saving is removed.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • builders: generated learner scripts changed shape (flow functions,
    sync gates, grad_scaler_creator); MIXED_PRECISION with a non-float16
    MIXED_PRECISION_TYPE is now a SpecError; bf16 learners expose empty
    grad_scalers.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • torch: TorchLearnerFactory is gone and the loggers import from new
    module paths.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • base-trainer: BaseTrainer requires data= at construction and
    SimpleDataProvider takes keyword arguments only.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • torch: the Timm* classes are no longer part of
    structcast_model.torch.trainer, and train no longer logs timm_version.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • base-trainer: objects implementing Learner must expose optimizers and
    learning_rates properties.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • cli,builders: the backward CLI vocabulary, BACKWARDS template key,
    cfg/torch/backwards/ directory and create_with_scheduler cfg patterns are gone.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • torch: create_with_scheduler and the scheduler registration side
    channel are removed; TorchTracker.reset and the wrapper's set_dataset_epoch/
    set_dataloader_epoch methods are replaced.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • base-trainer: GLOBAL_CALLBACKS, callbacks_session, NamedCallbackList and
    the Callbacks dataclass are removed; Backward is renamed Learner; fit() no
    longer accepts datasets.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

  • builders: unannotated dummy inputs are now bfloat16, not float32

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com

💥 Breaking Changes

  • base-trainer: require optimizers and learning_rates on the Learner protocol (e48ce25)
  • base-trainer: require the data provider and keyword-only SimpleDataProvider (ad6aebc)
  • base-trainer: restore runtime-checkable protocols via typing_extensions (d711c79)
  • base-trainer: route callbacks by protocol and rename Backward to Learner (bd69016)
  • builders: bind learner steps directly, dropping forward_* indirection (58b4d7b)
  • builders: generate strategy-aware learners with flow functions and sync gates (4429202)
  • builders: generated steps become class methods importing package helpers (a20880e)
  • cli,builders: cascade Learner rename and rewire the train command (c5f2b59)
  • commands: let the configuration decide structured output; compile in place (cd50ead)
  • example: attention and RoPE live in the configuration; Transformer becomes SmallLanguageModel (af84a9c)
  • torch: assemble training through the distributed strategy and add resume (274f49c)
  • torch: move timm.data integrations to examples and make the CLI timm-agnostic (6215eca)
  • torch: move torch layer to protocol-routed Learner design (fb7d44d)
  • torch: split loggers behind a Logger protocol and revert the learner factory (89a402a)
  • trainer: own step counts on the DataProvider and rework callback wiring (25ddffc)

👷 Build

  • docker: add a GPU training image for DGX validation runs (0df26cc)

📦 Other

  • add anysearch skill (179186c)
  • add devcontainer and agent skills (e8e79fb)
  • refresh uv.lock for structcast 2.0 (f8ffec3)
  • remove anysearch skill (bd6894c)
  • update .gitignore to exclude Claude Code settings and symlink (7f9c490)
  • update devcontainer configuration by removing unused variables and scripts (e0ca6cf)

📔 Docs

  • add domain glossary and training-loop redesign ADR (ab9ab52)
  • Add StructCast-Model Reference documentation (8c444cc)
  • adr: record distributed strategy, sync gating, and checkpoint decisions (6e739e5)
  • align distributed training claims with the strategy design (d4a28e8)
  • align guides with setter sync_gate, strategy compile, and NullLogger; drop redundant update_models (2eca54e)
  • align the docs with the current public API (268ac76)
  • references: bound the vision run-to-run spread and retract a compile regression (7176ae9)
  • references: complete the vision strategy matrix (6919f0a)
  • references: explain the ConvNeXt V2-B per-epoch cost and the compile relaunch (4ebfd79)
  • references: note the vision matrix runs a single seed (4b3deee)
  • references: record per-block FSDP2 validation on H200 (27c75b5)
  • references: record strategy comparison runs on H200 (b2520cc)
  • references: record the completed ViT-B strategy triplet (7beed4e)
  • references: replace concrete host paths with placeholders (9fb54a9)
  • references: restate the micro-benchmark method instead of keeping the scripts (d517f04)
  • references: state the vision augmentation recipe (bdd1056)
  • rewrite README and reference docs for the Learner design (b7f08c0)
  • update worktree guidelines for devcontainer compatibility (e97ac03)

📝 Examples

  • add simple training tutorial (76bf107)
  • torch: decoder-only transformer LM on Tiny Shakespeare (0148295)
  • torch: ViT-B/16 configuration bit-exact against timm (d570dbc)

💎 Features

  • builders: add INPUT_SHAPES tensor specification with dtype and initializer support (323c664)
  • commands: compile per shard block and s...
Read more

v2.0.0

Choose a tag to compare

@github-actions github-actions released this 12 Apr 05:20

2.0.0 (2026-04-12)

💥 Breaking Changes

  • restructure backward template schema for multi-optimizer GAN training support (26f0dd2)

v1.5.0

Choose a tag to compare

@github-actions github-actions released this 09 Apr 09:21

1.5.0 (2026-04-09)

👷 Build

  • add all-cpu dependency for unified installation of JAX, Torch, and TensorFlow support (de187f0)
  • add support for additional structcast-model configurations for Keras and CUDA (ba20716)
  • update Keras dependencies for Torch integration and enhance all-cpu configuration (50e0c81)

📦 Other

  • correct flow structure and output definitions in ConvNeXtV2 YAML configurations (6cf1284)
  • reorganize configuration files under cfg/torch/ directory (dab047f)
  • update Block flow to use string expression for addition operation (398b0e4)

🦊 CI/CD

  • update extras in tox.ini to replace 'torch-cpu' with 'all-cpu' (2cc6c0b)

📔 Docs

  • add clarification on avoiding unnecessary noqa and type ignore comments (264805a)
  • add Schema Reference section to README.md (3e686b3)
  • update README files to reflect multi-framework support for PyTorch, Flax, and Keras (499cdf9)

💎 Features

  • add class method to get class instance with rngs and training parameters (99397b0)
  • add command to measure average inference time of Flax models (7aeb480)
  • add functions to retrieve available JAX devices and specific device by string (a1d7e38)
  • add get_keras_device function to retrieve available Keras devices (164825d)
  • add inference time measurement command and compile option for PyTorch models (c1881c6)
  • add inference time measurement command for Keras models with compile options (14a8ae3)
  • add Keras module and Global Response Normalization layer implementation (59b9711)
  • add keras to module exports and import structure (9daba40)
  • add KerasBuilder, FlaxBuilder, CLI commands, and ConvNeXtV2 YAML configs (ae3cecc)
  • add matmul_precision option and warmup runs for inference time measurement (4b2517e)
  • add trainer helpers for Keras models with input creation functions (737a11c)
  • add warmup runs for inference time measurement (df24075)
  • implement Global Response Normalization (GRN) layer in Flax (548d8ea)

🔧 Fixes

  • add training parameter to FlaxLayerIntermediate constructor and call method (662ee94)
  • add TypeAlias annotation for _Intermediate in test_intermediate_get_scripts (c7b8626)
  • address code review - list type annotation, drop_path RNG seed, and shape comment (401ec89)
  • correct instantiation method for compile pattern in measure_inference_time function (49474f7)
  • correct variable name from 'warnup_runs' to 'warmup_runs' in cmd_flax.py, cmd_keras.py, and cmd_torch.py (13172f0)
  • expose get_jax_device and get_jax_devices in module exports (67d8665)
  • expose GlobalResponseNorm in module exports (fde565b)
  • expose GlobalResponseNorm in module exports (efef061)
  • update compile pattern check to ensure it's not None before compilation (3d0bb8e)
  • update default imports to include flax.nnx module (9089c81)
  • update dockerfile to use all-cpu dependency for consistent environment setup (81c34ab)
  • update GlobalResponseNormalization to GlobalResponseNorm in ConvNeXtV2.yaml (1813014)
  • update GlobalResponseNormalization to GlobalResponseNorm in ConvNeXtV2.yaml (f8852ee)
  • update import for GlobalResponseNormalization in layers module (f9f9ea1)
  • update jax import handling and instantiate compile pattern in measure_inference_time function (60cedc4)
  • update keras dependency to version 3.13.2 in pyproject.toml (c78d40d)
  • update model compilation to use instantiator for compile pattern (0a9e4b9)

🔨 Refactor

  • remove unused Add, Multiply, ReduceSum, and ScaleIdentity layers (04c14d0)
  • remove unused Flax layer classes and update module exports (52d7b96)
  • rename instantiate function to instantiate_object for clarity (29791c1)
  • replace _instantiate with instantiate in cmd_torch and update utils with detailed docstrings (dd60a05)
  • replace DropPath layer with Dropout layer in ConvNeXtV2.yaml (7a68465)
  • simplify _forward_flow method in KerasLayerIntermediate (fcf3863)
  • simplify import statements and improve docstring formatting in flax_builder.py (3982f78)
  • simplify training parameter handling in Flax and Keras model call methods (449ae01)
  • streamline GlobalResponseNorm class by removing redundant imports and simplifying parameter initialization (087e514)
  • streamline import statements and improve formatting in keras_builder.py (4a555fb)
  • update configuration paths for ConvNeXtV2 models to include 'torch' directory (b68b762)
  • update configuration paths for Flax and Keras ConvNeXt models to include respective directories (a1d66ec)
  • update ConvNeXtV2.yaml structure and layer configurations (a745980)
  • update ConvNeXtV2.yaml to enhance layer configurations and streamline flow definitions (2a97154)
  • update type ...
Read more

v1.4.0

Choose a tag to compare

@github-actions github-actions released this 01 Apr 11:19

1.4.0 (2026-04-01)

👷 Build

  • upgrade package dependencies (63590e9)

📦 Other

  • add data_file configuration for pytest coverage (2b8d14b)

💎 Features

  • add trainer pattern option for model training configuration (af8da80)

🔧 Fixes

  • correct elapsed_time calculation in training and validation steps (857a637)
  • correct forward method input handling in TorchLayerIntermediate (29417b9)
  • reorder output attribute check in _get_module_outputs function (7e1c838)

v1.3.0

Choose a tag to compare

@github-actions github-actions released this 28 Mar 03:48

1.3.0 (2026-03-28)

👷 Build

  • add mlflow and flops as extra dependencies in Dockerfile (7fa3847)

🦊 CI/CD

  • add coverage configuration for testing with multiprocessing support (3d2348d)
  • add mlflow and flops dependencies to tox configuration (ab087be)
  • update tox command to run without parallel execution (85c0036)

💎 Features

  • add initializer patterns option for model instantiation in train function (75ec398)
  • add options for training and validation step patterns in train function (eeb8cdb)

🔧 Fixes

  • add runtime_checkable decorator to protocol classes for enhanced type checking (d4bb823)

🔨 Refactor

  • streamline training and validation step instantiation in train function (606cca4)

v1.2.0

Choose a tag to compare

@github-actions github-actions released this 17 Mar 09:39

1.2.0 (2026-03-17)

🦊 CI/CD

  • remove unused 'flops' extra from tox configuration (ab8223a)

📔 Docs

  • add parallel check command to README (347cc3c)
  • add warning about SyncBatchNorm for multi-GPU training with DDP (e0471b7)
  • enhance documentation for distributed training support with torchrun (13aea9d)

💎 Features

  • enhance BestCriterion and TorchTracker for improved tracking and callback functionality (6692427)
  • enhance TimmDataLoaderWrapper with distributed support and dataset management (a90ebff)
  • refactor training logic and enhance distributed training support (b8e8a74)

🔧 Fixes

  • enhance TimmDataLoaderWrapper for distributed training support with additional parameters (305ae08)
  • fix the bugs of returning incorrect update code script in TorchBackwardIntermediate (89dffbe)
  • update command-line argument flags for consistency in training options (35ea5a9)

✨ Style

  • update noqa comments in train function for improved linting compliance (f14806e)