Skip to content

v6.0.0

Choose a tag to compare

@github-actions github-actions released this 25 Sep 09:29
· 5 commits to main since this release

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)

👷 Build

  • docker: derive the interpreter sync loop from PYTHON_VERSIONS (8de646a)
  • docker: stop rebuilding the CI image for README and tox.ini edits (b124bdf)

📦 Other

  • devcontainer: enhance setup for Antigravity CLI and Herdr integration (2e51d4d)
  • devcontainer: streamline Claude plugin setup by removing command check (7c0befa)
  • Dockerfile: add python3-dev to the list of installed packages (9291446)
  • ignore .worktrees/ as AGENTS.md already assumes (d93ec00)
  • plugins: add new plugins for caveman and OpenAI Codex to the marketplace (c13c702)
  • tear down previous herdr crew before respawn (7925dc9)

🦊 CI/CD

  • run each tox environment as its own job and test dev through its pull request (043a841)

📔 Docs

  • adr: correct the recorded reason a sharded torch model refuses an EMA (4c0af79), closes #33
  • adr: keep the keras time measurement inside ADR-0024 (9289db8)
  • adr: record ADR-0024, one --compile definition on every command (381ded6)
  • adr: record how flax drives DynamicScale from outside value_and_grad (6928ca9)
  • adr: record learner-owned training counters and the post-step protocol (355aff9)
  • adr: record per-backend native accumulation gating (357704b)
  • adr: record the checkpointing, EMA and tensor-parallel contracts (9b64bae)
  • adr: record the framework-agnostic loggers package and builders rename (8d426d3)
  • adr: record the named-state generated learner contract (f2a7dd3)
  • adr: record the shared CLI declaration layer and its placement rules (b075273)
  • adr: renumber the BatchNorm ADR to 0009 to resolve a number collision (fde3728)
  • adr: simplify the gradient_steps contract to an outermost check (827049a)
  • agents: point at .releaserc.json, the file that exists (3303484)
  • align CONTEXT and ADRs with the current code (42a7ff8)
  • bring the tutorials and agent guides in line with ADR-0024 (13895a8)
  • builders: annotate the torch gate's intent semantics in generated code (67ab470)
  • builders: correct the keras counter-read cost comment (8dde614)
  • cfg: carry the ADR pointers' reasoning into the templates themselves (3a94659)
  • commands: make every CLI help string accurate and complete (5f0779f)
  • examples: rebuild the README cf68eb0 triplicated (1abfed8)
  • move source comments into a ledger under docs/ (45b2e2b)
  • readme: warn that a torch EMA is refused under FSDP2 and tensor parallel (18b8d56)
  • reference: correct the keras EMA parity claims and amend ADR-0021 (c78ddb2)
  • reference: document the flax loss scale and the slot it is saved in (70d6176)
  • references: report the H200 framework-parity and feature campaign (ea1b85a), closes #32
  • reference: state what the keras EMA is evaluated on and how its momentum converts (1b17313)
  • reference: teach the learner-owned counter protocol (90beb21)
  • reference: teach the per-backend accumulation window forms (17cfff7)
  • strip design-document references from docstrings (c7cd569)
  • the keras average rides the resume checkpoint, not the best-model artifact (cb4987a)

📝 Examples

  • bring flax and keras cfg and examples to torch parity (f90fa5b)
  • cyclegan: feed the shipped learners an unpaired loader and image pool (08564a9)
  • harden the data loaders and fold the flax schedules into the templates (b730242)
  • stream ImageNet from directory trees and parameterize flax precision (cf68eb0)
  • torch: align the hand-written learner with the CLI pipeline (c54dd74)

