configgle🤭

Type-safe hierarchical experiment configuration using pure Python dataclass factories and dependency injection.

Quick Start

# Mac:
#   # Required for quick install.
#   brew install uv

# Ubuntu/Debian:
#   # Required for quick install.
#   sudo apt-get install -y curl
#   curl -LsSf https://astral.sh/uv/install.sh | sh

uv add configgle

# Alternatively: python -m pip install configgle

Hierarchical experiment configuration using pure Python dataclasses with typed factory methods, covariant protocols, inheritance support, and tooling for pretty printing, autodecorating, updating, and semi-deep copying.

Example

from configgle import Fig


class Model:
    class Config(Fig):
        channels_in: int = 256
        num_layers: int = 4

    def __init__(self, config: Config):
        self.config = config


# Create and modify config
cfg = Model.Config()
cfg.channels_in = 512

# Instantiate the parent class
model = cfg.make()
print(model.config)
assert isinstance(model, Model)

Configs are plain mutable dataclasses, so experiments are just functions that tweak a baseline:

def exp000() -> Model.Config:
    return Model.Config()


def exp001() -> Model.Config:
    cfg = exp000()
    cfg.channels_in = 512
    cfg.num_layers = 8
    return cfg

Or use @autofig to auto-generate the Config from __init__:

from configgle import autofig
from torch import nn


@autofig
class Model(nn.Module):
    def __init__(self, channels_in: int = 256, num_layers: int = 4):
        super().__init__()
        self.channels_in = channels_in
        self.num_layers = num_layers


# Config is auto-generated from __init__ signature
model = Model.Config(channels_in=512).make()
print(model.channels_in)  # 512

Features

Type-safe make()

tl;dr: Both ty and basedpyright are first-class supported. Unfortunately neither is perfect:

Details:

When Config is defined as a nested class, MakerMeta.__get__ uses the descriptor protocol to infer the parent class automatically. The return type of __get__ is Intersection[type[Config], type[Makeable[Parent]]], so make() knows the exact return type with zero annotation effort:

class Model:
    class Config(Fig):
        channels_in: int = 256

    def __init__(self, config: Config):
        self.channels_in = config.channels_in


model = Model.Config(channels_in=512).make()  # inferred as Model

Type checkers that support Intersection (like ty) resolve this fully -- bare Fig is all you need. For type checkers that don't yet support Intersection (like basedpyright), parameterize with the parent class name to give the checker the same information explicitly:

class Model:
    class Config(Fig["Model"]):  # explicit type parameter only for basedpyright
        channels_in: int = 256

    def __init__(self, config: Config):
        self.channels_in = config.channels_in


model: Model = Model.Config(channels_in=512).make()  # returns Model, not object

Without ["Model"], non-ty checkers fall back to Any (so attribute access works without typecheck suppressions).

ty gets full inference from Intersection -- bare Fig and inherited configs just work. basedpyright doesn't support Intersection yet, so it needs explicit Fig["Parent"] and Makes["Child"] annotations. ty honors class decorator return types (#143, fixed in 0.0.49), so @autofig-decorated classes resolve .Config with no suppression on both checkers. When Intersection lands in the type spec, Makes becomes unnecessary and both checkers will infer everything from bare Fig.

Requires ty>=0.0.60. Several behaviors configgle relies on were fixed upstream rather than worked around here -- see docs/ty_missing_features.md for the current limitations and their provenance.

Inheritance with Makes (only for basedpyright)

When a child class inherits a parent's Config, the make() return type would normally be the parent. Use Makes to re-bind it (again, only needed for basedpyright):

from configgle import Makes


class Animal:
    class Config(Fig["Animal"]):
        name: str = "animal"

    def __init__(self, config: Config):
        self.config = config
        self.name = config.name


class Dog(Animal):
    class Config(Makes["Dog"], Animal.Config):
        breed: str = "mutt"

    def __init__(self, config: Config):
        super().__init__(config)
        self.breed = config.breed


dog: Dog = Dog.Config(name="Rex", breed="labrador").make()  # returns Dog, not Animal

Makes contributes nothing to the MRO at runtime -- it exists purely for the type checker (see the type checker table above). When Intersection lands, Makes becomes unnecessary.

Covariant Makeable protocol

Makeable[T] is a covariant protocol satisfied by any Fig, InlineConfig, or custom class exposing make(), finalize(), update(), plus the _finalized and parent_class members (Maker and InlineConfig provide all five). Because it's covariant, Makeable[Dog] is assignable to Makeable[Animal]:

from configgle import Makeable


def train(config: Makeable[Animal]) -> Animal:
    return config.make()


# All valid:
train(Animal.Config())
train(Dog.Config(breed="poodle"))

This makes it easy to write functions that accept any config for a class hierarchy without losing type information.

Nested config finalization -- pre / super / post

Override finalize() to compute derived fields. super().finalize() cascades into the child configs, so it splits the method into a pre phase (before children finalize -- push values down) and a post phase (after -- derive values up):

