Document the conditioning-tutorial checkpoints

README.md

@@ -1,3 +1,66 @@
 ---
 license: apache-2.0
+library_name: stip
+tags:
+- jax
+- flax
+- stochastic-interpolants
+- tutorial
 ---
+
+# STIP tutorial checkpoints
+
+Small checkpoints used by the [`stip`](https://github.com/instadeepai/stip) tutorial
+notebooks, so that a tutorial can demonstrate sampling without spending ten
+minutes training first. They are toy models (a two-layer MLP, ~50k parameters,
+trained for 1500 steps on a 4-component 2D Gaussian mixture) and have no
+use outside the notebooks.
+
+Checkpoints are [Orbax](https://orbax.readthedocs.io) directories written by
+`stip`'s own `TrainingIOHandler`, holding `params`, `opt_state`, `ema_params` and
+`extra` (EMA decay and step count) as separately-restorable items.
+
+## `conditioning_and_guidance/`
+
+Used by `tutorials/notebooks/4.conditioning_and_guidance.ipynb`. Both models are
+`VelocityGenerativeModel`s over two modalities — `coordinates` (continuous, 2D)
+and `index` (discrete, 4 categories) — with a `FlowMatchingOneSidedInterpolant`.
+
+| Path | Model | Role in the notebook |
+|---|---|---|
+| `conditioning_and_guidance/joint_model` | Unconditional cross-modal MLP | Intrinsic guidance (Section 4): conditioning a model that was never trained to be conditional |
+| `conditioning_and_guidance/context_model` | The same MLP plus a label context path, trained with 20% context dropout | Context conditioning and classifier-free guidance (Sections 5-7) |
+
+### Loading
+
+```python
+from flax import nnx
+from huggingface_hub import snapshot_download
+from stip.training.checkpointer import Checkpointer, CheckpointerConfig
+
+path = snapshot_download(
+    "InstaDeepAI/STIP-tutorials", allow_patterns="conditioning_and_guidance/joint_model/*"
+)
+gen_model = ...  # build the same model structure as the notebook
+graphdef, params = nnx.split(gen_model, nnx.Param)
+checkpointer = Checkpointer(
+    CheckpointerConfig(
+        checkpoint_dir=f"{path}/conditioning_and_guidance/joint_model",
+        max_to_keep=None,  # read-only: never mutate a downloaded directory
+    )
+)
+gen_model = nnx.merge(graphdef, checkpointer.restore_ema(params))
+```
+
+`restore_ema` reads only `ema_params` and `extra`, and applies the same bias
+correction the training loop uses for evaluation.
+
+## Reproducing
+
+```bash
+uv run python tutorials/scripts/train_conditioning_checkpoints.py
+```
+
+The script mirrors the notebook's model definitions and PRNG chain, so it
+reproduces these exact weights. A checkpoint pins the parameter structure: if a
+notebook's network changes, re-run the script and re-upload.