💎 Features

  • api: expose module-file public APIs flat on the package routers (7bd634c)
  • builders: qualified project imports, keras flow closures and reserved-name checks (e14e419)
  • cfg: parameterize dtype in the flax ConvNeXtV2 and VisionTransformer templates (c4cc509)
  • cfg: parameterize the showcase average and the classifier precision (84c77a6)
  • commands: cap GPU memory from the torch and flax CLIs (3a6bc9b)
  • commands: control the logging level from the root CLI (631ce8d)
  • flax: carry dtype and param_dtype on every generated model (e84a57a)
  • flax: learner generation and end-to-end training workflow (#30) (14915c2), closes #22 #22 #22 #22 #22 #22 #22 #22 #22 #22 #22 #22
  • flax: replace the manual accumulator with a parsed MultiSteps window (dcad073)
  • flax: scale a learner segment's loss with a DynamicScale (b4d25e7)
  • flax: type each mesh axis from its own flag (c664576)
  • keras: evaluate the optimizer's moving average in the inference step (4759596)
  • keras: gate update() from the optimizer's own accumulation counter (a501b86)
  • keras: keras training workflow across the tensorflow, jax, and torch backends (#31) (ac5432b), closes #22 #22 #22 #22 #22 #22 #22 #22 #22 #22 #22 #22
  • torch: convert BatchNorm to SyncBatchNorm in the multi-rank strategies (#28) (3e62685)
  • torch: expose the generated-learner helpers as public optimizer APIs (49712f5)
  • trainer: seed the learner counters on resume (4d79833)

🔧 Fixes

  • builders: hoist literal bind callables to module-level constants (f83d35a)
  • builders: make bind-lambda argument names deterministic (1973cd0)
  • builders: reserve the keras learner's init locals (99297eb)
  • builders: say why a sharded torch model cannot be averaged (b02c1ef)
  • builders: short-circuit the idle keras gate and pin the MultiSteps match (8042994)
  • cfg: align template defaults across the three frameworks (b22ce12)
  • cfg: align the flax ConvNeXtV2 learner with its twins and spell project addresses off the package (d6efa89)
  • cfg: bind clip_grad_norm to the timm clipping threshold (1d55e6a)
  • cfg: call the exact erf GELU from the flax model templates (dbf6404)
  • cfg: cast the keras image classifier logits to float32 before its criteria (cf26bdc)
  • cfg: drop whole samples in the flax ConvNeXt V2 stochastic depth (42e0d95)
  • cfg: give the keras ConvNeXt V2 learner the float32 cast its top-k needs (2f56391)
  • cfg: give the keras SmallLanguageModel the torch/flax attention (f6860cb)
  • cfg: guard the showcase accumulation window against a null parameter (ca19a2f)
  • commands: parse --training-mode-kwargs with the instantiator (7961ba3)
  • commands: read a YAML null as off in bool_or_path_or_dict_parser (2bf3122)
  • crews: add new worker and reviewer configurations with permission bypass (9583c94)
  • docker: put TensorFlow's CUDA wheel libraries on the loader path (cf34e7b)
  • examples: align the flax and keras image pipelines with the torch recipe (e340d9e)
  • examples: hide GPUs from TensorFlow in the keras data pipelines (f6b2f6d)
  • examples: seed keras ranks apart, resample flax images once, refuse single-channel crops (35de419)
  • examples: shuffle directory trees at the path level, not the pixels (b888232)
  • flax: fire the update gate on the step MultiSteps actually applies (587b772)
  • flax: forward a precision keyword only where it is inert at its default (81dce92)
  • flax: refuse tensor-parallel presets without a column or row rule (13e1c0f)
  • flax: type every mesh axis Auto unless model_axis_mode opts into explicit (0dff549)
  • keras: disable flash attention when a layer checkpoints on jax (43d1f32)
  • keras: make the EMA inference swap total, single-owner and unwindable (90b41fd)
  • keras: stop the tensorflow dp path halving every Loss twice (d195d7f)
  • keras: time the compiled forward under --compile (88a1e61)
  • layers: keep the GRN gradient finite on zero-norm channels (9cb6c82)
  • layers: zero-initialize flax and keras GRN scales (243e877)
  • loggers: fail clearly when writing run files without an active run (fb6499e)
  • torch: reject index-keyed optimizer state and gate partial resumes (e9b2449), closes #24
  • torch: split optimizer param groups that mix DTensor and plain tensors (ee6ece2)
  • torch: split param_names with the parameter groups (0489101)
  • worker: add permission bypass for Gemini websearch model (b80b110)

🚀 Performance

  • flax: keep two placed batches in flight ahead of the training step (70ef955)

🔨 Refactor

  • builders: drop dead branches, read positional dropout rates, widen the keras reserved names (f4a981e)
  • builders: wire flax precision from templates instead of layer signatures (45deb57)
  • commands: close the review findings on the declaration layer (772ccdc)
  • commands: declare every --compile through compile_option (6175d79)
  • commands: extract the shared CLI declaration layer (a8134d7)
  • flax: read the accumulation window back from the built optimizer (0d5fa12)
  • flax: replace Any with precise types in the flax runtime (8ea6f0d)
  • import TensorInitializer only from base_trainer (29fbc51)
  • keras: replace Any with precise types in the keras runtime (aac9a21)
  • replace Any with precise types in the framework-agnostic modules (4591a4e)
  • share one generic TensorInitializer protocol across frameworks (ad81119)
  • torch: fold the single-use helpers and resolve the DCP api once (07f7724)
  • torch: replace Any with precise types in the torch runtime (ca516ff)
  • trainer: align counter views and slim update_models (77da75f)
  • trust the flow_functions protocol member (7a8711f)

✨ Style

  • trim three comments and seed the keras crop like the flax one (71e0a23)

🚨 Tests

  • builders: pin the shipped templates to citation-free prose (1ea2739)
  • flax: drive the accumulation gate under the donation a run compiles with (b986962)
  • keras: build the swap probe gradients from the variable shape (fb84f2b)
  • keras: pin the logical-device probe and the EMA swap over a missing average (b9e80a5)
  • keras: run both image classifier templates under a bfloat16 policy (8e458e3)
  • loggers: exercise the wandb logger against the real SDK offline (dbb820a)
  • loggers: tear down the wandb singleton after each offline run (7d351bf)
  • narrow hoisted-binding expressions and annotate the strategy list for mypy (49fddf3)
  • share the counting learner and stepped info across the fakes (826087d)