1# Tinker Format Specification
2 
3This reference documents the exact data structures required for Tinker supervised fine-tuning.
4 
5## Core Data Types
6 
7### Datum
8 
9The fundamental training unit in Tinker:
10 
11```python
12from tinker import types
13 
14datum = types.Datum(
15    model_input=types.ModelInput.from_ints(tokens=input_tokens),
16    loss_fn_inputs={
17        "target_tokens": target_tokens,  # List[int] - shifted by 1 for next-token prediction
18        "weights": weights               # List[float] - 0.0 for prompt, 1.0 for completion
19    }
20)
21```
22 
23### ModelInput
24 
25Container for tokenized input:
26 
27```python
28# Simple text-only input
29model_input = types.ModelInput.from_ints(tokens=[...])
30 
31# Multi-modal (for VLMs)
32model_input = types.ModelInput(chunks=[
33    types.EncodedTextChunk(tokens=[...]),
34    types.ImageChunk(data=image_bytes, format="png"),
35    types.EncodedTextChunk(tokens=[...])
36])
37```
38 
39### Token Weight Assignment
40 
41The weights array determines which tokens contribute to the loss:
42 
43| Token Type | Weight | Description |
44|------------|--------|-------------|
45| System prompt | 0.0 | Context, not learned |
46| User message | 0.0 | Input prompt |
47| Assistant message | 1.0 | Target completion |
48| Special tokens | 0.0 | EOS, BOS, delimiters |
49 
50## Renderer System
51 
52Tinker uses renderers to convert message lists to tokens with proper weights.
53 
54### Using Built-in Renderers
55 
56```python
57from tinker_cookbook import renderers, tokenizer_utils
58 
59# Get tokenizer for your model
60tokenizer = tokenizer_utils.get_tokenizer("meta-llama/Llama-3.1-8B-Instruct")
61 
62# Get appropriate renderer
63renderer = renderers.get_renderer("llama3", tokenizer)
64 
65# Convert messages to training format
66messages = [
67    {"role": "system", "content": "You are a creative writer..."},
68    {"role": "user", "content": "Write a 500 word excerpt..."},
69    {"role": "assistant", "content": "The actual book text..."}
70]
71 
72model_input, weights = renderer.build_supervised_example(messages)
73```
74 
75### Renderer Output Visualization
76 
77The renderer assigns weights per-token:
78 
79```
80Token          Weight
81<|im_start|>   0.0
82system         0.0
83\n             0.0
84You are...     0.0
85<|im_end|>     0.0
86...            ...
87<|im_start|>   0.0
88assistant      0.0
89\n             0.0
90The actual     1.0    <- Completion starts
91book text      1.0
92...            1.0
93<|im_end|>     1.0    <- Final token weighted
94```
95 
96## JSONL Format
97 
98For batch processing, use standard conversation JSONL:
99 
100```json
101{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}
102{"messages": [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}
103```
104 
105### Converting JSONL to Datum
106 
107```python
108import json
109from tinker import types
110from tinker_cookbook import renderers, tokenizer_utils
111 
112def load_dataset(jsonl_path: str, model_name: str) -> list[types.Datum]:
113    """Load JSONL and convert to Tinker Datum objects."""
114    
115    tokenizer = tokenizer_utils.get_tokenizer(model_name)
116    renderer = renderers.get_renderer("llama3", tokenizer)
117    
118    data = []
119    with open(jsonl_path) as f:
120        for line in f:
121            example = json.loads(line)
122            messages = example["messages"]
123            
124            model_input, weights = renderer.build_supervised_example(messages)
125            
126            # Get token sequences
127            input_tokens = model_input.to_ints()
128            target_tokens = input_tokens[1:]  # Shift for next-token prediction
129            input_tokens = input_tokens[:-1]
130            weights = weights[1:]  # Align weights with targets
131            
132            datum = types.Datum(
133                model_input=types.ModelInput.from_ints(tokens=input_tokens),
134                loss_fn_inputs={
135                    "target_tokens": target_tokens,
136                    "weights": weights
137                }
138            )
139            data.append(datum)
140    
141    return data
142```
143 
144## Training Loop Integration
145 
146```python
147import tinker
148from tinker import types
149 
150async def train_on_book_dataset(
151    dataset: list[types.Datum],
152    model_name: str,
153    learning_rate: float = 1e-4,
154    epochs: int = 1
155):
156    """Train on book SFT dataset."""
157    
158    service_client = tinker.ServiceClient()
159    training_client = await service_client.create_lora_training_client_async(
160        base_model=model_name,
161        rank=32
162    )
163    
164    for epoch in range(epochs):
165        for batch_start in range(0, len(dataset), 1):  # Batch size 1
166            batch = dataset[batch_start:batch_start + 1]
167            
168            # Forward-backward with cross-entropy loss
169            fwd_bwd_future = await training_client.forward_backward_async(
170                batch, 
171                loss_fn="cross_entropy"
172            )
173            
174            # Optimizer step with aggressive learning rate
175            optim_future = await training_client.optim_step_async(
176                types.AdamParams(learning_rate=learning_rate * 2.0)
177            )
178            
179            # Wait for completion
180            fwd_bwd_result = await fwd_bwd_future
181            optim_result = await optim_future
182```
183 
184## Key Constraints
185 
1861. **Batch Size**: Use 1 for style transfer. Larger batches average out stylistic gradients.
187 
1882. **Sequence Length**: Keep chunks under 1000 tokens. Longer sequences dilute local style patterns.
189 
1903. **Learning Rate**: Use 2x multiplier (e.g., 2e-4 instead of 1e-4) for faster style convergence.
191 
1924. **Token Alignment**: Target tokens must be shifted by 1 position from input tokens.
193 
1945. **Weight Precision**: Weights should be float32, typically 0.0 or 1.0.
195 
196## Model Selection
197 
198For book SFT, consider:
199 
200| Model | Use Case |
201|-------|----------|
202| meta-llama/Llama-3.1-8B-Instruct | General style transfer |
203| Qwen/Qwen3-30B-A3B | Higher quality, MoE efficiency |
204| GPT-4o (via OpenAI) | Data generation only, not Tinker |
205 
206## References
207 
208- Tinker Cookbook: `tinker_cookbook/supervised/train.py`
209- Renderer implementations: `tinker_cookbook/renderers.py`
210- Type definitions: `tinker/types.py`
211 
212