from configgle import Configurable  # Just an alias to Makeable.
from dataclasses import field


class Encoder:
    class Config(Fig):
        c_in: int = 256
        mlp: Configurable[nn.Module] = field(default_factory=MLP.Config)

        def finalize(self) -> Self:
            self.mlp.c_in = self.c_in  # pre: push down into the child
            self = super().finalize()  # children finalize here
            self.out = self.mlp.out  # post: derive up from the child
            return self

Inject into a child before super() (so it finalizes with the value); derive from a child after (so you read its finalized result). Pushdown is the common case, so super() is usually last -- but it need not be.

finalize() mutates in place; the copy that protects the original happens once at the make() / pprint boundary (copy_tree().finalize()), so a config is finalized exactly once on a fresh tree (never re-finalized) and the config passed to make() is left untouched.

update() for bulk mutation

Configs support bulk updates from another config or keyword arguments:

cfg = Model.Config(channels_in=256)
cfg.update(channels_in=512, num_layers=8)

# Or copy from another config (kwargs take precedence):
cfg.update(other_cfg, num_layers=12)

InlineConfig / PartialConfig

InlineConfig wraps an arbitrary callable and its arguments into a config object with deferred execution. Use it for classes where all constructor arguments are known at config time:

from configgle import InlineConfig
import torch.nn as nn

cfg = InlineConfig(nn.Linear, in_features=256, out_features=128, bias=False)
cfg.out_features = 64  # attribute-style access to kwargs
layer = cfg.make()  # calls nn.Linear(in_features=256, out_features=64, bias=False)
y = layer(x)  # use the constructed module

PartialConfig is shorthand for InlineConfig(functools.partial, fn, ...) -- use it for functions where some arguments aren't known at config time:

from configgle import PartialConfig
import torch.nn.functional as F

cfg = PartialConfig(F.cross_entropy, label_smoothing=0.1)
loss_fn = cfg.make()  # returns functools.partial(F.cross_entropy, label_smoothing=0.1)
loss = loss_fn(
    logits, targets
)  # calls F.cross_entropy(logits, targets, label_smoothing=0.1)

Nested configs in args/kwargs are finalized and make()-d recursively, so both compose naturally with Fig configs.

copy_tree()

copy_tree() is a "semi-deep" copy: nested configs and mutable containers holding configs are duplicated, while leaf values (primitives, tensors, loggers) are aliased. make() and pprint apply it before finalizing so the source config stays pristine. Reach for it directly to finalize a copy without touching the source:

finalized = cfg.copy_tree().finalize()  # cfg unchanged

traverse()

traverse(root, cls) walks the same shapes copy_tree walks and yields a Match for every node that is an instance of cls: the node, its dotted path (blocks[0].proj, extras['aux']), and a replace(new) handle that writes into the parent slot -- a list index, a dict key, a tuple position, or an attribute. A shared node is yielded once. With recurse=True, matches nested inside a match are yielded too, parents first.

from configgle import traverse

for match in traverse(cfg, Linear.Config):
    match.replace(QuantizedLinear.Config(**vars(match.config)))

pprint / pformat

Config-aware pretty printing that hides default values, auto-finalizes before printing, and scrubs memory addresses:

from configgle import Configurable, Fig, pformat


class MLP:
    class Config(Fig):
        c_in: int = 256
        c_out: int = 256
        num_layers: int = 2
        dropout: float = 0.1
        use_bias: bool = True

    def __init__(self, config: Config): ...


class Model:
    class Config(Fig):
        channels_in: int = 256
        num_layers: int = 4
        mlp: Configurable[nn.Module] = field(default_factory=MLP.Config)
        output_mlp: Configurable[nn.Module] = field(default_factory=MLP.Config)

    def __init__(self, config: Config): ...


def exp001():
    cfg = Model.Config()
    cfg.channels_in = 512
    cfg.num_layers = 12
    cfg.mlp.c_in = 512
    cfg.mlp.c_out = 1024
    cfg.mlp.num_layers = 4
    cfg.mlp.dropout = 0.2
    cfg.mlp.use_bias = False
    cfg.output_mlp.c_in = 1024
    cfg.output_mlp.c_out = 256
    cfg.output_mlp.dropout = 0.3
    return cfg


print(pformat(exp001(), continuation_pipe=0))
# Model.Config(
#    channels_in=512,
#    num_layers=12,
#    mlp=MLP.Config(
#    │       c_in=512,
#    │       c_out=1_024,
#    │       num_layers=4,
#    │       dropout=0.2,
#    │       use_bias=False
#    ),
#    output_mlp=MLP.Config(c_in=1_024, dropout=0.3)
# )

Default values are hidden, continuation pipes show where nested blocks belong, large numbers get underscores (1_024), and short sub-configs collapse onto one line. pformat and pprint are also available as methods on any Fig config:

cfg = exp001()
cfg.pprint()  # prints to stdout
s = cfg.pformat()  # returns string

serialize() / deserialize()

serialize() returns a tree of plain Python containers (dict, list, str, int, float, bool, None), not a string, so the caller picks the transport:

