Skip to content

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.

NameSummary
KINDSEvery kind, which a record’s alias is looked up across.
AliasesThe short names of one kind, each mapped to the import path of its class.
ModelConfigA model’s class and the fields the run gives it.
RecordA class as a record names it: its alias or import path and its constructor fields, {"class": "mla", "fields": {...}}.
RecordedA 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_recordsfields 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.
componentThe 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_nameReturn the name resolve_dtype accepts for a dtype, for a logged config.
encoders
from_recordReturn value as the class annotation names, from a record or already one.
import_pathThe path a record names a class or function by, module:Qualified.name.
import_trustedTrust 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).
importedThe class or function an import path names, importing its module.
metrics
mixers
models
objectives
parametersmember’s named parameters, each with the function that declares it, and whether it takes any other keyword besides.
presets
projectors
record_argumentA 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_fieldsThe 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_recordReturn value as the record from_record(annotation, ...) rebuilds it from.
towers
trust_sourcesTrust the sources names for the rest of the process (trusts_source).
trusts_sourceWhether 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_dtypefields, the model name builds from, computing in dtype.

attribute source

KINDS: tuple[Aliases, ...] = (models, presets, solvers, encoders, metrics, objectives, mixers, towers, projectors, schedules)

Every kind, which a record’s alias is looked up across.

class source

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.

def label(path: str) -> str

The alias of the class at import path, or its class name where it has none, for a run’s human-readable name.

def name_of(member: Importable) -> str

The name a record writes for member: its alias in this kind, else its import path.

def alias_of(member: Importable) -> str

The alias of member, for a run’s human-readable name; KeyError for a class this kind has no alias for.

def build(
name: str,
record: Mapping[str, object] = NO_RECORD,
/,
**fields: Configured = {},
) -> Built

Construct 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.

def from_record(record: Mapping[str, object]) -> Built

Construct the member a class record names, {"class": ..., "fields": {...}}.

dataclass source

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 build applies 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.

def from_dict(values: Mapping[str, object]) -> Self

Read back the record RunConfig.to_dict writes for this field.

def from_model(model) -> Self

Return the module’s class and constructor fields, and each wrapper its class was made in, in the order they were applied.

def with_dtype(dtype: str | None) -> Self

This model computing in dtype (with_dtype); None keeps it.

def build(**derived: Configured = {})

Build the model from its fields and the ones the recipe derived.

attribute source

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": {...}}.

class source

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.

def recorded_fields() -> Mapping[str, object]

function source

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.

function source

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.

function source

def dtype_name(value: DTypeLike | None) -> DtypeName | None

Return 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.

attribute source

encoders: Aliases[type[ConditionEncoder[Any]], ConditionEncoder[Any]]

function source

def from_record(
annotation: type[ValueT] | types.UnionType | TypeAliasType,
value: Configured,
*,
dtypes: bool = True,
) -> ValueT | Configured

Return 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).

function source

def import_path(member: Importable) -> str

The 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.

function source

def import_trusted(record: object, trust: Sequence[str]) -> None

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). A source named there, a Hub repository or a directory, has its own code run where a load reads it (trusts_source).

function source

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.

attribute source

metrics: Aliases[Callable[..., Metric], Metric]

attribute source

mixers: Aliases[type[MixerBase], MixerBase]

attribute source

models: Aliases[type[nn.Module], nn.Module]

attribute source

objectives: Aliases[type[Objective], Objective]

function source

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.

attribute source

presets: Aliases[type[Preset], Preset]

attribute source

projectors: Aliases[type[ProjectorBase], ProjectorBase]

function source

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])].

function source

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.

attribute source

runs: Aliases[type[RunConfig], RunConfig]

attribute source

schedules: Aliases[type[ScheduleBase], ScheduleBase]

attribute source

solvers: Aliases[type[Solver], Solver]

function source

def to_record(value, annotation) -> JSON

Return 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).

attribute source

towers: Aliases[type[TowerBase], TowerBase]

function source

def trust_sources(names: Sequence[str]) -> None

Trust the sources names for the rest of the process (trusts_source).

function source

def trusts_source(name: str) -> bool

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).

function source

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.