Skip to content

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.

NameSummary
PretrainedA native model with explicit variables and its checkpoint’s host processor.
PretrainedBlockDecoderA DiffusionGemma source, which decodes whole canvases.
PretrainedDecisionA native backbone bundle with its readout and declared decision task.
PretrainedDecoderAn autoregressive decoder, alone or inside a multimodal wrapper.
PretrainedFallbackA causal LM run as transformers’ PyTorch forward, lowered to JAX by torchax (tier 3).
PretrainedMaskedDecoderA masked-diffusion decoder (LLaDA, Dream).
PretrainedPipelineA latent diffusion pipeline: the denoiser as model, with its process, conditions and autoencoder.
ProcessorRuns a checkpoint’s own processor on the host and arranges its outputs as native model inputs.
SourceReferenceA local directory or Hub repository, its pinned revision and selected component folder.
load_paramsRead a safetensors file back into a nested parameter dict.
save_hf_layoutWrite the weights and config.json into directory, the layout a Hugging Face style loader reads.
save_paramsWrite a parameter tree to a safetensors file, one tensor per leaf.
translate_configTranslate one registered family’s config, refusing any setting Dew does not compute.
translate_weightsMap HF tensors into a CausalTransformer tree, with parameters in FP32 by default: read_decoder’s tree.

dataclass source

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(),
quantized_specs: Mapping[str, jax.ShapeDtypeStruct] = 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 save to 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 export writes through, installed by the route that built the model, or None for weight_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. save writes 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.

quantized_specs: Mapping[str, jax.ShapeDtypeStruct]

The stored tensors of each of quantized_tensors as the source’s headers state them: the tensors an export writes the weight back as, known before any is encoded (SourceQuantization.requantize).

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 adapt attached to the model, or None for the source as published.

The variables hold its factors under params, next to the base weights under frozen.

tokenizer: str | decoders.ExportTokenizer | None

The vocabulary save writes 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), which save writes 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 model drawn fresh beside the loaded weights, by their paths under params (layers_1/cross_attention): what with_cross_attention adds, 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). An export writes it beside its config and a load reads it back (dew.interop.release, ledger 4314).

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, where model_config keeps 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 tokenizer names (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 and unet.<module> for a pipeline component. A published adapter file uses these names, so dew.lora attaches a low-rank delta through them.

def map_variables(transform: Callable[[Variables], Variables]) -> Self

This bundle with its variable tree transformed, for placement or a shape-only load. Composite bundles apply the same transformation to each component.

def pipeline() -> SavedTask

The native task declared by this source kind.

def formed(task: TaskT) -> TaskT

task, built from this source, under the numerics its load was asked for (numerics) where it traces under numerics (dew.inference.tasks.InItsForm).

def packed() -> Self

A serving view with packed projections, preserving this bundle’s arrays for reuse.

def from_run(
directory: str | Path,
*,
step: int | str | None = None,
ema: bool | None = None,
trust: Sequence[str] = (),
) -> Self

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

def from_saved(
run: SavedRun,
*,
ema: bool | None = None,
mesh: MeshSpec | Mesh | None = None,
layout: Layout | None = None,
) -> Self

Return the pinned checkpoint run (SavedRun.pinned), rebuilt from the run’s own inference record, in the layout of the architecture the record names.

def bound(model: nn.Module, variables: Variables) -> Self

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

def load(
name_or_dir: str | Path,
*,
dtype: DTypeLike | None = None,
param_dtype: DTypeLike | Literal['auto'] | None = None,
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,
) -> Self

Load 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: BF16 over FP32 master weights unless stated, or an exported run’s own (load_settings); ‘auto’ keeps each tensor’s stored dtype; 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).

def adapt(lora: LoRA, *, key: int | jax.Array) -> Self

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

def with_cross_attention(
cross: CrossBlocks,
*,
key: int | jax.Array,
frozen: bool = True,
) -> Self

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

def with_dex(extension: DifferentialExtension, *, key: int | jax.Array) -> Self

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

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

def save(
directory: str | Path,
*,
variables: Mapping[str, object] | None = None,
max_shard_size: int | str = MAX_SHARD_SIZE,
) -> None

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

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,
) -> None

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

dataclass source

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(),
quantized_specs: Mapping[str, jax.ShapeDtypeStruct] = 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.

def pipeline()
def block_generation() -> BlockGeneration

Build the DiffusionGemma canvas task, with the source’s sampler config as its default, a saved run’s its own declaration (settings).

dataclass source

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(),
quantized_specs: Mapping[str, jax.ShapeDtypeStruct] = 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: save writes the format it was read from.

