# tinker_cookbook.stores.TrainingRunStore

## *class* [**tinker_cookbook.stores.TrainingRunStore**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L50)()

Typed read/write access to one training run's data.

All file I/O goes through the [`Storage`](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/storage/index.md) protocol — no direct `Path`/`open()` usage. Pickle-serializable when freshly constructed (lazy reader init).

### [**url**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L67)(*path*)

Return a human-readable URI for a path within this run.

Useful for logging in distributed workers::

logger.info("Writing metrics to %s", store.url("metrics.jsonl"))

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L67) (*str*)

**Returns:** *str*

### [**read_config**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L128)()

Read config.json (cached after first read).

**Returns:** *dict[str, Any] | None*

### [**read_metrics**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L142)()

Read all metrics (incremental — only new data from disk).

**Returns:** *list\[dict[str, Any]\]*

### [**read_new_metrics**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L148)()

Read only metrics added since last call.

**Returns:** *list\[dict[str, Any]\]*

### [**metric_keys**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L152)()

All metric keys seen so far (excluding 'step').

**Returns:** *set[str]*

### [**read_rollouts**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L162)(*iteration*, *base_name*)

Read rollout summaries for an iteration as raw dicts.

**Parameters:**

- [**iteration**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L162) (*int*) – Training iteration number.
- [**base_name**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L162) (*str*) – Prefix for the JSONL file (e.g. `"train"`, `"eval_gsm8k"`). Matches the naming used by `rollout_summaries_jsonl_path()` in RL training.

**Returns:** *list\[dict[str, Any]\]*

### [**read_single_rollout**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L180)(*iteration*, *group_idx*, *traj_idx*, *base_name*)

Find one rollout by group and trajectory index, or `None`.

**Parameters:**

- [**iteration**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L182) (*int*)
- [**group_idx**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L183) (*int*)
- [**traj_idx**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L184) (*int*)
- [**base_name**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L185) (*str*)

**Returns:** *dict[str, Any] | None*

### [**read_checkpoints**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L195)()

Read checkpoints.jsonl.

**Returns:** *list\[dict[str, Any]\]*

### [**read_checkpoint_records**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L199)()

Read checkpoints.jsonl as [`CheckpointRecord`](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/checkpoint_utils/checkpointrecord/index.md) objects.

**Returns:** *list[Any]*

### [**read_timing**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L212)()

Read all timing records (incremental — only new data from disk).

**Returns:** *list\[dict[str, Any]\]*

### [**read_logtree**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L220)(*iteration*, *base_name*)

Read a logtree JSON file for an iteration, or `None` if missing.

**Parameters:**

- [**iteration**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L220) (*int*)
- [**base_name**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L220) (*str*)

**Returns:** *dict[str, Any] | None*

### [**list_logtrees**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L224)(*iteration*)

List logtree base names for an iteration (e.g. `["train", "eval_gsm8k"]`).

**Parameters:**

- [**iteration**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L224) (*int*)

**Returns:** *list[str]*

### [**list_iterations**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L231)()

List all iteration directories with metadata about their contents.

**Returns:** *list[IterationInfo]*

### [**write_config**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L259)(*config*)

Write config.json (overwrites if exists, updates cache).

**Parameters:**

- [**config**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L259) (*dict[str, Any]*)

**Returns:** *None*

### [**write_metrics**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L264)(*metrics*, *step*)

Append one metrics record to metrics.jsonl.

The record is `{"step": step, ...metrics}` if step is given, otherwise just the metrics dict.

**Parameters:**

- [**metrics**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L264) (*dict[str, Any]*)
- [**step**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L264) (*int | None*)

**Returns:** *None*

### [**write_timing_spans**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L274)(*step*, *spans*)

Append one timing record to timing_spans.jsonl.

Each span dict should have keys: `name`, `duration`, `wall_start`, `wall_end`.

**Parameters:**

- [**step**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L274) (*int*)
- [**spans**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L274) (*list\[dict[str, Any]\]*)

**Returns:** *None*

### [**write_checkpoint**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L284)(*record*)

Append one checkpoint record to checkpoints.jsonl.

Accepts a raw dict (e.g. from `CheckpointRecord.to_dict()`). Must contain at least a `"name"` key.

**Parameters:**

- [**record**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L284) (*dict[str, Any]*)

**Returns:** *None*

### [**write_rollouts**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L292)(*iteration*, *records*, *base_name*)

Write rollout summaries for an iteration (overwrites).

**Parameters:**

- [**iteration**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L294) (*int*) – Training iteration number.
- [**records**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L295) (*list\[dict[str, Any]\]*) – List of trajectory dicts to write.
- [**base_name**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L296) (*str*) – Prefix for the JSONL file (e.g. `"train"`, `"eval_gsm8k"`). Must match the `base_name` used in `read_rollouts()`.

**Returns:** *None*

### [**write_logtree**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L316)(*iteration*, *data*, *base_name*)

Write a logtree JSON file for an iteration (overwrites).

**Parameters:**

- [**iteration**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L316) (*int*)
- [**data**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L316) (*dict[str, Any]*)
- [**base_name**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L316) (*str*)

**Returns:** *None*

### [**write_code_diff**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L320)(*diff*)

Write code.diff (overwrites).

**Parameters:**

- [**diff**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L320) (*str*)

**Returns:** *None*

### [**aread_config**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L326)()

Async version of `read_config`.

**Returns:** *dict[str, Any] | None*

### [**aread_metrics**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L330)()

Async version of `read_metrics`.

**Returns:** *list\[dict[str, Any]\]*

### [**aread_new_metrics**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L334)()

Async version of `read_new_metrics`.

**Returns:** *list\[dict[str, Any]\]*

### [**aread_rollouts**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L338)(*iteration*, *base_name*)

Async version of `read_rollouts`.

**Parameters:**

- [**iteration**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L339) (*int*)
- [**base_name**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L339) (*str*)

**Returns:** *list\[dict[str, Any]\]*

### [**aread_checkpoints**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L344)()

Async version of `read_checkpoints`.

**Returns:** *list\[dict[str, Any]\]*

### [**aread_timing**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L348)()

Async version of `read_timing`.

**Returns:** *list\[dict[str, Any]\]*

### [**aread_logtree**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L352)(*iteration*, *base_name*)

Async version of `read_logtree`.

**Parameters:**

- [**iteration**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L353) (*int*)
- [**base_name**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L353) (*str*)

**Returns:** *dict[str, Any] | None*

### [**awrite_metrics**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L358)(*metrics*, *step*)

Async version of `write_metrics`.

**Parameters:**

- [**metrics**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L358) (*dict[str, Any]*)
- [**step**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L358) (*int | None*)

**Returns:** *None*

### [**awrite_checkpoint**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L362)(*record*)

Async version of `write_checkpoint`.

**Parameters:**

- [**record**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/training_store.py#L362) (*dict[str, Any]*)

**Returns:** *None*

## Referenced by

- [tinker_cookbook.checkpoint_utils.save_checkpoint](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/checkpoint_utils/save_checkpoint/index.md)
- [tinker_cookbook.stores.IncrementalReader](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/incrementalreader/index.md)
- [tinker_cookbook.stores.RunRegistry.get_training_store](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/runregistry/#runregistry-get_training_store)