Philosophy

Transformers is a PyTorch-first library. Hugging Face aims for models that are faithful to their papers, easy to use, and easy to hack.

Adapted for this playbook from the 🤗 Transformers documentation by Hugging Face. Official page: https://huggingface.co/docs/transformers/philosophy. Images © Hugging Face (documentation-images) unless noted. This is not a substitute for the upstream docs — verify against the current version.

Covers Hugging Face pages: philosophy

Executive summary

Expect three core classes per architecture (configuration, model, preprocessor), two high-level APIs (Pipeline and Trainer), and tenets that favour readable modelling files over heavy abstraction.

Who it is for

• Researchers and educators extending architectures
• Practitioners fine-tuning, evaluating or serving models
• Engineers who want a pretrained model with a predictable API

Three core classes

Class	Role
Configuration	Hyperparameters (layers, hidden size, …)
Model	torch.nn.Module wrapped by PreTrainedModel
Preprocessor	Tokenizer, image/video processor, feature extractor, or multimodal processor

All support:

• from_pretrained() — download/cache/load from Hub or disk
• save_pretrained() — write a local folder
• push_to_hub() — share to the Hub

High-level APIs

• pipeline — task inference with sensible defaults
• Trainer — train / fine-tune PyTorch models with mixed precision, compile, FlashAttention, distributed helpers

Core tenets (Hugging Face)

From the official philosophy (also expanded in the Transformers tenets space):

1. Source of truth — faithful to official results and intended behaviour
2. One model, one file — core logic readable top-to-bottom
3. Code is the product — optimise for reading and diffing
4. Standardise, don’t abstract — model-specific behaviour stays in the model
5. DRY* (repeat when it helps users) — end-user modelling files stay self-contained; infra is factored out
6. Minimal user API — few code paths, predictable kwargs
7. Backwards compatibility — Hub artefacts keep working
8. Consistent public surface — naming, outputs, diagnostics aligned

Modular Transformers

Contributors write a small modular_*.py shard; the library expands it into the visible modeling_*.py users read. That preserves “one model, one file” without boilerplate drift. See Hugging Face’s modular transformers guide.

Enterprise takeaway

Standardising on Transformers reduces vendor lock-in at the definition layer: the same checkpoint can move between research notebooks, Trainer jobs and production engines that consume Hugging Face model definitions.

Key takeaways

• Configuration + model + preprocessor is the universal pattern.
• Pipeline and Trainer sit on top of those classes.
• Readable modelling files are intentional — use them when debugging.

What to do next

Load your first checkpoint in Loading models.