weights

name	weights
description	Guide for the weight lifecycle — downloading trained weights from Tinker, merging LoRA adapters into HuggingFace models, and publishing to HuggingFace Hub. Use when the user asks about exporting, downloading, merging, or publishing trained model weights.

Weight Lifecycle

The tinker_cookbook.weights subpackage provides a standard pipeline for trained weight management: download → build → publish.

Reference

Read these for details:

• tinker_cookbook/weights/__init__.py — API overview and workflow example
• tinker_cookbook/weights/_download.py — Download implementation
• tinker_cookbook/weights/_export.py — LoRA merge implementation
• tinker_cookbook/weights/_publish.py — HuggingFace Hub publish
• docs/download-weights.mdx — Download guide
• docs/publish-weights.mdx — Publishing guide
• docs/save-load.mdx — Checkpointing (save_weights_for_sampler vs save_state)

Full workflow

from tinker_cookbook import weights

# Step 1: Download adapter from Tinker
adapter_dir = weights.download(
    tinker_path="tinker://run-id/sampler_weights/final",
    output_dir="./adapter",
)

# Step 2: Merge LoRA adapter into base model
weights.build_hf_model(
    base_model="Qwen/Qwen3.5-35B-A3B",
    adapter_path=adapter_dir,
    output_path="./model",
    dtype="bfloat16",  # or "float16", "float32"
)

# Step 3: Publish to HuggingFace Hub
url = weights.publish_to_hf_hub(
    model_path="./model",
    repo_id="user/my-finetuned-model",
    private=True,
)

API reference

weights.download()

Downloads and extracts a checkpoint archive from Tinker.

adapter_dir = weights.download(
    tinker_path="tinker://run-id/sampler_weights/final",  # Tinker checkpoint path
    output_dir="./adapter",      # Local directory to extract to
    base_url=None,               # Optional custom Tinker API URL
)
# Returns: path to extracted directory

weights.build_hf_model()

Merges a LoRA adapter into a base model, producing a full HuggingFace model.

weights.build_hf_model(
    base_model="Qwen/Qwen3-8B",     # HF model name or local path
    adapter_path="./adapter",        # Directory with adapter_model.safetensors
    output_path="./model",           # Where to save merged model
    dtype="bfloat16",                # Weight dtype
    trust_remote_code=None,          # Override HF_TRUST_REMOTE_CODE
)

weights.publish_to_hf_hub()

Pushes a local model directory to HuggingFace Hub.

url = weights.publish_to_hf_hub(
    model_path="./model",                    # Local model directory
    repo_id="user/my-finetuned-model",       # HF repo ID
    private=True,                            # Private repo
    token=None,                              # HF token (uses HF_TOKEN env var if None)
)
# Returns: URL to published repo

weights.build_lora_adapter() (not yet implemented)

Convert Tinker LoRA adapter to standard format for vLLM/SGLang. Currently raises NotImplementedError — use build_hf_model() instead.

Checkpoint types (during training)

During training, there are two types of checkpoints:

• save_state() — Full state (weights + optimizer). Used for resuming training.
• save_weights_for_sampler() — Weights only. Used for sampling and export.

The weights.download() function works with sampler weights (save_weights_for_sampler checkpoints).

Common pitfalls

• download() expects a tinker:// path from save_weights_for_sampler, not save_state
• build_hf_model() requires the base model to be downloadable from HuggingFace
• Set HF_TOKEN environment variable for private models and publishing
• dtype="bfloat16" is recommended for most models