dew.interop
Checkpoint readers and translators, each imported only when you use its API.
So reading Hub metadata or a safetensors file does not import the decoder translators or the diffusion pipeline loader.
| Name | Summary |
|---|---|
Pretrained | A native model with explicit variables and its checkpoint’s host processor. |
PretrainedBlockDecoder | A DiffusionGemma source, which decodes whole canvases. |
PretrainedDecision | A native backbone bundle with its readout and declared decision task. |
PretrainedDecoder | An autoregressive decoder, alone or inside a multimodal wrapper. |
PretrainedFallback | A causal LM run as transformers’ PyTorch forward, lowered to JAX by torchax (tier 3). |
PretrainedMaskedDecoder | A masked-diffusion decoder (LLaDA, Dream). |
PretrainedPipeline | A latent diffusion pipeline: the denoiser as model, with its process, conditions and autoencoder. |
Processor | Runs a checkpoint’s own processor on the host and arranges its outputs as native model inputs. |
SourceReference | A local directory or Hub repository, its pinned revision and selected component folder. |
load_params | Read a safetensors file back into a nested parameter dict. |
save_hf_layout | Write the weights and config.json into directory, the layout a Hugging Face style loader reads. |
save_params | Write a parameter tree to a safetensors file, one tensor per leaf. |
translate_config | Translate one registered family’s config, refusing any setting Dew does not compute. |
translate_weights | Map HF tensors into a CausalTransformer tree, with parameters in FP32 by default: read_decoder’s tree. |
Pretrained
Section titled “Pretrained”class Pretrained( model: nn.Module, variables: Variables, processor: Processor | None, config: Mapping[str, object], source: Path | None, model_config: Mapping[str, object], generation_config: Mapping[str, object] = dict(), weight_layouts: tuple[WeightLayout, ...] = (), retained_tensors: Mapping[str, unread.Stored] = dict(), export_adapter: Callable[..., Mapping[str, np.ndarray]] | None = None, quantized_tensors: tuple[str, ...] = (), quantized_scale_dtype: str | None = None, quantization_grid: Mapping[str, unread.Stored] = dict(), revision: str | None = None, origin: str | None = None, adapter: Adapter | None = None, tokenizer: str | decoders.ExportTokenizer | None = None, code: decoder_parts.SourceCode | None = None, fresh: tuple[str, ...] = (), numerics: Numerics | None = None, settings: TaskSettings | None = None,)A native model with explicit variables and its checkpoint’s host processor.
Pretrained.load returns a subclass for the kind of source it read, with the
methods that work for that kind: PretrainedDecoder for an autoregressive
decoder, PretrainedMaskedDecoder for a masked-diffusion one,
PretrainedBlockDecoder for DiffusionGemma, PretrainedPipeline for a latent
diffusion pipeline, and PretrainedFallback for transformers’ own forward run
through torchax. Every kind saves back to the source’s format.
model_config is the record the model was built from at its load, in Dew’s
own vocabulary with the run’s compute dtype and attention kernel; declaration
is the model’s record as it is now, an adapter, DEX, cross-attention or a
loop it was given since included, which a caller logs to name the model it ran.
retained_tensors: Mapping[str, unread.Stored]-
The source tensors no forward reads, kept as stored for
saveto write back.A pipeline keeps a text encoder’s vision tower here, each tensor named under its component as its layouts are.
export_adapter: Callable[..., Mapping[str, np.ndarray]] | None-
The encoder
exportwrites through, installed by the route that built the model, or None forweight_layouts. quantized_scale_dtype: str | None-
The dtype a quantized source stored its scales in, when its format leaves that to the checkpoint.
DeepSeek-V4’s
.scale, for example, is float8_e8m0fnu, and float32 in the Base releases.savewrites the scales back in this dtype. quantization_grid: Mapping[str, unread.Stored]-
The scales and zeros an integer format (AWQ, GPTQ) encodes a saved weight against.
They are kept as the source stored them.
revision: str | None-
The Hub commit the source resolved to, whatever branch or tag was requested.
None for a local directory.
origin: str | None-
The Hub id the load resolved to
revision, which an adapter’s PEFT config names as its base (AdapterBase); None for a local directory, a payload a selector chose or a model trained in Dew, which a reader of an id alone does not load (_published). adapter: Adapter | None-
The low-rank adapter that
adaptattached to the model, or None for the source as published.The variables hold its factors under
params, next to the base weights underfrozen. tokenizer: str | decoders.ExportTokenizer | None-
The vocabulary
savewrites next to the weights, by name or as an object.It is used by a bundle that has no source processor to write (
from_model). code: decoder_parts.SourceCode | None-
The source’s own modeling code, where its config names it (
auto_map), whichsavewrites beside the weights, its modules and their relative imports (sources.code_modules), whether a load ran them (trust_remote_code) or, mapped natively, kept them unexecuted, so a save opens through the source’s own transformers loader as the source does; read from the source’s snapshot, which a weights conversion may not be, when the save writes it. fresh: tuple[str, ...]-
The modules of
modeldrawn fresh beside the loaded weights, by their paths underparams(layers_1/cross_attention): whatwith_cross_attentionadds, which a run trains in a fresh group (Objective.fresh_modules,dew.optim.OptimConfig.fresh_groups). numerics: Numerics | None-
The numerics the load was asked for (
load(precision=...)), whose dtypes it computes and stores in and whose products’ precision and forms its tasks trace under (formed), a saved run’s those its step trained in (SavedRun.precision); None for its dtypes alone. settings: TaskSettings | None-
A saved run’s own task declaration (
from_saved), which its tasks build from as the run’s own loader builds them (TextGeneration.from_settings: its prefix, policy and budget), where a source read from its files builds them from its generation config, which an export writes as the representation its format’s readers read (ledger 3007). names_tokenizer: bool-
Whether generation_config.json may record the tokenizer’s name.
It is False for a family whose reader treats that file as a closed set of fields.
source: Path | None-
The directory the source was read from.
None for a model trained in Dew (
PretrainedDecoder.from_model). eos_token_ids: tuple[int, ...]-
The end-of-sequence ids the source’s generation stops at, from its generation config or its config (
eos_token_id), none where neither names one. declaration: ModelConfig-
The record of the model this bundle holds now (
ModelConfig.from_model): its class, every field and each wrapper it was made in, an extension given since its load included, wheremodel_configkeeps the record it was loaded as (ledger 3009). A tier-3 model, whose graph holds a live torch module, records nothing more than its load’s record, which a caller reads instead. text_processor: TaskProcessor | None-
Return what the bundle’s tasks encode and decode text with.
That is the source’s processor, or a run processor over the vocabulary that
tokenizernames (a run’s export, including Dew’s byte vocabulary). layouts: Mapping[str, WeightLayout]-
Map each source module name to the layout of its weight.
The names are
model.<module>for a decoder andunet.<module>for a pipeline component. A published adapter file uses these names, sodew.loraattaches a low-rank delta through them.
Pretrained.map_variables
Section titled “Pretrained.map_variables”def map_variables(transform: Callable[[Variables], Variables]) -> SelfThis bundle with its variable tree transformed, for placement or a shape-only load. Composite bundles apply the same transformation to each component.
Pretrained.pipeline
Section titled “Pretrained.pipeline”def pipeline() -> SavedTaskThe native task declared by this source kind.
Pretrained.formed
Section titled “Pretrained.formed”def formed(task: TaskT) -> TaskTtask, built from this source, under the numerics its load was asked for (numerics) where
it traces under numerics (dew.inference.tasks.InItsForm).
Pretrained.packed
Section titled “Pretrained.packed”def packed() -> SelfA serving view with packed projections, preserving this bundle’s arrays for reuse.
Pretrained.from_run
Section titled “Pretrained.from_run”def from_run( directory: str | Path, *, step: int | str | None = None, ema: bool | None = None, trust: Sequence[str] = (),) -> SelfReturn a trained run’s selected checkpoint, step or the one its task loads by default
(SavedRun.pinned), rebuilt from the run’s
own inference record (from_saved). trust names the packages outside Dew the record may
import (TextGeneration.from_run).
Pretrained.from_saved
Section titled “Pretrained.from_saved”def from_saved( run: SavedRun, *, ema: bool | None = None, mesh: MeshSpec | Mesh | None = None, layout: Layout | None = None,) -> SelfReturn the pinned checkpoint run (SavedRun.pinned), rebuilt from the run’s own inference
record, in the layout of the architecture the record names.
Pretrained.bound
Section titled “Pretrained.bound”def bound(model: nn.Module, variables: Variables) -> SelfThis bundle carrying the LoRA model’s record binds over variables, as
Adapter.from_run rebuilds it, so export and save merge its factors into
their kernels and adapter.save writes them alone; the bundle itself where
model carries none.
Pretrained.load
Section titled “Pretrained.load”def load( name_or_dir: str | Path, *, dtype: DTypeLike = jnp.bfloat16, param_dtype: DTypeLike | Literal['auto'] = jnp.float32, attention_impl: AttentionImpl = 'auto', max_seq_len: int | None = None, revision: str | None = None, subfolder: str | None = None, gguf_file: str | None = None, single_file: str | None = None, dduf_file: str | None = None, mesh: MeshSpec | Mesh | None = None, layout: Layout | None = None, fallback: str | None = None, weights: bool = True, on_host: bool = False, modeling_overrides: Mapping[str, object] | None = None, trust_remote_code: bool | None = None, text_only: bool = False, prediction_depths: int | None = None, dex: DifferentialExtension | None = None, precision: Numerics | str | None = None, scan_layers: bool = False, step: int | str | None = None, ema: bool | None = None,) -> SelfLoad a source as a native Flax model with explicit parameter trees, as the kind of source it is.
name_or_dir is a local HF directory or a Hub model ID. Decoder, tower and
projector weights keep their usual internal paths, and a wrapper’s variables
join under its existing component names. Processor files are loaded only when
the source has them.
dtype sets the compute dtype, and param_dtype separately sets the storage
dtype of floating parameters. It defaults to FP32 master weights, and ‘auto’
keeps each tensor in the dtype the checkpoint stores it in; a quantized
source’s packed weights decode to the dtype it declares (declared_dtype).
precision, a run’s numerics or their name (dew.nn.precision.numerics_of), sets both
from its dtypes, and the bundle’s tasks trace under its precision and forms (formed).
Each is a dtype (jnp.bfloat16) or its name, and the model’s record keeps
the name. Frozen components (text encoders and the VAE) follow param_dtype
too, while router, clipping, positional and safety state keep their own FP32
or integer dtypes.
A loaded source is ready to run: without mesh or layout its variables are
built on the host and then placed on JAX’s default device (jax.default_device)
one leaf at a time, uncommitted, as a jnp array is, so a call or a placement
over other devices still takes them. With either, they are placed on that mesh
(the default MeshSpec() when only layout is given) under that layout.
on_host=True keeps them as host arrays instead, for a caller that places them
itself, as a training start or an export does; a host tree passed to a jitted
call is copied to the device at each call. With a mesh or layout, a decoder’s or
a diffusion pipeline’s leaves are read from the memory-mapped checkpoint one
device shard at a time, and cast and transposed there (dew.interop.streaming),
so the host never holds the whole translated model. Towers, projectors, a quantized source’s
dequantized tensors and a pipeline’s convolution kernels are still built
whole on the host first.
gguf_file names a GGUF file in the repo or directory. Its metadata is the
config, its block-quantized tensors are dequantized to float32
(dew.interop.gguf), and its tokenizer is the processor when the repo ships
no tokenizer.
single_file selects an original diffusion checkpoint, converted through
Diffusers’ key maps (dew.interop.single_file); dduf_file selects a packed
diffusion pipeline (dew.interop.dduf). Both load through the ordinary
directory pipeline after conversion. fallback="torchax" selects the
explicit transformers-forward route (dew.interop.torchax_fallback).
subfolder selects a folder within the resolved snapshot; decision releases
are assembled from their declared backbone and head components.
trust_remote_code=True lets tier 2 run the repository’s own modeling code (its
auto_map) for a model_type transformers has no class for (dew.interop.verify), and a media
processor its own processor code (LFM3-VL’s), and save writes it beside the weights (code);
the process then trusts the source (dew.registry.trusts_source), so a processor reloaded from its
record runs that code too (load_processor). None, the default, runs it where the process
already trusts the source: a task or run loaded with trust=(name,) or --trust name
(dew.inference.load, dew train). False never runs it.
Called on a specific kind (PretrainedDecoder.load), it refuses a source of
another kind and names that kind.
text_only=True loads a multimodal wrapper’s language model alone, as its text family’s own
checkpoint states it (Qwen3.5’s Qwen3_5ForCausalLM; DeepSeek-V4.1’s bundle as its own text
checkpoint): no tower, projector or audio encoder is built, nor their tensors read, and the source
saves as that text checkpoint. A source that is a decoder already loads as it is; a pipeline or
a fallback has no language model to take.
prediction_depths keeps the first that many of a decoder’s multi-token prediction depths
(DeepSeek V3’s, GLM’s and Qwen3.5’s mtp blocks): None the ones the checkpoint holds, 0
none, n the first n; a DSpark drafter, whose stages draft as one, is kept whole or at 0
not at all. The load reads the source as a checkpoint of those
alone (_kept_depths): the others are neither built nor their tensors read, and it saves as
that checkpoint. A source that holds fewer keeps what it holds; one with none holds none.
Without weights, the variables are their shapes and dtypes alone
(jax.ShapeDtypeStruct), read from the source’s headers through the same
translation: what a run that resumes from its own checkpoint builds its state
around (TrainerConfig.resumes), as MaxText loads its base parameters only
for a run with no checkpoint.
modeling_overrides is a record of the form a release’s config states under that key, read
through the same reader over the release’s own, kind by kind: {"attention": {"full_attention": "block_bidirectional"}} lets that layer kind’s tokens read their whole block
(AttentionMixer.bidirectional_blocks, a call’s block_groups) on any decoder or wrapper this
loads natively, and “causal” turns a release’s back off. A saved model states it in its own
config. dex attaches DEX (with_dex) from key 0; scan_layers scans like layers (Scanning).
A saved Dew run loads as dew export writes it, at step with ema (released_run).
Pretrained.adapt
Section titled “Pretrained.adapt”def adapt(lora: LoRA, *, key: int | jax.Array) -> SelfReturn this source with lora attached to its model and its factors drawn (LoRA.apply).
The result holds the adapted model, the variables with the factors under
params and the base weights under frozen, and the bound adapter. Any
objective built over it trains only the factors, and since B starts at zero it
computes what the source does. adapter.save writes the factors under the
source’s own names (PEFT’s directory for a decoder, the Diffusers file for a
pipeline), and save writes the source with them merged in. A pipeline
adapts only its denoiser’s projections, so the text towers and the VAE stay
as published.
Pretrained.with_cross_attention
Section titled “Pretrained.with_cross_attention”def with_cross_attention( cross: CrossBlocks, *, key: int | jax.Array, frozen: bool = True,) -> SelfReturn this source with gated cross-attention before the layers cross names, each
block drawn from key (dew.nn.cross_attention).
The blocks’ gates start at zero, so the model computes what the source
does until they train. The variables hold the blocks under params and,
where frozen, the source’s weights under FROZEN, so an objective
built over the result trains the blocks alone; an adapter’s factors that
already train keep training, and adapt keeps the blocks training, so
the two compose in either order. With frozen=False the source’s own
split stands: an unsplit source’s every weight trains beside the
blocks, a full fine-tune. The source’s own format holds no
cross-attention, so save and export refuse the result; a run’s
checkpoint keeps it.
Pretrained.with_dex
Section titled “Pretrained.with_dex”def with_dex(extension: DifferentialExtension, *, key: int | jax.Array) -> SelfReturn this source with DEX’s differential on extension’s chosen heads (dew.nn.dex), its
projections drawn from key under params and its lambdas zero, so the model computes what the
source does until they train, and each layer’s chosen heads and lambda_init held beside them
(dew.nn.dex.DEX_CONSTANTS); the rest trains as the extension’s recipe says
(DifferentialExtension.trains: the paper’s, the attention’s key, value and output projections
beside it and the rest under FROZEN, or all of it), a source’s frozen weights staying frozen. A
source loaded without its weights takes the extension’s shapes. The source’s own format holds no
extension: save and export write each layer’s differential at its learned lambda folded into
its output projection (dew.nn.dex.folded), what the model computes outside a run, and refuse a
layer whose heads’ outputs pass through more before it; a run’s checkpoint keeps the extension.
Pretrained.export
Section titled “Pretrained.export”def export(variables: Mapping[str, object] | None = None) -> Mapping[str, np.ndarray]Return the tensors save writes, by their source names; dew.inference.NCCLPush sends these.
An adapted bundle (lora) writes the source’s own tensors with the factors
merged into their kernels, as PEFT’s merge_and_unload does, from its
variables or a trainer’s split of them; adapter.save writes the factors
alone. A loaded task’s tree, its projections packed for serving, is written
as the source’s own members (dew.inference.projections.unpacked). A model with DEX writes
each layer’s differential folded into its output projection (dew.nn.dex.folded).
Pretrained.save
Section titled “Pretrained.save”def save( directory: str | Path, *, variables: Mapping[str, object] | None = None, max_shard_size: int | str = MAX_SHARD_SIZE,) -> NoneWrite export’s tensors, the source’s own config.json as published, and its tokenizer files,
and the source’s own Python modules a load ran (code), so the directory loads as the source
did.
The tensors are written in shards of at most max_shard_size.
Pretrained.push_to_hub
Section titled “Pretrained.push_to_hub”def push_to_hub( repo_id: str, *, variables: Mapping[str, object] | None = None, private: bool = False, commit_message: str = 'Upload dew export', max_shard_size: int | str = MAX_SHARD_SIZE,) -> NoneUpload what save writes to the Hub repo repo_id, creating the repo if it is missing.
It calls save into a staging directory, then huggingface_hub.HfApi’s
create_repo and upload_folder. The Hub client handles retries, progress
and authentication.
PretrainedBlockDecoder
Section titled “PretrainedBlockDecoder”class PretrainedBlockDecoder( model: DiffusionGemma, variables: Variables, processor: Processor | None, config: Mapping[str, object], source: Path | None, model_config: Mapping[str, object], generation_config: Mapping[str, object] = dict(), weight_layouts: tuple[WeightLayout, ...] = (), retained_tensors: Mapping[str, unread.Stored] = dict(), export_adapter: Callable[..., Mapping[str, np.ndarray]] | None = None, quantized_tensors: tuple[str, ...] = (), quantized_scale_dtype: str | None = None, quantization_grid: Mapping[str, unread.Stored] = dict(), revision: str | None = None, origin: str | None = None, adapter: Adapter | None = None, tokenizer: str | decoders.ExportTokenizer | None = None, code: decoder_parts.SourceCode | None = None, fresh: tuple[str, ...] = (), numerics: Numerics | None = None, settings: TaskSettings | None = None,)A DiffusionGemma source, which decodes whole canvases.
PretrainedBlockDecoder.pipeline
Section titled “PretrainedBlockDecoder.pipeline”def pipeline()PretrainedBlockDecoder.block_generation
Section titled “PretrainedBlockDecoder.block_generation”def block_generation() -> BlockGenerationBuild the DiffusionGemma canvas task, with the source’s sampler config as its default, a
saved run’s its own declaration (settings).
PretrainedDecision
Section titled “PretrainedDecision”class PretrainedDecision( model: nn.Module, variables: Variables, processor: Processor | None, config: Mapping[str, object], source: Path | None, model_config: Mapping[str, object], generation_config: Mapping[str, object] = dict(), weight_layouts: tuple[WeightLayout, ...] = (), retained_tensors: Mapping[str, unread.Stored] = dict(), export_adapter: Callable[..., Mapping[str, np.ndarray]] | None = None, quantized_tensors: tuple[str, ...] = (), quantized_scale_dtype: str | None = None, quantization_grid: Mapping[str, unread.Stored] = dict(), revision: str | None = None, origin: str | None = None, adapter: Adapter | None = None, tokenizer: str | decoders.ExportTokenizer | None = None, code: decoder_parts.SourceCode | None = None, fresh: tuple[str, ...] = (), numerics: Numerics | None = None, settings: TaskSettings | None = None, *, head: Head, head_variables: Variables, layout: Layout, specials: Specials, calibration: Calibration, decision_tokenizer: HFTokenizer, writer: Callable[..., None], exporter: Callable[..., Mapping[str, np.ndarray]], assumed: frozenset[str] = frozenset(),)A native backbone bundle with its readout and declared decision task.
Inherited adaptation operates on the backbone; the readout retains its own variables. The release
is the backbone and its readout together: save writes both in the format it was read from, and
export returns every tensor that release holds, the readout’s beside the backbone’s, by its name
in the release’s files, which a weight push (NCCLPush) sends; backbone is the backbone alone.
writer: Callable[..., None]-
The release format’s writer, the source codec’s own:
savewrites the format it was read from. exporter: Callable[..., Mapping[str, np.ndarray]]-
The release format’s tensors,
writer’s own:exportreturns whatsavewrites. assumed: frozenset[str]-
The question budgets its layout holds that its release states none of, Laya’s own (
LAYA_BUDGETS), as a run reports where each came from.
PretrainedDecision.map_variables
Section titled “PretrainedDecision.map_variables”def map_variables(transform: Callable[[Variables], Variables]) -> SelfPretrainedDecision.backbone
Section titled “PretrainedDecision.backbone”def backbone() -> PretrainedThe native backbone alone, as it was read and as it is adapted (adapt), without the
readout: its own export and save, which a release’s writer writes beside the readout.
PretrainedDecision.export
Section titled “PretrainedDecision.export”def export(variables: Mapping[str, object] | None = None) -> Mapping[str, np.ndarray]Every tensor the release save writes, the readout’s beside the backbone’s, by its name in the
release’s files; variables, a trainer’s split of the backbone’s, in place of the bundle’s.
PretrainedDecision.pipeline
Section titled “PretrainedDecision.pipeline”def pipeline() -> DecidePretrainedDecision.save
Section titled “PretrainedDecision.save”def save( directory: str | Path, *, variables: Mapping[str, object] | None = None, max_shard_size: int | str = MAX_SHARD_SIZE,) -> NonePretrainedDecision.from_components
Section titled “PretrainedDecision.from_components”def from_components( backbone: Pretrained, head: Head, head_variables: Variables, directory: Path, tokenizer_folder: str, *, layout: Layout, calibration: Calibration, strict_specials: bool, writer: Callable[..., None], exporter: Callable[..., Mapping[str, np.ndarray]], assumed: frozenset[str] = frozenset(),) -> SelfPretrainedDecoder
Section titled “PretrainedDecoder”class PretrainedDecoder( model: CausalTransformer | MultimodalTransformer, variables: Variables, processor: Processor | None, config: Mapping[str, object], source: Path | None, model_config: Mapping[str, object], generation_config: Mapping[str, object] = dict(), weight_layouts: tuple[WeightLayout, ...] = (), retained_tensors: Mapping[str, unread.Stored] = dict(), export_adapter: Callable[..., Mapping[str, np.ndarray]] | None = None, quantized_tensors: tuple[str, ...] = (), quantized_scale_dtype: str | None = None, quantization_grid: Mapping[str, unread.Stored] = dict(), revision: str | None = None, origin: str | None = None, adapter: Adapter | None = None, tokenizer: str | decoders.ExportTokenizer | None = None, code: decoder_parts.SourceCode | None = None, fresh: tuple[str, ...] = (), numerics: Numerics | None = None, settings: TaskSettings | None = None,)An autoregressive decoder, alone or inside a multimodal wrapper.
It generates through its KV cache, fine-tunes on next-token prediction and takes a low-rank adapter.
PretrainedDecoder.pipeline
Section titled “PretrainedDecoder.pipeline”def pipeline()PretrainedDecoder.from_model
Section titled “PretrainedDecoder.from_model”def from_model( model: nn.Module, variables: Variables, *, tokenizer: str | decoders.ExportTokenizer | None = None, generation_config: Mapping[str, object] | None = None,) -> PretrainedDecoderWrap a decoder trained in Dew as a bundle that save writes in its family’s Hugging Face layout.
The config is derived from the native computation, and every variable
collection is encoded through the matching family. That is the same encoder a
loaded source of the derived family exports through, so both write the same
weights. Gemma 4 writes frozen or trainable layer-scalar values into HF
buffers; reloading that layout reproduces the computation, but not which
scalars were trainable. The config is derived from a causal_transformer’s
fields, so any other model is refused. A decoder with cross-attention or DEX takes the
config of the decoder they extend and runs as a bundle, but save refuses it.
tokenizer is the vocabulary the weights were trained with, as an object or
by name. save writes its files next to the weights, so the directory that
Pretrained.load reads back includes its processor. generation_config is
what generation_config.json records; None uses the native defaults with
the exported model’s cache mode.
PretrainedDecoder.text_generation
Section titled “PretrainedDecoder.text_generation”def text_generation(*, sampling: Sampling | None = None) -> TextGenerationBuild the text generation task this source describes.
Without an override, the task runs the source’s policy (task.sampling holds
every common control its config sets), any transform chain the rarer controls
need, and the strategy its config names. An explicit sampling replaces the
policy and drops that chain, because the chain was built for the policy the
caller replaced; the source’s EOS and pad ids fill the ones it leaves None,
and num_return_sequences still comes from the source.
The task shares the bundle’s weights and packs its decoder’s projections inside
each generation’s compiled call; dew.pipeline’s task packs them once, after
placing them. An adapted model whose factors are not merged keeps its
projection paths and is not packed.
PretrainedFallback
Section titled “PretrainedFallback”class PretrainedFallback( model: nn.Module, variables: Variables, processor: Processor | None, config: Mapping[str, object], source: Path | None, model_config: Mapping[str, object], generation_config: Mapping[str, object] = dict(), weight_layouts: tuple[WeightLayout, ...] = (), retained_tensors: Mapping[str, unread.Stored] = dict(), export_adapter: Callable[..., Mapping[str, np.ndarray]] | None = None, quantized_tensors: tuple[str, ...] = (), quantized_scale_dtype: str | None = None, quantization_grid: Mapping[str, unread.Stored] = dict(), revision: str | None = None, origin: str | None = None, adapter: Adapter | None = None, tokenizer: str | decoders.ExportTokenizer | None = None, code: decoder_parts.SourceCode | None = None, fresh: tuple[str, ...] = (), numerics: Numerics | None = None, settings: TaskSettings | None = None,)A causal LM run as transformers’ PyTorch forward, lowered to JAX by torchax (tier 3).
It fine-tunes on next-token prediction, without Dew’s kernels or sharding rules; train it like
any source, LMObjective(fallback, seq_len). One whose attention runs on Dew’s generates through
Dew’s decode cache (text_generation, as a native decoder’s, which dew.pipeline and the
server run); one on transformers’ own refuses a cache (TorchCausalLM).
PretrainedFallback.pipeline
Section titled “PretrainedFallback.pipeline”def pipeline()PretrainedFallback.text_generation
Section titled “PretrainedFallback.text_generation”def text_generation(*, sampling: Sampling | None = None) -> TextGenerationThe text generation task this source describes, as a native decoder’s
(PretrainedDecoder.text_generation).
PretrainedMaskedDecoder
Section titled “PretrainedMaskedDecoder”class PretrainedMaskedDecoder( model: CausalTransformer, variables: Variables, processor: Processor | None, config: Mapping[str, object], source: Path | None, model_config: Mapping[str, object], generation_config: Mapping[str, object] = dict(), weight_layouts: tuple[WeightLayout, ...] = (), retained_tensors: Mapping[str, unread.Stored] = dict(), export_adapter: Callable[..., Mapping[str, np.ndarray]] | None = None, quantized_tensors: tuple[str, ...] = (), quantized_scale_dtype: str | None = None, quantization_grid: Mapping[str, unread.Stored] = dict(), revision: str | None = None, origin: str | None = None, adapter: Adapter | None = None, tokenizer: str | decoders.ExportTokenizer | None = None, code: decoder_parts.SourceCode | None = None, fresh: tuple[str, ...] = (), numerics: Numerics | None = None, settings: TaskSettings | None = None,)A masked-diffusion decoder (LLaDA, Dream).
It is a non-causal decoder with a mask id that generates by unmasking a whole
response, or, where its family declares its release’s walk (LLaDA2.0’s
blocks, Dream’s grid), as the release does (masked_walk), which its task
and an objective over it (MaskedDiffusionObjective) take alike.
masked_walk: decoder_parts.MaskedWalk | None-
The release’s own walk this source generates by (
DecoderFamily.masked_walkof its config, its generation config and its own code: LLaDA2.0’s blocks, Dream’sorigin), or None for a source whose family declares none, an unregistered one among them, which unmasks the whole response with Dew’s MDLM.
PretrainedMaskedDecoder.pipeline
Section titled “PretrainedMaskedDecoder.pipeline”def pipeline()PretrainedMaskedDecoder.text_generation
Section titled “PretrainedMaskedDecoder.text_generation”def text_generation() -> MaskedGenerationBuild the masked generation task this source describes, walking as its release does where
its family declares the walk (masked_walk), else refining a whole response with Dew’s MDLM
sampler (Unmask), not its family’s own recipe.
PretrainedPipeline
Section titled “PretrainedPipeline”class PretrainedPipeline( model: nn.Module, variables: Variables, processor: Processor | None, config: Mapping[str, object], source: Path | None, model_config: Mapping[str, object], generation_config: Mapping[str, object] = dict(), weight_layouts: tuple[WeightLayout, ...] = (), retained_tensors: Mapping[str, unread.Stored] = dict(), export_adapter: Callable[..., Mapping[str, np.ndarray]] | None = None, quantized_tensors: tuple[str, ...] = (), quantized_scale_dtype: str | None = None, quantization_grid: Mapping[str, unread.Stored] = dict(), revision: str | None = None, origin: str | None = None, adapter: Adapter | None = None, tokenizer: str | decoders.ExportTokenizer | None = None, code: decoder_parts.SourceCode | None = None, fresh: tuple[str, ...] = (), numerics: Numerics | None = None, settings: TaskSettings | None = None, *, process: Process, inputs: InputSpec, autoencoder: AutoEncoder | None, schedule: SourceSchedule, task: SourceTask, finish: Callable[[Mapping[str, object], jax.Array], jax.Array] | None = None,)A latent diffusion pipeline: the denoiser as model, with its process, conditions and autoencoder.
It also holds the policy the source samples with. It samples, fine-tunes by
denoising and takes a low-rank adapter on its denoiser. save writes one
tensor set per component, in the diffusers layout.
solver: Solver-
The native solver its scheduler file names (
SourceSchedule.solver). steps: int-
The step count its call samples with by default (
SourceTask.steps). guidance: Guidance | None-
The guidance its call samples with by default (
SourceTask.guidance). grid: SourceGrid-
The sampling grid its call prepares (
SourceTask.grid).
PretrainedPipeline.pipeline
Section titled “PretrainedPipeline.pipeline”def pipeline()PretrainedPipeline.text_to_image
Section titled “PretrainedPipeline.text_to_image”def text_to_image() -> TextToImageBuild the pipeline as a sampling task with its published policy.
A video source’s task (Wan’s) samples clips of shape
[N, frames, height, width, 3].
PretrainedPipeline.export
Section titled “PretrainedPipeline.export”def export(variables: Mapping[str, object] | None = None) -> Mapping[str, np.ndarray]PretrainedPipeline.save
Section titled “PretrainedPipeline.save”def save( directory: str | Path, *, variables: Mapping[str, object] | None = None, max_shard_size: int | str = MAX_SHARD_SIZE,) -> NoneWrite each component’s tensors and config in the diffusers layout,
its weights in shards of at most max_shard_size where they exceed it.
An adapted bundle’s factors are merged into the denoiser’s kernels (PEFT’s
merge_and_unload), from its variables or a trainer’s split of them;
adapter.save writes the factors alone.
Processor
Section titled “Processor”class Processor( reference: HostProcessor, config: Mapping[str, object], record: Mapping[str, object], vocab_size: int, source: SourceReference | None = None, directory: Path | None = None,)Runs a checkpoint’s own processor on the host and arranges its outputs as native model inputs.
reference is the checkpoint’s tokenizer. Media requests load and
retain its full processor, which owns resizing, normalization and
special-token expansion. Dew arranges its outputs into row-aligned
arrays; it does not reproduce the checkpoint’s image preprocessing
algorithms. Calling it with text, and optionally images, audio or
videos, returns ModelInputs.
source records the directory or repository, revision and subfolder its files came from.
That identity reloads the processor (load_processor), and a media
processor’s geometry from the source config, independently of a task’s
text tokenizer. Only a media processor reads files from directory, and
runs the source’s own processor code there (its config’s auto_map,
LFM3-VL’s) where its load ran the source’s own code
(SourceReference.remote_code).
directory: Path | None-
Where this process reads the files. Only
sourcerecords their identity. bos_id: int | None-
The id the source’s tokenizer starts a sequence with, or None.
Processor.host_media
Section titled “Processor.host_media”def host_media(text: str | Sequence[str], *, images: Media) -> dict[str, np.ndarray]The source’s fields for text and images as host arrays in their own dtypes, before Dew
aligns them to model rows: asked of the processor in the tensor type it computes in
(_media_tensors), and read as _from_arrays reads them, a bfloat16 field widened to
float32.
Processor.media
Section titled “Processor.media”def media( *, images: Media | None = None, **kwargs: Unpack[ProcessorCall] = {},) -> Mapping[str, object]Return the source’s media fields before Dew aligns them to model rows.
Processor.image_text
Section titled “Processor.image_text”def image_text() -> strThe text one image stands as in a prompt, as this checkpoint’s own chat template writes
an image part (dew.data.chat.image_text), which media expands to the image’s tokens.
Processor.chat
Section titled “Processor.chat”def chat( messages: Sequence[Mapping[str, object]], *, add_generation_prompt: bool = True, **template_options: JSON = {},) -> ModelInputsApply the checkpoint’s own chat template and processor to messages and return numeric inputs.
The checkpoint’s template interprets template options such as
reasoning_effort and preserve_thinking. Messages with media go
through the same processor and numeric normalization as plain text;
text alone is tokenized to NumPy arrays, without Torch.
Processor.from_hf
Section titled “Processor.from_hf”def from_hf(values: Mapping[str, object]) -> ModelInputsCheck a processor’s raw outputs and turn them into ModelInputs for the device.
A field with no native model input, or input_ids that are not
nonempty integer [B, S] rows, raises ValueError.
Processor.decode
Section titled “Processor.decode”def decode(tokens: jax.typing.ArrayLike) -> list[str]Decode integer [B, S] token rows with the processor’s tokenizer, skipping special tokens.
Processor.spelling
Section titled “Processor.spelling”def spelling(ids: Sequence[int]) -> strThe text the source’s tokenizer decodes ids to, its special tokens spelled out, as
transformers’ decode gives it by default.
Processor.encode
Section titled “Processor.encode”def encode(text: str, *, specials: bool) -> list[int]text’s ids from the source’s tokenizer: with the special tokens its encoding adds around
a sequence where specials (a BOS it opens with, an EOS it closes with, as T5’s does), and
none otherwise.
Processor.save_pretrained
Section titled “Processor.save_pretrained”def save_pretrained(directory: str | Path) -> NoneSave the tokenizer and the source’s unchanged media processor files.
SourceReference
Section titled “SourceReference”class SourceReference( name: str, revision: str | None = None, subfolder: str | None = None, remote_code: bool = False,)A local directory or Hub repository, its pinned revision and selected component folder. Saved processor settings keep this record, not a string that has to be parsed again.
remote_code: bool-
Whether its load ran the source’s own code (
Pretrained.load(trust_remote_code=True)), which a processor reloaded from this record runs again only where the process trusts the source (pretrained.load_processor,dew.registry.trusts_source).
SourceReference.parse
Section titled “SourceReference.parse”def parse(source: str) -> SourceReferenceRead a user-provided repo@revision spelling once, at the input boundary.
SourceReference.metadata
Section titled “SourceReference.metadata”def metadata() -> PathSourceReference.pinned
Section titled “SourceReference.pinned”def pinned() -> SourceReferenceThis source at the commit its revision resolves to now, as a run records it (hub_commit). A
directory, local or on storage a URI names (a saved Dew run’s on a bucket), or a source named at
a commit, is as it is: no Hub repository’s id holds a scheme.
SourceReference.cached
Section titled “SourceReference.cached”def cached() -> PathThe cache’s snapshot folder of this source’s commit (pinned first), where its files land as
they are fetched (file), with none fetched here.
SourceReference.spelled
Section titled “SourceReference.spelled”def spelled() -> strThe repo@revision spelling parse reads back, or the name alone.
SourceReference.directory
Section titled “SourceReference.directory”def directory(root: Path) -> PathSourceReference.component
Section titled “SourceReference.component”def component(folder: str) -> SourceReferenceThe same snapshot, selecting a component below this source’s folder.
SourceReference.file
Section titled “SourceReference.file”def file(root: Path, filename: str) -> PathResolve a component file against the pinned snapshot root, not its folder name.
SourceReference.optional_file
Section titled “SourceReference.optional_file”def optional_file(root: Path, filename: str) -> Path | NoneA file, or proven absence at the pinned source. A file the pinned snapshot already holds needs no Hub lookup; an offline lookup for one it lacks raises rather than treating an uncached file as absent and initializing replacement parameters.
SourceReference.weights
Section titled “SourceReference.weights”def weights(root: Path, components: tuple[str, ...] = ('',)) -> PathThe pinned root with exactly the requested component weights present.
load_params
Section titled “load_params”def load_params(path) -> ParamTreeRead a safetensors file back into a nested parameter dict.
Leaves are read-only views of the file in their stored dtype, so nothing is placed on a device until the caller asks for it.
save_hf_layout
Section titled “save_hf_layout”def save_hf_layout( params, config: Mapping[str, object], directory, max_shard_size: int | str = MAX_SHARD_SIZE,) -> NoneWrite the weights and config.json into directory, the layout a Hugging Face style loader reads.
save_sharded writes the weights, as one file or as shards of at most
max_shard_size, and every file is replaced whole (dew.files.replacing), so a reader of the
directory never reads one half written. params is a flat table of named tensors, or a tree
whose ’/‘-joined paths name them. The config is written as given; Dew
does not translate its own config vocabulary into anyone else’s.
save_params
Section titled “save_params”def save_params(params, path) -> NoneWrite a parameter tree to a safetensors file, one tensor per leaf.
translate_config
Section titled “translate_config”def translate_config(hf_config: Mapping[str, object]) -> DecoderFieldsTranslate one registered family’s config, refusing any setting Dew does not compute.
translate_weights
Section titled “translate_weights”def translate_weights( hf_tensors: Mapping[str, Stored], config: DecoderFields, model_type: str | DecoderFamily | None = None, *, param_dtype: str = 'float32', lazy: bool = False, checked: Checked = NOTHING_CHECKED,) -> VariablesMap HF tensors into a CausalTransformer tree, with parameters in FP32 by
default: read_decoder’s tree.