tinker_cookbook 0.1.0__tar.gz

tinker_cookbook-0.1.0/.github/workflows/claude-review.yml

@@ -0,0 +1,82 @@
+name: Claude Code
+
+permissions:
+  contents: write        # allow Claude to edit files & push commits
+  pull-requests: write   # allow PR comments/reviews & PR creation
+  issues: write          # allow issue comments & labels
+
+  id-token: write       # Necessary because otherwise we get:
+    # Error: Failed to setup GitHub token: Error: Could not fetch an OIDC token. Did you remember to add `id-token: write` to your workflow permissions?
+    # If you instead wish to use this action with a custom GitHub token or custom GitHub app, provide a `github_token` in the `uses` section of the app in your workflow yml file.
+  actions: read
+    # ^^^ Not sure if this is necessary, but my previous working configuration had it.
+
+on:
+  # 1) Automatic PR review (non‑excessive)
+  pull_request:
+    types: [opened, reopened, ready_for_review]
+
+  # 2) Talk to @claude in PRs & issues
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened]
+
+env:
+  # Shared Claude CLI configuration for all jobs
+  CLAUDE_ARGS_COMMON: >
+    --max-turns 50
+    --allowedTools "Read" "Write" "Edit" "MultiEdit"
+    "Glob" "Grep" "LS"
+    "Bash(git:*)" "Bash(gh:*)"
+    "mcp__github_inline_comment__create_inline_comment"
+
+jobs:
+  pr_review:
+    name: Automatic PR review
+    runs-on: ubuntu-latest
+    # Only run this job for pull_request events
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Claude PR review
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # Official slash command for PR review (context comes from the PR event)
+          # https://code.claude.com/docs/en/github-actions#using-slash-commands
+          prompt: "/review"
+          claude_args: ${{ env.CLAUDE_ARGS_COMMON }}
+          track_progress: true
+          show_full_output: true
+
+  claude_mention:
+    name: Respond to @claude in issues & PRs
+    runs-on: ubuntu-latest
+    # Only run when @claude actually appears
+    if: >
+      (github.event_name == 'issue_comment' &&
+       contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' &&
+       contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'issues' &&
+       contains(github.event.issue.body, '@claude'))
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Claude on @mention
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # No prompt → action switches to "tag" mode and responds to @claude
+          # https://code.claude.com/docs/en/github-actions#configuration-examples
+          claude_args: ${{ env.CLAUDE_ARGS_COMMON }}

tinker_cookbook-0.1.0/.github/workflows/pre-commit.yaml

@@ -0,0 +1,17 @@
+name: pre-commit
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: pre-commit
+      uses: pre-commit/action@v3.0.1

tinker_cookbook-0.1.0/.github/workflows/pyright.yaml

@@ -0,0 +1,25 @@
+name: pyright
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  type-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: install-uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: venv
+        run: uv venv && uv sync --all-extras
+
+      - name: pyright
+        run: uv run pyright

tinker_cookbook-0.1.0/.gitignore

@@ -0,0 +1 @@
+**/__pycache__

tinker_cookbook-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+    - id: check-added-large-files
+      args: ["--maxkb=500"]
+    - id: end-of-file-fixer
+      exclude: |
+          (?x)
+          ^(
+            \.sync_state
+          )$
+    - id: trailing-whitespace
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.13.2
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+    # Run the formatter.
+    - id: ruff-format

tinker_cookbook-0.1.0/.sync_state

@@ -0,0 +1,4 @@
+{
+  "last_synced_sha": "b4fee215e812ae5a6b0096ba37b3d9edc4f99cd5",
+  "last_sync_time": "2025-10-09T00:09:30.116486"
+}

tinker_cookbook-0.1.0/AGENTS.md

