Scope
Metalhead ports what a checkpoint determines, and checks it against PyTorch. It doesn't reimplement the general-purpose machinery of timm, transformers, diffusers and sentence-transformers. A feature belongs in Metalhead when both of these hold:
- The checkpoint determines it: through its configuration, its weights, or upstream code specific to its architecture.
- Getting it wrong would silently change the results compared with the Python library, so it has to be validated against them.
In scope:
- Architectures, their configurations and weights, and the feature interface of image and language models (
forward_features,forward_intermediates, ...). - The inference preprocessing that a checkpoint's configuration sets: resizing, cropping, normalising, and the packing of inputs: the token indices and padding of a batch of texts, and what is specific to a model, such as image patches and image placeholder tokens.
- The post-processing specific to a model, such as SAM 3's masks and boxes.
- The schedulers and sampling loops of the ported diffusion pipelines. The sampler, not the denoiser alone, defines the image. A scheduler is ported along with a pipeline that uses it, not on its own.
- The text embeddings of sentence-transformers models. sentence-transformers is a library of its own, but a checkpoint sets how its embeddings are made, and getting it wrong changes them silently: the pipeline of its
modules.json(the pooling of the token embeddings, its mode,Denseprojections and normalization), the truncation and lowercasing ofsentence_bert_config.json, and the prompts and similarity function ofconfig_sentence_transformers.json. Metalhead reads them strictly and computes the embeddings as sentence-transformers'encodedoes. - The key-value cache of language models (not implemented yet).
Out of scope, for other packages:
- Tokenization algorithms. HuggingFaceTokenizers.jl tokenizes, and Metalhead uses it through an extension.
- Chat templates, and decoding strategies such as beam search, logits processors and streaming.
- Training: optimizers, learning-rate schedules, losses, weight averaging and training loops, which Flux, Optimisers.jl and ParameterSchedulers.jl provide. The models are ordinary differentiable Flux models.
- Data augmentation, data loading and image I/O, which DataAugmentation.jl, MLUtils.jl and FileIO.jl provide.
- Task APIs such as transformers'
pipeline, quantization, LoRA and distributed training. - The rest of sentence-transformers: training and its losses, evaluators, semantic search and similarity utilities other than the similarity function a model sets, quantized embeddings, and multi-process encoding.
General-purpose code that matching PyTorch requires, such as PIL's resampling filters, stays internal rather than public. Architectures are added once a checkpoint validates them; the goal is not to cover each library's whole model collection.