dew.registry
Short names for the classes a run is made of, and the records that rebuild them.
A record names a class by its import path, {"class": "dew.nn.dit:SimpleDiT", "fields": {...}}, and a function the same way, {"function": "optax:adamw"}.
Rebuilding one imports the module and calls the class with its fields, each
converted to the type its annotation declares, so a record loads in a process
that imported nothing beforehand, and a class outside Dew needs nothing to be
recorded: its import path is its name. A record Dew writes carries the path,
so rebuilding it never depends on an alias, with one exception: a run’s own
record names its run class by its alias in runs, so a saved run reads back
wherever its class moves, and only that kind is consulted for it.
Where a person writes a record, in a config file or on the command line, the
class may be a short alias instead, {"class": "simple_dit"}. Each kind’s
aliases are a static table below (models, mixers, …) that maps a name to
a path and imports the class only when it is read. An unknown name or field
raises an error.
A run’s model is one such record, ModelConfig: the model’s class, the fields
the run gives it, the defaults it took and the wrappers it was made in. A
component built around parameters (an encoder, an autoencoder) records the view
it is rebuilt from (Recorded), and its class is found back by component.
| Name | Summary |
|---|---|
KINDS | Every kind, which a record’s alias is looked up across. |
Aliases | The short names of one kind, each mapped to the import path of its class. |
ModelConfig | A model’s class and the fields the run gives it. |
Record | A class as a record names it: its alias or import path and its constructor fields, {"class": "mla", "fields": {...}}. |
Recorded | A component a run records by the constructor view it is rebuilt from, not by its attributes: an encoder’s checkpoint and settings, an autoencoder’s module and normalization, never the parameters it was built around (to_record writes it as {"class", "fields"}, component finds its class). |
argument_records | fields as records of member’s parameters (parameters): each read against its parameter’s annotation and written back, so an alias becomes its import path, a value already built becomes its record, and an argument member does not take, or a value no record can carry (a lambda), is refused here rather than where the run is built. |
component | The class a component’s record, {"class": ..., "fields": {...}} (to_record, Recorded), names by an alias or its import path, one that is base or derives from it, and the record’s fields as written: the lookup from_record uses for a class record (_member). |
dtype_name | Return the name resolve_dtype accepts for a dtype, for a logged config. |
encoders | |
from_record | Return value as the class annotation names, from a record or already one. |
import_path | The path a record names a class or function by, module:Qualified.name. |
import_trusted | Trust the packages in trust for the rest of the process, and import every module of theirs that record names by an import path, so reading the record finds them imported (imported) and may construct their classes where a field declares no base class (_owned). |
imported | The class or function an import path names, importing its module. |
metrics | |
mixers | |
models | |
objectives | |
parameters | member’s named parameters, each with the function that declares it, and whether it takes any other keyword besides. |
presets | |
projectors | |
record_argument | A field typed annotation written as one JSON value on the command line, the record a run holds: a tuple of records as a list, [{"field": ...}, ...], and a mapping of class records as an object, {"sigma": {"class": "linear", "fields": {...}}}, since a flag per field cannot spell a collection whose length or keys the command line decides. |
record_fields | The record of a dataclass value’s constructor fields, each as owner declares it, at every level of a nested value alike. |
runs | |
schedules | |
solvers | |
to_record | Return value as the record from_record(annotation, ...) rebuilds it from. |
towers | |
trust_sources | Trust the sources names for the rest of the process (trusts_source). |
trusts_source | Whether the process trusts the source name, a Hub repository or a directory, to run its own code where a load reads it (trust_remote_code): as trust=(name,) and --trust name say where a run or a task loads (import_trusted), or a load asked to run it (trust_sources). |
with_dtype | fields, the model name builds from, computing in dtype. |
KINDS: tuple[Aliases, ...] = (models, presets, solvers, encoders, metrics, objectives, mixers, towers, projectors, schedules)Every kind, which a record’s alias is looked up across.
Aliases
Section titled “Aliases”class Aliases(kind: str, paths: Mapping[str, str], base: str | None = None)The short names of one kind, each mapped to the import path of its class.
models["simple_dit"] imports and returns SimpleDiT, as does
models["dew.nn.backbones.dit:SimpleDiT"]: the table is static, and a
class outside it, Dew’s or a user’s, is named by its path.
base-
The import path of the class every member derives from, or of the protocol they share, whose members are then classes of Dew’s or of a trusted package, or functions declared to return one (
_derives); None where the members share only an unnamed protocol. union: type[Built] | types.UnionType-
The union of the members’ types, for a tyro subcommand over the kind.
subcommands: Annotation-
The members’ union with each subcommand named as the kind names it (“data:text”), rather than by its class.
Aliases.label
Section titled “Aliases.label”def label(path: str) -> strThe alias of the class at import path, or its class name where
it has none, for a run’s human-readable name.
Aliases.name_of
Section titled “Aliases.name_of”def name_of(member: Importable) -> strThe name a record writes for member: its alias in this kind, else its import path.
Aliases.alias_of
Section titled “Aliases.alias_of”def alias_of(member: Importable) -> strThe alias of member, for a run’s human-readable name; KeyError
for a class this kind has no alias for.
Aliases.build
Section titled “Aliases.build”def build( name: str, record: Mapping[str, object] = NO_RECORD, /, **fields: Configured = {},) -> BuiltConstruct the member an alias or import path names, from a record, keyword fields, or both.
A field the member does not declare is an error. Fields come from JSON
as often as from code, so a field whose declared type is a value class
is built here from its record. For example,
models.build("m", attention={"heads": 8}) and
models.build("m", attention=Attention(heads=8)) build the same model.
Keyword fields override the record’s. The fields of a function, or of a
class that is not a dataclass, are its parameters, converted to their
annotations the same way.
Aliases.from_record
Section titled “Aliases.from_record”def from_record(record: Mapping[str, object]) -> BuiltConstruct the member a class record names, {"class": ..., "fields": {...}}.
ModelConfig
Section titled “ModelConfig”class ModelConfig( name: str = 'simple_dit', fields: JsonDict = dict(), defaults: JsonDict = dict(), wrappers: tuple[Wrapper, ...] = (),)A model’s class and the fields the run gives it.
name is an alias or an import path, held as the path. fields are the
class’s own fields, its compute and storage dtypes, attention kernel and
matmul precision included, which the command line sets one flag each
(RunConfig.cli); a recipe fills the ones it derives from its data in
build. defaults holds every other field the class defaults, as it
defaulted them when the run was first recorded, so the record builds the
same model after a default changes (arguments). wrappers are the
classes the model was wrapped in, in the order they were applied.
wrappers: tuple[Wrapper, ...]-
What wraps the built model, innermost first, which
buildapplies in order: a checkpoint’s input quantization, a bound LoRA (its factors are stored with the checkpoint variables), the quantized training a run wrapped it in.
ModelConfig.from_dict
Section titled “ModelConfig.from_dict”def from_dict(values: Mapping[str, object]) -> SelfRead back the record RunConfig.to_dict writes for this field.
ModelConfig.from_model
Section titled “ModelConfig.from_model”def from_model(model) -> SelfReturn the module’s class and constructor fields, and each wrapper its class was made in, in the order they were applied.
ModelConfig.with_dtype
Section titled “ModelConfig.with_dtype”def with_dtype(dtype: str | None) -> SelfThis model computing in dtype (with_dtype); None keeps it.
ModelConfig.build
Section titled “ModelConfig.build”def build(**derived: Configured = {})Build the model from its fields and the ones the recipe derived.
Record
Section titled “Record”Record = TypedDict('Record', {'class': str, 'fields': Mapping[str, object]})A class as a record names it: its alias or import path and its constructor
fields, {"class": "mla", "fields": {...}}.
Recorded
Section titled “Recorded”class Recorded(Protocol)A component a run records by the constructor view it is rebuilt from, not by its attributes: an
encoder’s checkpoint and settings, an autoencoder’s module and normalization, never the parameters
it was built around (to_record writes it as {"class", "fields"}, component finds its class).
to_record asks for this view before it walks a dataclass’s fields (record_fields), so a
dataclass that is Recorded is recorded by its view alone.
Recorded.recorded_fields
Section titled “Recorded.recorded_fields”def recorded_fields() -> Mapping[str, object]argument_records
Section titled “argument_records”def argument_records( member: type | Callable[..., Configured], fields: Mapping[str, object],) -> dict[str, JSON]fields as records of member’s parameters (parameters): each read
against its parameter’s annotation and written back, so an alias becomes
its import path, a value already built becomes its record, and an
argument member does not take, or a value no record can carry (a
lambda), is refused here rather than where the run is built.
component
Section titled “component”def component( base: type[Base], record: Mapping[str, object],) -> tuple[type[Base], Mapping[str, object]]The class a component’s record, {"class": ..., "fields": {...}} (to_record, Recorded), names
by an alias or its import path, one that is base or derives from it, and the record’s fields as
written: the lookup from_record uses for a class record (_member). A component built around parameters
(an encoder, an autoencoder, a decision head) reads its fields against its own constructor
(read_arguments) and binds them itself. A record of another shape, of a function, or a protocol
base (which no class need derive from) is refused.
dtype_name
Section titled “dtype_name”def dtype_name(value: DTypeLike | None) -> DtypeName | NoneReturn the name resolve_dtype accepts for a dtype, for a logged config.
A loader takes a dtype, jnp.bfloat16, or its name, and records the name.
encoders
Section titled “encoders”encoders: Aliases[type[ConditionEncoder[Any]], ConditionEncoder[Any]]from_record
Section titled “from_record”def from_record( annotation: type[ValueT] | types.UnionType | TypeAliasType, value: Configured, *, dtypes: bool = True,) -> ValueT | ConfiguredReturn value as the class annotation names, from a record or already one.
The class is the witness: what comes back is an instance of it or a
ValueError naming what the record built instead, so a caller reads a
value of the type it asked for rather than one it has to narrow again. A
container annotation, tuple[ParamGroup, ...] or Mapping[str, ...],
builds every entry and witnesses the container.
dtypes is the one policy the two readers differ in: a module field
takes a dtype as the dtype its name says (True), and a run record
keeps the name it wrote (RunConfig.from_dict, False).
import_path
Section titled “import_path”def import_path(member: Importable) -> strThe path a record names a class or function by, module:Qualified.name.
A lambda, a function defined inside another, or anything defined in
__main__ has no path another process can import, so it is refused here,
where the record is written, rather than when it is read.
import_trusted
Section titled “import_trusted”def import_trusted(record: object, trust: Sequence[str]) -> NoneTrust the packages in trust for the rest of the process, and import
every module of theirs that record names by an import path, so reading
the record finds them imported (imported) and may construct their
classes where a field declares no base class (_owned). A source named
there, a Hub repository or a directory, has its own code run where a
load reads it (trusts_source).
imported
Section titled “imported”def imported(path: str) -> Callable[..., Configured]The class or function an import path names, importing its module.
Records arrive from the Hub, and importing a module runs its top level,
so a record imports only Dew’s own modules and modules already imported.
Code that defines its own classes imports them before it loads a run of
them; a run of a package not yet imported loads once the caller trusts
the package (import_trusted), as trust_remote_code does in
transformers.
metrics
Section titled “metrics”metrics: Aliases[Callable[..., Metric], Metric]mixers
Section titled “mixers”mixers: Aliases[type[MixerBase], MixerBase]models
Section titled “models”models: Aliases[type[nn.Module], nn.Module]objectives
Section titled “objectives”objectives: Aliases[type[Objective], Objective]parameters
Section titled “parameters”def parameters(member: type | Callable[..., Configured]) -> tuple[Parameters, bool]member’s named parameters, each with the function that declares it,
and whether it takes any other keyword besides.
A class’s parameters are its constructor’s, and a constructor that passes
**kwargs on to its base’s takes the base’s too, as a few-step
diffusion objective takes every DiffusionObjective argument. A subclass
that names an argument again declares its own default for it.
presets
Section titled “presets”presets: Aliases[type[Preset], Preset]projectors
Section titled “projectors”projectors: Aliases[type[ProjectorBase], ProjectorBase]record_argument
Section titled “record_argument”def record_argument( annotation: type[Value],) -> tyro.constructors.PrimitiveConstructorSpec[Value]A field typed annotation written as one JSON value on the command
line, the record a run holds: a tuple of records as a list,
[{"field": ...}, ...], and a mapping of class records as an
object, {"sigma": {"class": "linear", "fields": {...}}}, since a flag per
field cannot spell a collection whose length or keys the command line
decides.
The value is read with from_record and written with to_record, so a
flag, a default and run.json hold the same record. Use it as the
field’s metadata: Annotated[Mapping[str, ScheduleSpec], record_argument(Mapping[str, ScheduleSpec])].
record_fields
Section titled “record_fields”def record_fields(value: DataclassInstance, owner: type) -> dict[str, JSON]The record of a dataclass value’s constructor fields, each as owner
declares it, at every level of a nested value alike.
A field still holding its declared callable default, such as a Flax
layer’s initializer closure, is left out: no record can name a closure,
and the class supplies the same default again when the record is read.
A Flax module’s parent is its binding, never recorded, and its name
is recorded where it was given one: a parent that keeps its submodules’
own names (preserve_adopted_names) finds its weights under them.
runs: Aliases[Callable[..., Any], Any]schedules
Section titled “schedules”schedules: Aliases[type[ScheduleBase], ScheduleBase]solvers
Section titled “solvers”solvers: Aliases[type[Solver[Any]], Solver[Any]]to_record
Section titled “to_record”def to_record(value, annotation) -> JSONReturn value as the record from_record(annotation, ...) rebuilds it from.
The record is JSON: a dict, a list, or a scalar json.dump can write. A
dataclass is the record of its fields where annotation names its class
exactly, and {"class": <import path>, "fields": {...}} where the field
declares a base, a union or nothing, so the reader knows what to build;
a function is {"function": <import path>}. A Flax module held twice in
one record, as nn.Sequential([dense, dense]) holds its one shared layer,
is written once as a class record with "share": <n>, and each later
place that holds it as {"shared": <n>}, so the reader builds one module
and the model keeps one set of parameters for it (recording).
towers
Section titled “towers”towers: Aliases[type[TowerBase], TowerBase]trust_sources
Section titled “trust_sources”def trust_sources(names: Sequence[str]) -> NoneTrust the sources names for the rest of the process (trusts_source).
trusts_source
Section titled “trusts_source”def trusts_source(name: str) -> boolWhether the process trusts the source name, a Hub repository or a directory, to run its own
code where a load reads it (trust_remote_code): as trust=(name,) and --trust name say where a
run or a task loads (import_trusted), or a load asked to run it (trust_sources).
with_dtype
Section titled “with_dtype”def with_dtype( name: str, fields: Mapping[str, object], dtype: str | None,) -> Mapping[str, object]fields, the model name builds from, computing in dtype.
The dtype is written into the model’s own dtype field, or, for a
composite that declares none (DiffusionGemma around its text decoder),
into each model part it holds that declares one, as a record or built.
A model with neither refuses a dtype. None leaves fields as they are.