@@ -0,0 +1,134 @@
+# Tinker Cookbook Agent Guide
+
+Working notes for future agents hacking on `tinker-cookbook`. Additional docs can be found in the `llms.txt` (condensed) / `llms-full.txt` (complete), `CONTRIBUTING`, and the bundled documentation.
+
+## Mission & Scope
+- `tinker-cookbook` is the client-side layer for the hosted **Tinker** service. You author training/eval loops that run on a CPU machine; Tinker executes the heavy GPU work (LoRA fine-tuning, sampling, checkpointing) on synchronized worker pools (a.k.a. clock cycles).
+- The cookbook must mirror the public docs. Both `llms.txt` and `llms-full.txt` are autogenerated outside this repo—treat them as read-only and coordinate with maintainers when they need a refresh.
+- Primary users: (1) researchers cloning recipes and swapping in their data/envs; (2) SDK developers extending abstractions like renderers, datasets, evaluators, completers.
+
+## Tooling & Setup
+- Python ≥3.11. Follow the onboarding instructions: join the waitlist, create a `TINKER_API_KEY` in the console, `pip install tinker`, then `pip install -e .[dev]` (or `uv pip install -e .[dev]`). Most contributors already have the env variable set; if requests fail with auth errors, re-export it.
+- Optional extras (`vector-search`, `wandb`, `verifiers`, etc.) are defined in `pyproject.toml`.
+- CLI utilities expect datasets, logs, and checkpoints to live under user-controlled paths (default `/tmp/tinker-examples/...`). Clean up disk usage between runs.
+- Heavy examples (smoke tests, RL recipes) download Hugging Face datasets and call the hosted API; run them only when you have network+API access.
+
+## Architecture & Patterns
+- **Builder pattern (per CONTRIBUTING):**
+  - Config objects are lightweight `chz` dataclasses (e.g., `SupervisedDatasetBuilder`, `RLDatasetBuilder`, `EnvGroupBuilder`, `EvaluatorBuilder`). They capture parameters, stay serializable, and usually expose a `.build()`/`__call__()` that returns heavyweight runtime objects.
+  - Launch scripts define a CLI-facing `CLIConfig` (parsed by `chz`) that instantiates the richer training `Config`. This gives every recipe a consistent `python -m ... key=value` interface.
+  - Env builders compose like `RLDatasetBuilder → EnvGroupBuilder → Env`. Groups let us share metadata (tags, pairwise comparisons) and center rewards across related rollouts.
+- **Completers:** algorithms interact with the `TokenCompleter` interface. `TinkerTokenCompleter` (wrapping a `SamplingClient`) is the default implementation, but evaluators may accept any `TokenCompleter` or `MessageCompleter`.
+- **Renderers & tokenizer utils:** pick the renderer that matches your tokenizer/model pair (e.g., `role_colon`, `llama3`, `qwen3`). `TrainOnWhat` controls which tokens get weight=1 in SFT. Tokenizers are cached via `tokenizer_utils.get_tokenizer`, with Llama-3 names remapped to `thinkingmachineslabinc/meta-llama-3-tokenizer` to bypass HF gating.
+- **Loss plumbing:** every `tinker.Datum` bundles a `model_input` plus `loss_fn_inputs` (`TensorData`). Use helpers such as `conversation_to_datum`, `datum_from_tokens_weights`, and `_remove_mask` instead of constructing dicts manually. Built-in losses: `cross_entropy`, `importance_sampling`, `ppo`; `forward_backward_custom` covers bespoke differentiable objectives.
+
+## Conventions & Notation (from CONTRIBUTING)
+- **Subscripts:** `_P` (problems/prompts), `_G` (groups of rollouts sharing metadata), `_T` (tokens/time), `_D` (datums), with flattened forms like `_PG`. Example: `tokens_P_G_T[p][g][t]` indexes tokens for problem `p`, group member `g`, token `t`. Keep these suffixes when naming tensors/metrics so downstream tooling can interpret shapes.
+- **Env lifecycle:** `Env` objects are single-use (no `reset`); create them via `EnvGroupBuilder`, which returns correlated envs (for GRPO-style centering or multi-agent comparisons). Datasets return groups, not individual envs.
+- **Typing:** prefer explicit typing, avoid `Any` / `type: ignore`. Keep generics readable. Converters like `TensorData.from_numpy` and helper casting utilities already exist; use them.
+- **`chz` usage:** configuration objects (`Config`, dataset builders, CLI configs) are `@chz.chz` classes so they can be serialized, logged, and hydrated from CLI key-value pairs.
+- **Logging style:** training scripts rely on `ml_log` for metrics (`metrics.jsonl`, optional W&B) and `logtree` for HTML transcripts. When adding new metrics, follow the `ml_log.log_metrics` shape conventions (`str → float/int/str`).
+- **Safe iteration:** functions like `safezip`, `timed`, and `scope` (tracing) are widely used; follow those patterns instead of hand-writing logging/zip logic.
+
+## Data & Rendering
+- Rendering is the bridge between chat-style data and token sequences. `renderers.py` defines `Renderer.build_supervised_example`, `build_generation_prompt`, `get_stop_sequences`, and `parse_response`. Use `TrainOnWhat` to switch between “last assistant only” vs “all assistant messages” vs “prompt distillation” setups.
+- For supervised chat datasets, reuse `SupervisedDatasetFromHFDataset`, `StreamingSupervisedDatasetFromHFDataset`, or `FromConversationFileBuilder`. They expect HF rows with `messages` arrays; map them through a renderer and optional max length.
+- RL data is organized by dimensions `_P` (problems), `_G` (group members / rollouts per problem), `_T` (tokens), `_D` (datums). Keep arrays ragged-aware, and document shape suffixes when introducing new tensors.
+
+## Training Playbooks
+### Supervised Learning
+- **Main loop:** `tinker_cookbook/supervised/train.py`. It pipelines batches by submitting `forward_backward_async` and `optim_step_async` immediately, storing futures inside `SubmittedBatch`. Metrics/logging run through `ml_log`, stdout previews via `display.colorize_example`.
+- **Configs:** include LR schedule (`linear` multiplier via `compute_schedule_lr_multiplier`), LoRA rank, checkpoint cadence (`save_every`), eval cadence (`eval_every`, `infrequent_eval_every`), and dataset builders.
+- **Hyperparameters:** Call `hyperparam_utils.get_lr(model_name)`; LR is independent of LoRA rank.
+- **Prompt distillation:** see `tinker_cookbook/recipes/prompt_distillation`. Renderers assign weight=0 to context instructions and weight=1 to distilled responses.
+- **Sweeps:** `tinker_cookbook/recipes/sl_loop.py` doubles as a sweep harness (log-scale grid, aggregate from `metrics.jsonl`). Keep these scripts runnable; they double as docs tests.
+
+### Reinforcement Learning
+- **Main loop:** `tinker_cookbook/rl/train.py`. Steps: build dataset (`RLDatasetBuilder`), get groups of envs (`EnvGroupBuilder`), collect rollouts (`do_group_rollout`), compute advantages (`compute_advantages`), assemble datums (`assemble_training_data`), run `forward_backward_async(..., loss_fn="importance_sampling" | "ppo")`, apply `optim_step_async`.
+- **Policies:** implement the `TokenCompleter` interface. Training loops usually instantiate `TinkerTokenCompleter`, but tests may stub a completer.
+- **Hyperparameters:** key knobs are `batch_size` vs `group_size`, `num_substeps` (similar to PPO epochs but still single-pass), and advanced configs:
+  - `StreamMinibatchConfig` overlaps sampling with training (still on-policy).
+  - `AsyncConfig` enables bounded off-policy lag (“off-by-K”). Monitor KL metrics (`compute_kl_sample_train`, `compute_post_kl`) plus reward trends to make sure drift stays manageable.
+- **Environments:** `Env`, `EnvGroupBuilder`, and `RLDataset` live in `tinker_cookbook/rl/types.py`. Groups make it easy to compute pairwise rewards (preference models) or multi-agent games. Example: `recipes/multiplayer_rl/twenty_questions`.
+- **Recipes:** `rl_basic.py` demonstrates default metrics: reward, entropy, `ac_tokens_per_turn`, format rate, KL approximations, and progress/time tokens.
+
+### Preferences & Distillation
+- **DPO:** `tinker_cookbook/preference/train_dpo.py` (CLI in `recipes/preference/train.py`). Important knobs: dataset builder (choose whichever comparison corpus you need), `renderer_name`, `dpo_beta`, LR (often 1e-5 to 1e-6). Metrics like `dpo_loss`, `accuracy`, `margin`, `chosen/rejected_reward` come from the implicit reward model.
+- **RLHF pipeline:** `recipes/preference/rlhf/rlhf_pipeline.py` walks through the standard three stages (supervised warm-start, preference model, RL self-play using pairwise comparisons).
+- **Distillation:** `distillation/train_on_policy.py` handles on-policy or SFT-style distillation; combine with `renderers`, `hyperparam_utils`, and `sampling_client` utilities.
+
+### Evaluations & Sampling
+- Inline evaluators implement either `TrainingClientEvaluator` or `SamplingClientEvaluator`. Training loops accept builder lists (`evaluator_builders`, `infrequent_evaluator_builders`). Inspect AI integration is in `eval/inspect_evaluators.py` and `eval/run_inspect_evals.py`.
+- Sampling clients come from `training_client.save_weights_and_get_sampling_client(name=...)`. To export weights, use `RestClient.get_checkpoint_archive_url_from_tinker_path`.
+
+## Async & Performance
+- Worker pools advance in ~10s clock cycles. Submit `forward_backward_async` and `optim_step_async` back-to-back, then await both futures to keep them on the same cycle.
+- Pipeline batches: enqueue the next `forward_backward_async` before awaiting the previous batch’s results so there’s always work when a clock cycle begins.
+- Use async everywhere performance matters (RL loops, production SFT). The synchronous helpers exist only for pedagogy (e.g., `recipes/sl_loop.py`) and small tests.
+
+- Training CLIs (`recipes/*/*.py`) call `cli_utils.check_log_dir` at startup to decide whether to delete, resume, or prompt about an existing `log_path`. This convention is specific to training/eval entry points and is wired through `chz` CLI configs so users can choose behaviors (`delete`, `resume`, `ask`, `raise`).
+- `ml_log` handles structured logging: metrics stream to stdout, `metrics.jsonl`, and optionally Weights & Biases (`wandb_project`, `wandb_name`). Use `logtree` scopes for HTML transcripts when you need qualitative review of rollouts.
+- `checkpoint_utils.save_checkpoint_async` writes `{log_path}/checkpoints.jsonl` entries for state and/or sampler checkpoints. `get_last_checkpoint` filters by key (`state_path`, `sampler_path`) before resuming.
+- After each optimizer step sequence, call `save_weights_for_sampler[_async]` (or `save_weights_and_get_sampling_client`) and then create a **new** sampling client. Existing `SamplingClient`s do not automatically pick up fresh weights, so evaluators must use the newly returned client handle.
+
+## Testing & Troubleshooting
+- Lightweight checks: `pytest tinker_cookbook/tests/test_renderers.py`, `pytest tinker_cookbook/tests/test_utils.py`. `tests/smoke_tests.py` spins up real training runs (needs HF + API access).
+- Example data lives in `tinker_cookbook/example_data/` (e.g., `conversations.jsonl`, `multilingual.txt`) and mirrors the formats documented in `training-sampling`.
+- If you hit auth/network issues, double-check `TINKER_API_KEY`, ensure your environment can reach the Tinker service, and verify dependencies (`pip show tinker`).
+- Resize datasets/batch sizes in recipes when debugging; `dataset_builder` objects usually accept `n_batches`, `batch_size`, and `group_size` fields so you can shrink workloads.
+
+## Common Pitfalls
+- **LoRA LR mismatch:** LoRA typically needs learning rates tens of times higher than full fine-tuning. Use `hyperparam_utils.get_lr` or the LR formula above. Rank does not change the optimal LR.
+- **Renderer/tokenizer mismatch:** The renderer determines BOS/EOS tokens and stop sequences. Pair `renderer_name` with the tokenizer family your model expects (`llama3`, `qwen3`, `role_colon`, etc.). Otherwise loss weights and sampling stops will be wrong.
+- **Loss inputs wrong shape:** Stick to helper functions so `loss_fn_inputs["weights"]`, `["target_tokens"]`, `["advantages"]`, etc., end up as `TensorData` with the right dtype. Custom DPO/RL objectives often fail here.
+- **Async gaps:** Awaiting `forward_backward` before submitting `optim_step` wastes two extra clock cycles. Submit both first, then await results.
+- **Sampler desync:** Saving weights isn’t enough; always request a new sampling client (e.g., via `save_weights_and_get_sampling_client`) before running evals so the client reflects the latest checkpoint.
+- **Group semantics:** RL advantages are centered within each group.
+- **DPO beta / LR:** Too large a beta or LR makes the policy collapse; start with `dpo_beta=0.1`, LR≈1e-5, and watch `accuracy` + `margin` trends.
+
+## Quick Reference Commands
+1. **Environment setup:**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate
+   pip install tinker
+   pip install -e .[dev]
+   # Set once per shell if needed
+   export TINKER_API_KEY=sk-...
+   ```
+2. **Basic SFT run (default recipe):**
+   ```bash
+   python -m tinker_cookbook.recipes.sl_basic \
+     model_name=meta-llama/Llama-3.2-1B \
+     log_path=/tmp/tinker-examples/sl_basic
+   ```
+3. **Custom JSONL SFT (bring your own conversations file):**
+   ```bash
+   python -m tinker_cookbook.recipes.sl_basic \
+     dataset_path=/path/to/conversations.jsonl \
+     renderer_name=role_colon \
+     train_on_what=all_assistant_messages \
+     log_path=/tmp/tinker-examples/sl_jsonl
+   ```
+4. **RL basic run (default reward):**
+   ```bash
+   python -m tinker_cookbook.recipes.rl_basic \
+     model_name=meta-llama/Llama-3.1-8B \
+     log_path=/tmp/tinker-examples/rl_basic
+   ```
+5. **DPO training (generic preference dataset):**
+   ```bash
+   python -m tinker_cookbook.recipes.preference.train \
+     log_path=/tmp/dpo-run \
+     model_name=meta-llama/Llama-3.2-1B \
+     dataset=<preference_dataset> renderer_name=role_colon \
+     learning_rate=1e-5 dpo_beta=0.1
+   ```
+6. **Inspect eval after training:**
+   ```bash
+   python -m tinker_cookbook.eval.run_inspect_evals \
+     model_path=tinker://YOUR_MODEL \
+     model_name=meta-llama/Llama-3.2-1B \
+     tasks=<inspect_task_id> \
+     renderer_name=role_colon
+   ```

tinker_cookbook-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

tinker_cookbook-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Development
+
+This project is built in the spirit of open science and collaborative development. We believe that the best tools emerge through community involvement and shared learning.
+
+We welcome PR contributions after our private beta is over. If you have any feedback, please email us at tinker@thinkingmachines.ai.
+
+## Organization of training scripts
+
+We're designing the codebase with the following goals:
+
+1. Low barrier to entry: it should be dead simple to run something and see numbers go up.
+2. Extensible: it should be possible to pass in custom datasets and evals and control all the hyperparameters.
+3. Science-friendly: it should be easy to run sweeps, and analyze the results.
+
+To achieve this, we'll use the following structure around training scripts:
+
+- There's a main training function, such as [rl/train.py](tinker_cookbook/rl/train.py) or [supervised/train.py](tinker_cookbook/supervised/train.py), which contains the main loop.
+    - This function contains a detailed config object (`Config`), which isn't constructable from the command line.
+    - The config contains members that specify things like datasets and evals. However, these should be chz configs (with a `.build` method that constructs the actual object) or callables (we recommend using functools.partial). This way, the config is serializable, which is useful for sweeps.
+- There are launch scripts that assemble training configs (e.g., [recipes/math_rl/train.py](tinker_cookbook/recipes/math_rl/train.py)), which construct a smaller config object (`CLIConfig`) from the command line.
+
+## Async
+
+Async is very useful for RL, where it allows us to make many queries in parallel (e.g., sampling calls). For all of the interfaces used in RL (such as the `Env` class), all the methods that take nontrivial amounts of time should be async. For some of the other code, such as [recipes/sl_loop.py](tinker_cookbook/recipes/sl_loop.py), we've chosen not to use async methods, just to make it more beginner-friendly, as many python programmers are not familiar with async.
+
+## Typing
+
+Please use typing wherever possible; avoid `Any` and `type: ignore`; prefer casting. However, avoid using convoluted generics or writing code that's much more verbose just to satisfy the type checker. Prefer using single types over union types.
+
+## Classes
+
+There are a lot of different classes, which might make the code feel less approachable. However, they follow *the builder pattern*, and the code should be less confusing when you know the pattern.
+
+We can illustrate the pattern with the two main examples:
+
+- A `SupervisedDatasetBuilder` is a configuration object which builds a `SupervisedDataset`.
+- An `RLDatasetBuilder` is a configuration object which builds an `RLDataset`, which generates batches of `EnvGroupBuilder` objects, which each generate a group of `Env` objects.
+
+Here, the `SupervisedDatasetBuilder`, `RLDatasetBuilder`, and `EnvGroupBuilder` are all configuration objects, which have a `__call__` method that builds another object. You can see these objects in [supervised/types.py](tinker_cookbook/supervised/types.py) and [rl/types.py](tinker_cookbook/rl/types.py).
+
+In general, we use a lot of configuration objects, with a `__call__` method that returns a heavyweight object (like a dataset). We use `chz` for the configuration objects -- it's similar to a dataclass but with some extra features that are nice for configs. We use either dataclasses or regular python classes for the heavyweight objects.
+
+## Envs
+
+An `Env` is an RL environment. For those with an RL background, it roughly corresponds to an MDP or a POMDP, however we use in more general cases (such as multi-agent settings) that don't strictly correspond to the MDP/POMDP formalism. It's roughly analogous the concept of an Env in OpenAI Gym, but unlike OpenAI Gym, we don't have a `reset` method; rather, the env should be discarded after a rollout. Any shared resources should be maintained by whatever object is creating the envs.
+
+The `Env`s are created by `EnvGroupBuilder`s. The group of envs returned by `EnvGroupBuilder` have something in common; either they correspond to the same task (in which case we can use this information for variance reduction, as in GRPO, which centers per group); or, we can use the group to define a multi-agent environment.
+
+- One common multi-agent environment is where we use a pairwise preference model to compare pairs of completions.
+- We can also use the group to define a two-player game. Some two player games such as tic-tac-toe are currently supported through the [text_arena](tinker_cookbook/recipes/multiplayer_rl/text_arena/env.py) environments.
+
+
+## Notation
+
+We'll use subscripts to indicate the shapes of objects. For example, `tokens_P_G_T` indicates a three-dimensional array of tokens, with `P` problems, `G` groups, and `T` tokens per groups, so `tokens_P_G_T[p][g][t]` should refer to a single token. In many cases, the arrays will be ragged. E.g., the `T` axis will have different lengths for different `(p,g)`. Sometimes, a given dimension will be flattened from two dimensions. If we write `tokens_PG_T`, that means that we have a two dimensional array, where the 0th dimension is flattened from the `P` and `G` dimensions.
+
+### Common Dimension Names
+
+Here are the standard dimension subscripts used throughout the codebase:
+
+- `_D`: Data/Datum dimension (for training data items)
+- `_G`: Group dimension (for multiple attempts/rollouts of the same problem)
+- `_P`: Problem dimension (for different problems/prompts)
+- `_T`: Token/Time dimension (for sequences)
+
+The relationship between dimensions in RL:
+- A batch contains multiple problems (`_P`)
+- Each problem spawns multiple attempts/environments (`_G`), forming a group
+- Each attempt produces one trajectory
+- Advantages are normalized within each group (across the `_G` dimension)
+
+Examples:
+- `env_group_builders_P`: A list of environment builders, one per problem
+- `trajectories_G`: Multiple trajectories from attempts at the same problem
+- `rewards_G`: Rewards for each attempt within a group
+- `tokens_P_G_T`: Tokens with problem, group, and time dimensions
+- `data_D`: A list of training data items

tinker_cookbook-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Thinking Machines Lab
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.