# CLAUDE.md: Hugging Face Transformers project

## Commands
`uv run pytest -q` · `uv run ruff check .` · quick inference smoke test: `uv run python scripts/smoke.py --model <small-model-id>`

## Loading models
- Use `Auto*` classes (`AutoTokenizer`, `AutoModelForCausalLM`, `AutoModelForSequenceClassification`) with the model id and a pinned `revision` (commit hash or tag) from config.
- `trust_remote_code=False` unless the user explicitly approves a model that needs it.
- Choose precision and placement explicitly: `dtype=torch.bfloat16` (older versions call it `torch_dtype`) and `device_map="auto"` for large models; CPU-friendly small models in tests.
- Load once and reuse; never load a model inside a request handler or loop.
- Prefer `safetensors` weights; don't load untrusted pickle `.bin` checkpoints.

## Inference
- Tokenize with `padding`/`truncation`/`max_length` set; batch inputs. Use the tokenizer's chat template (`apply_chat_template`) for chat models.
- `model.eval()` and `torch.inference_mode()`; set `max_new_tokens` and sampling params explicitly in `generate`.
- For serving, consider the project's inference server (TGI, vLLM) instead of raw `generate` in a web process.

## Data
- `datasets.load_dataset` with explicit splits; preprocess with `.map(batched=True, num_proc=...)`; cache in the project data dir.

## Rules
- `HF_TOKEN` from env only; never print it. Respect model licenses and gated-model terms.
- Ask before downloading models larger than ~2 GB or starting GPU jobs.