import json, yaml

tree = cfg.serialize()  # plain dict/list/primitives

json_text = json.dumps(tree, indent=2)
yaml_text = yaml.safe_dump(tree, sort_keys=False)

cfg = Model.Config.deserialize(yaml.safe_load(yaml_text))  # a real Model.Config
model = cfg.make()

yaml.safe_dump refuses any non-plain Python object, so a clean dump means the tree contains nothing else. The same tree works with msgpack, a W&B run record, or a field in a larger payload.

The round trip preserves what a plain dict loses: nested config classes, polymorphic Makeable slots, tuples vs lists, DAG identity (a sub-config shared by two fields stays shared), and cycles. The wire format is jsonpickle's py/* tag vocabulary, so the tree is legible to anyone who knows jsonpickle. serialize() does not finalize, so the loaded config is raw and ready for finalize() / make(). Leaves JSON cannot represent natively (tensors, arrays) take a hooks={type: (encode, decode)} map.

Deserialization imports the modules named in the payload, so treat a serialized config like pickle: load only trusted data.

CLI overrides

apply_overrides edits a config from PATH=VALUE strings. Dotted paths reach into nested configs, every hop is checked against the node's declared fields (so a typo raises instead of silently creating an attribute), and the value is cast to the field's declared type:

from configgle import apply_overrides

cfg = Model.Config()
apply_overrides(cfg, ["channels_in=512", "mlp.dropout=0.2"])

configgle/launch.py wires that to argparse, so any factory function returning a config is runnable as-is:

# myproject/experiments.py
def baseline() -> Makeable[Trainer]:
    return Trainer.Config()

python -m configgle myproject.experiments.baseline --override mlp.dropout=0.2

The launcher is deliberately small -- it exists to make --override usable out of the box and to show the pattern. A real project usually wants its own entry point (hardware logging, distributed setup, run naming); build it on resolve_config and apply_overrides rather than copying the file.

Dataclass base

Dataclass provides the auto-dataclass metaclass (with the same opinionated defaults as Fig: kw_only=True, slots=True, etc.) but without Maker or make(). Use it for plain data objects that don't need the factory pattern.

@autofig for zero-boilerplate configs

When you don't need a hand-written Config, @autofig generates one from __init__ (see Example above).

Pickling and cloudpickle

Configs are fully compatible with pickle and cloudpickle, including the parent class reference. This is important for distributed workflows (e.g., sending configs across processes):

import cloudpickle, pickle

cfg = Model.Config(channels_in=512)
cfg_ = pickle.loads(cloudpickle.dumps(cfg))
model = cfg_.make()  # parent_class is preserved

Comparison

✅ = yes, 🟡 = partial/caveat, ❌ = no, 🚫 = intentionally no.

Corrections welcome -- open a PR.

(🚫 is used only where a project states the reason in writing: configgle here, and AXLearn and torchtitan on the YAML row.)

Lineage

The nested-Config shape is not new. Two production training codebases use it, and one cites the other:

• AXLearn (Apple, 2023). Its ML API Style sets the rules configgle follows: every layer has a Config member class, a composite layer's config holds its children's configs as fields, and a child's input_dim is set by the parent. axlearn/common/config.py supplies Configurable.Config.instantiate(), default_config(), and config_for_function / config_for_class for signature-derived configs.
• torchtitan (Meta, 2026-02-23). PR #2386 replaced its TOML job config with a Configurable base whose nested @dataclass(kw_only=True, slots=True) class Config builds the owner via build(). The author's note credits AXLearn's style doc. Model configs then grew methods -- get_nparams_and_flops(model, seq_len) -- which is the same move as a finalize() override: computation that belongs with the config, not the module.

configgle was written without knowledge of either and released 2026-02-02, three weeks before torchtitan's refactor merged. It adds a finalize() cascade for derived fields (AXLearn has validators; torchtitan's update_from_config carries a TODO calling itself an encapsulation violation), pprint as a diff against class defaults, LateBound for references across the built tree, and ships as a library with no framework attached. Both appear in the comparison below.

See also

Sibling projects in the rekursiv-ai family:

• sagent — The self-mutating multi-provider coding-agent CLI and typed Python library.
• trackinizer — Centralized agent database for tracking inquiries, work, and the evidence behind conclusions.
• wesearch — Web search, resilient page fetch, and scholarly-paper lookup without a browser stack.
• madcatter — Rich-based Markdown renderer for the terminal; ships the mdcat CLI.
• priml — Composable PyTorch building blocks: models, optimizers, losses, and a step-based training loop.
• copybarista — Bidirectional source sync for publishing OSS-ready trees from a monorepo.

Citing

If you find our work useful, please consider citing:

@misc{rekursivai2026configgle,
      title={Configgle - Type-safe hierarchical experiment configuration using pure Python dataclass factories and dependency injection.},
      author={Joshua V. Dillon},
      year={2026},
      howpublished={Github},
      url={https://github.com/rekursiv-ai/configgle},
}