exporter: Callable[..., Mapping[str, np.ndarray]]

The release format’s tensors, writer’s own: export returns what save writes.

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.

def map_variables(transform: Callable[[Variables], Variables]) -> Self
def backbone() -> Pretrained

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

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.

def pipeline() -> Decide
def save(
directory: str | Path,
*,
variables: Mapping[str, object] | None = None,
max_shard_size: int | str = MAX_SHARD_SIZE,
) -> None
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(),
) -> Self

dataclass source

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(),
quantized_specs: Mapping[str, jax.ShapeDtypeStruct] = 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.

def pipeline()
def from_model(
model: nn.Module,
variables: Variables,
*,
tokenizer: str | decoders.ExportTokenizer | None = None,
generation_config: Mapping[str, object] | None = None,
) -> PretrainedDecoder

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

def text_generation(*, sampling: Sampling | None = None) -> TextGeneration

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

dataclass source

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(),
quantized_specs: Mapping[str, jax.ShapeDtypeStruct] = 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).

def pipeline()
def text_generation(*, sampling: Sampling | None = None) -> TextGeneration

The text generation task this source describes, as a native decoder’s (PretrainedDecoder.text_generation).

dataclass source

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(),
quantized_specs: Mapping[str, jax.ShapeDtypeStruct] = 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_walk of its config, its generation config and its own code: LLaDA2.0’s blocks, Dream’s origin), or None for a source whose family declares none, an unregistered one among them, which unmasks the whole response with Dew’s MDLM.

def pipeline()
def text_generation() -> MaskedGeneration

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

dataclass source

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(),
quantized_specs: Mapping[str, jax.ShapeDtypeStruct] = 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).

def pipeline()
def text_to_image() -> TextToImage

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

def export(variables: Mapping[str, object] | None = None) -> Mapping[str, np.ndarray]
def save(
directory: str | Path,
*,
variables: Mapping[str, object] | None = None,
max_shard_size: int | str = MAX_SHARD_SIZE,
) -> None

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

dataclass source

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 source records their identity.

pools_frames: bool

Whether the source’s tower pools an item’s frames into one frame’s tokens (TowerGeometry.pools_frames).

bos_id: int | None

The id the source’s tokenizer starts a sequence with, or None.

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.

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: its processor’s own, or, for a processor whose public call takes its media as medias (Kimi K2.5’s release’s), the fields that call gives as the other processors give them (_medias_fields).

def image_text() -> str

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

def chat(
messages: Sequence[Mapping[str, object]],
*,
add_generation_prompt: bool = True,
**template_options: JSON = {},
) -> ModelInputs

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

def from_hf(values: Mapping[str, object]) -> ModelInputs

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

def decode(tokens: jax.typing.ArrayLike) -> list[str]

Decode integer [B, S] token rows with the processor’s tokenizer, skipping special tokens.

def spelling(ids: Sequence[int]) -> str

The text the source’s tokenizer decodes ids to, its special tokens spelled out, as transformers’ decode gives it by default.

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.

def save_pretrained(directory: str | Path) -> None

Save the tokenizer and the source’s unchanged media processor files.

dataclass source

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

def parse(source: str) -> SourceReference

Read a user-provided repo@revision spelling once, at the input boundary.

def metadata() -> Path
def pinned() -> SourceReference

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

def cached() -> Path

The cache’s snapshot folder of this source’s commit (pinned first), where its files land as they are fetched (file), with none fetched here.

def spelled() -> str

The repo@revision spelling parse reads back, or the name alone.

def directory(root: Path) -> Path
def component(folder: str) -> SourceReference

The same snapshot, selecting a component below this source’s folder.

def file(root: Path, filename: str) -> Path

Resolve a component file against the pinned snapshot root, not its folder name.

def optional_file(root: Path, filename: str) -> Path | None

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

def weights(root: Path, components: tuple[str, ...] = ('',)) -> Path

The pinned root with exactly the requested component weights present.

function source

def load_params(path) -> ParamTree

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

function source

def save_hf_layout(
params,
config: Mapping[str, object],
directory,
max_shard_size: int | str = MAX_SHARD_SIZE,
) -> None

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

function source

def save_params(params, path) -> None

Write a parameter tree to a safetensors file, one tensor per leaf.

function source

def translate_config(hf_config: Mapping[str, object]) -> DecoderFields

Translate one registered family’s config, refusing any setting Dew does not compute.

function source

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,
) -> Variables

Map HF tensors into a CausalTransformer tree, with parameters in FP32 by default: read_decoder’s tree.