baseten-loops-cookbook 0.2.0a3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. baseten_loops_cookbook-0.2.0a3/.gitignore +22 -0
  2. baseten_loops_cookbook-0.2.0a3/LICENSE +21 -0
  3. baseten_loops_cookbook-0.2.0a3/PKG-INFO +334 -0
  4. baseten_loops_cookbook-0.2.0a3/README.md +291 -0
  5. baseten_loops_cookbook-0.2.0a3/examples/README.md +32 -0
  6. baseten_loops_cookbook-0.2.0a3/examples/async_scheduling/README.md +21 -0
  7. baseten_loops_cookbook-0.2.0a3/examples/async_scheduling/answer_episode.py +77 -0
  8. baseten_loops_cookbook-0.2.0a3/examples/async_scheduling/train.toml +50 -0
  9. baseten_loops_cookbook-0.2.0a3/examples/async_scheduling/train_blaxel.toml +62 -0
  10. baseten_loops_cookbook-0.2.0a3/examples/counting/README.md +60 -0
  11. baseten_loops_cookbook-0.2.0a3/examples/counting/count_episode.py +108 -0
  12. baseten_loops_cookbook-0.2.0a3/examples/counting/make_tasks.py +29 -0
  13. baseten_loops_cookbook-0.2.0a3/examples/counting/tasks.jsonl +512 -0
  14. baseten_loops_cookbook-0.2.0a3/examples/counting/train.toml +49 -0
  15. baseten_loops_cookbook-0.2.0a3/examples/critic/README.md +21 -0
  16. baseten_loops_cookbook-0.2.0a3/examples/critic/critic_agent.py +67 -0
  17. baseten_loops_cookbook-0.2.0a3/examples/critic/job_blaxel.yaml +19 -0
  18. baseten_loops_cookbook-0.2.0a3/examples/critic/train_blaxel.toml +67 -0
  19. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/README.md +116 -0
  20. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/episodes.py +89 -0
  21. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/hill_climb_episode.py +36 -0
  22. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/hill_climb_tasks.jsonl +1 -0
  23. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/questions.jsonl +1 -0
  24. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/train_hill_climb.toml +48 -0
  25. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/train_host_scored.toml +48 -0
  26. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/train_separate_verifier.toml +61 -0
  27. baseten_loops_cookbook-0.2.0a3/examples/episode_basics/train_shared_sandbox.toml +56 -0
  28. baseten_loops_cookbook-0.2.0a3/examples/litellm_streaming/README.md +23 -0
  29. baseten_loops_cookbook-0.2.0a3/examples/litellm_streaming/litellm_episode.py +60 -0
  30. baseten_loops_cookbook-0.2.0a3/examples/litellm_streaming/train.toml +50 -0
  31. baseten_loops_cookbook-0.2.0a3/examples/llm_judge/README.md +76 -0
  32. baseten_loops_cookbook-0.2.0a3/examples/llm_judge/judge_episode.py +209 -0
  33. baseten_loops_cookbook-0.2.0a3/examples/llm_judge/tasks.jsonl +8 -0
  34. baseten_loops_cookbook-0.2.0a3/examples/llm_judge/train.toml +60 -0
  35. baseten_loops_cookbook-0.2.0a3/examples/llm_judge/train_blaxel.toml +73 -0
  36. baseten_loops_cookbook-0.2.0a3/examples/multi_step/README.md +18 -0
  37. baseten_loops_cookbook-0.2.0a3/examples/multi_step/job_blaxel.yaml +19 -0
  38. baseten_loops_cookbook-0.2.0a3/examples/multi_step/step_agent.py +51 -0
  39. baseten_loops_cookbook-0.2.0a3/examples/multi_step/train_blaxel.toml +61 -0
  40. baseten_loops_cookbook-0.2.0a3/examples/sft_tool_use/README.md +23 -0
  41. baseten_loops_cookbook-0.2.0a3/examples/sft_tool_use/make_data.py +127 -0
  42. baseten_loops_cookbook-0.2.0a3/examples/sft_tool_use/sft.toml +29 -0
  43. baseten_loops_cookbook-0.2.0a3/examples/sft_tool_use/train.jsonl +64 -0
  44. baseten_loops_cookbook-0.2.0a3/examples/sft_tool_use/validation.jsonl +8 -0
  45. baseten_loops_cookbook-0.2.0a3/examples/sft_toucan/README.md +57 -0
  46. baseten_loops_cookbook-0.2.0a3/examples/sft_toucan/evaluate.py +194 -0
  47. baseten_loops_cookbook-0.2.0a3/examples/sft_toucan/make_data.py +185 -0
  48. baseten_loops_cookbook-0.2.0a3/examples/sft_toucan/sft.toml +30 -0
  49. baseten_loops_cookbook-0.2.0a3/examples/terminal_bench/README.md +44 -0
  50. baseten_loops_cookbook-0.2.0a3/examples/terminal_bench/echo_loss.py +54 -0
  51. baseten_loops_cookbook-0.2.0a3/examples/terminal_bench/harbor.yaml +39 -0
  52. baseten_loops_cookbook-0.2.0a3/examples/terminal_bench/terminal_agent.py +187 -0
  53. baseten_loops_cookbook-0.2.0a3/examples/terminal_bench/train.toml +83 -0
  54. baseten_loops_cookbook-0.2.0a3/examples/terminal_bench/train_echo.toml +89 -0
  55. baseten_loops_cookbook-0.2.0a3/examples/tool_agent/README.md +70 -0
  56. baseten_loops_cookbook-0.2.0a3/examples/tool_agent/tasks.jsonl +8 -0
  57. baseten_loops_cookbook-0.2.0a3/examples/tool_agent/tool_episode.py +167 -0
  58. baseten_loops_cookbook-0.2.0a3/examples/tool_agent/train_blaxel.toml +68 -0
  59. baseten_loops_cookbook-0.2.0a3/patterns/README.md +212 -0
  60. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/in_process_direct/README.md +46 -0
  61. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/in_process_direct/direct_episode.py +83 -0
  62. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/in_process_direct/train.toml +49 -0
  63. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/in_process_direct/train_blaxel.toml +62 -0
  64. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/in_process_openai_http/README.md +50 -0
  65. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/in_process_openai_http/http_episode.py +95 -0
  66. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/in_process_openai_http/train.toml +49 -0
  67. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/in_process_openai_http/train_blaxel.toml +62 -0
  68. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/local/README.md +59 -0
  69. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/local/agent_program.py +54 -0
  70. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/local/local_episode.py +155 -0
  71. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/local/local_sandbox.py +153 -0
  72. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/local/sandbox_io.py +60 -0
  73. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/local/train.toml +75 -0
  74. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/local/train_blaxel.toml +71 -0
  75. baseten_loops_cookbook-0.2.0a3/patterns/custom_runtime/local/verifier.py +63 -0
  76. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_direct/README.md +30 -0
  77. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_direct/direct_agent.py +52 -0
  78. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_direct/job.yaml +11 -0
  79. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_direct/job_blaxel.yaml +19 -0
  80. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_direct/train.toml +50 -0
  81. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_direct/train_blaxel.toml +60 -0
  82. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_openai_http/README.md +30 -0
  83. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_openai_http/http_agent.py +49 -0
  84. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_openai_http/job.yaml +11 -0
  85. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_openai_http/job_blaxel.yaml +19 -0
  86. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_openai_http/train.toml +51 -0
  87. baseten_loops_cookbook-0.2.0a3/patterns/harbor/in_process_openai_http/train_blaxel.toml +59 -0
  88. baseten_loops_cookbook-0.2.0a3/patterns/harbor/local/README.md +37 -0
  89. baseten_loops_cookbook-0.2.0a3/patterns/harbor/local/agent_program.py +54 -0
  90. baseten_loops_cookbook-0.2.0a3/patterns/harbor/local/job_blaxel.yaml +22 -0
  91. baseten_loops_cookbook-0.2.0a3/patterns/harbor/local/local_agent.py +98 -0
  92. baseten_loops_cookbook-0.2.0a3/patterns/harbor/local/train_blaxel.toml +61 -0
  93. baseten_loops_cookbook-0.2.0a3/patterns/harbor/train_template.toml +54 -0
  94. baseten_loops_cookbook-0.2.0a3/pyproject.toml +207 -0
  95. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/__init__.py +19 -0
  96. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/cancellation.py +163 -0
  97. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/cli.py +559 -0
  98. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/command.py +195 -0
  99. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/console.py +361 -0
  100. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/docs.py +295 -0
  101. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/episodes/__init__.py +39 -0
  102. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/episodes/api.py +381 -0
  103. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/episodes/runtime.py +840 -0
  104. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/episodes/tasks.py +120 -0
  105. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/evidence.py +758 -0
  106. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/harbor/__init__.py +20 -0
  107. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/harbor/agent.py +50 -0
  108. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/harbor/attempts.py +116 -0
  109. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/harbor/blaxel.py +209 -0
  110. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/harbor/daytona.py +233 -0
  111. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/harbor/integration.py +293 -0
  112. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/harbor/oom.py +56 -0
  113. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/harbor/runtime.py +1141 -0
  114. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/__init__.py +60 -0
  115. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/client.py +908 -0
  116. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/factory.py +142 -0
  117. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/images.py +176 -0
  118. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/prime.py +360 -0
  119. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/render_pool.py +70 -0
  120. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/renderer_extensions/README.md +76 -0
  121. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/renderer_extensions/__init__.py +1 -0
  122. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/renderer_extensions/glm53.py +338 -0
  123. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/renderer_extensions/qwen35.py +85 -0
  124. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/rendering.py +192 -0
  125. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/llm/transcript.py +506 -0
  126. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/metrics.py +149 -0
  127. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/__init__.py +21 -0
  128. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/api.py +63 -0
  129. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/lease.py +647 -0
  130. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/openai/__init__.py +1 -0
  131. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/openai/access.py +393 -0
  132. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/openai/gateway.py +386 -0
  133. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/openai/policy.py +457 -0
  134. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/openai/schema/__init__.py +1 -0
  135. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/openai/schema/chat_completions.json +2841 -0
  136. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/openai/schema/models.py +1783 -0
  137. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/openai/translate.py +479 -0
  138. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/model_access/producers.py +43 -0
  139. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/project.py +190 -0
  140. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/__init__.py +77 -0
  141. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/blaxel/__init__.py +113 -0
  142. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/blaxel/adapter.py +480 -0
  143. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/blaxel/api.py +255 -0
  144. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/blaxel/build_file.py +50 -0
  145. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/blaxel/incidents.py +354 -0
  146. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/blaxel/settings.py +72 -0
  147. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/blaxel/usage.py +81 -0
  148. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/daytona/__init__.py +160 -0
  149. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/daytona/adapter.py +468 -0
  150. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/daytona/api.py +171 -0
  151. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/daytona/errors.py +98 -0
  152. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/daytona/settings.py +145 -0
  153. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/providers/daytona/usage.py +90 -0
  154. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/py.typed +0 -0
  155. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/resources/__init__.py +45 -0
  156. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/resources/api.py +428 -0
  157. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/resources/capacity.py +43 -0
  158. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/resources/cleanup.py +239 -0
  159. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/resources/journal.py +286 -0
  160. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/resources/registry.py +1507 -0
  161. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/resources/services.py +156 -0
  162. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/__init__.py +17 -0
  163. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/aggregation.py +184 -0
  164. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/cli.py +125 -0
  165. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/config.py +601 -0
  166. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/grpo.py +116 -0
  167. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/loss.py +108 -0
  168. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/metrics.py +167 -0
  169. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/observability.py +181 -0
  170. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/pipeline.py +1190 -0
  171. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/recipe.py +303 -0
  172. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/run.py +1802 -0
  173. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/slices.py +62 -0
  174. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/rl/trainer.py +477 -0
  175. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/run_record.py +298 -0
  176. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/runtime/__init__.py +73 -0
  177. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/runtime/api.py +348 -0
  178. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/runtime/capacity.py +486 -0
  179. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/runtime/context.py +247 -0
  180. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/runtime/driver.py +1506 -0
  181. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/runtime/groups.py +136 -0
  182. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/runtime/processes.py +301 -0
  183. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/settings.py +213 -0
  184. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/sft/__init__.py +31 -0
  185. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/sft/cli.py +37 -0
  186. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/sft/config.py +133 -0
  187. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/sft/data.py +425 -0
  188. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/sft/recipe.py +147 -0
  189. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/sft/run.py +839 -0
  190. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/sft/sequences.py +496 -0
  191. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/sft/trainer.py +181 -0
  192. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/telemetry.py +72 -0
  193. baseten_loops_cookbook-0.2.0a3/src/loops_cookbook/trainer.py +607 -0
  194. baseten_loops_cookbook-0.2.0a3/tasks/README.md +19 -0
  195. baseten_loops_cookbook-0.2.0a3/tasks/hidden_answer.jsonl +1 -0
  196. baseten_loops_cookbook-0.2.0a3/tasks/hidden_answer_35b.jsonl +1 -0
  197. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb/environment/Dockerfile +2 -0
  198. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb/instruction.md +3 -0
  199. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb/task.toml +20 -0
  200. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb/tests/Dockerfile +3 -0
  201. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb/tests/grade.py +14 -0
  202. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb/tests/test.sh +3 -0
  203. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb_steps/environment/Dockerfile +2 -0
  204. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb_steps/steps/first/instruction.md +3 -0
  205. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb_steps/steps/first/tests/test.sh +3 -0
  206. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb_steps/steps/second/instruction.md +3 -0
  207. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb_steps/steps/second/tests/test.sh +3 -0
  208. baseten_loops_cookbook-0.2.0a3/tasks/hill_climb_steps/task.toml +20 -0
@@ -0,0 +1,22 @@
1
+ __pycache__/
2
+ *.pyc
3
+ *.egg-info/
4
+ .DS_Store
5
+ .venv/
6
+ /dist/
7
+ .env
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .worktrees/
11
+ wandb/
12
+
13
+ # Training output written by `loops run`
14
+ runs/
15
+ outputs/
16
+
17
+ # Private working notes, kept out of the published recipe
18
+ notes/
19
+
20
+ # Data the SFT examples download and write
21
+ examples/sft_toucan/data/
22
+ examples/sft_toucan/evaluation.json
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Baseten
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,334 @@
1
+ Metadata-Version: 2.5
2
+ Name: baseten-loops-cookbook
3
+ Version: 0.2.0a3
4
+ Summary: RL and SFT recipes on Baseten Loops: train your agent on your tasks, or fine-tune on conversations.
5
+ Project-URL: Repository, https://github.com/basetenlabs/loops-cookbook
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.12
9
+ Requires-Dist: aiohttp>=3.14.4
10
+ Requires-Dist: baseten-loops<0.33,>=0.32.0
11
+ Requires-Dist: pillow>=13.0
12
+ Requires-Dist: pydantic>=2.7
13
+ Requires-Dist: python-dotenv>=1.2
14
+ Requires-Dist: pyyaml>=6
15
+ Requires-Dist: renderers[multimodal,transformers]<0.1.13,>=0.1.12
16
+ Requires-Dist: transformers<5.20,>=5.16
17
+ Requires-Dist: typing-extensions>=4.12
18
+ Provides-Extra: blaxel
19
+ Requires-Dist: blaxel<0.5,>=0.4.20; extra == 'blaxel'
20
+ Provides-Extra: console
21
+ Requires-Dist: rich>=13.0; extra == 'console'
22
+ Provides-Extra: custom-loss
23
+ Requires-Dist: baseten-loops[torch]<0.33,>=0.32.0; extra == 'custom-loss'
24
+ Provides-Extra: daytona
25
+ Requires-Dist: daytona<0.227,>=0.220.0; extra == 'daytona'
26
+ Provides-Extra: harbor
27
+ Requires-Dist: harbor<0.24,>=0.23; extra == 'harbor'
28
+ Requires-Dist: litellm!=1.107.0,>=1.100.4; extra == 'harbor'
29
+ Provides-Extra: harbor-blaxel
30
+ Requires-Dist: blaxel<0.5,>=0.4.20; extra == 'harbor-blaxel'
31
+ Requires-Dist: harbor[blaxel]<0.24,>=0.23; extra == 'harbor-blaxel'
32
+ Requires-Dist: litellm!=1.107.0,>=1.100.4; extra == 'harbor-blaxel'
33
+ Provides-Extra: harbor-daytona
34
+ Requires-Dist: daytona<0.227,>=0.220.0; extra == 'harbor-daytona'
35
+ Requires-Dist: harbor[daytona]<0.24,>=0.23; extra == 'harbor-daytona'
36
+ Requires-Dist: litellm!=1.107.0,>=1.100.4; extra == 'harbor-daytona'
37
+ Provides-Extra: vision
38
+ Requires-Dist: torch>=2.4; extra == 'vision'
39
+ Requires-Dist: torchvision>=0.19; extra == 'vision'
40
+ Provides-Extra: wandb
41
+ Requires-Dist: wandb>=0.16.0; extra == 'wandb'
42
+ Description-Content-Type: text/markdown
43
+
44
+ # loops-cookbook
45
+
46
+ Post-train models on [Baseten Loops](https://docs.baseten.co). Loops runs the
47
+ expensive half, a LoRA trainer and a paired sampler that hot-swaps to each new policy;
48
+ the cookbook runs the rest. It comes with two recipes, and the `loops` command runs
49
+ both: each config names its recipe with the `recipe` key.
50
+
51
+ | Recipe | Config key | Use it when |
52
+ | --- | --- | --- |
53
+ | [RL](#rl) | `recipe = "rl"` | your agent acts on tasks and a verifier rewards what it did |
54
+ | [SFT](#sft) | `recipe = "sft"` | you have conversations for the model to imitate |
55
+
56
+ ## Install
57
+
58
+ You need `uv`, and a Baseten workspace with Loops enabled and its API key. Gated or
59
+ private Hugging Face repos, including a tokenizer named by `[model] tokenizer`, also
60
+ need `HF_TOKEN`.
61
+
62
+ As a dependency of your own project, from [PyPI](https://pypi.org/p/baseten-loops-cookbook).
63
+ Add `==X.Y.Z` to pin a [release](https://github.com/basetenlabs/loops-cookbook/releases).
64
+
65
+ ```sh
66
+ uv add baseten-loops-cookbook # SFT, or RL with a custom runtime
67
+ uv add "baseten-loops-cookbook[harbor]" # RL with the Harbor runtime
68
+ ```
69
+
70
+ The package ships the [examples](examples/), [patterns](patterns/) and [tasks](tasks/).
71
+ Run one by its path in this repository, from any directory:
72
+
73
+ ```sh
74
+ uv run loops check examples/terminal_bench/train.toml
75
+ ```
76
+
77
+ A file at that path in your working directory wins over the installed one, so to change
78
+ an example, copy its directory there; `loops check` prints where the installed one is.
79
+ Copy it too for an example whose scripts write beside themselves, such as `sft_toucan`. The extras are the same as below: for
80
+ example, `uv add "baseten-loops-cookbook[harbor-blaxel]"`.
81
+
82
+ Or clone it to run the examples and hack on it:
83
+
84
+ ```sh
85
+ uv sync # the core: SFT, and RL with a custom runtime
86
+ uv sync --extra harbor # + the Harbor runtime on Docker
87
+ uv sync --extra harbor-blaxel # + the Harbor runtime on Blaxel sandboxes
88
+ uv sync --extra harbor-daytona # + the Harbor runtime on Daytona sandboxes
89
+ uv sync --extra blaxel # + the Blaxel provider alone, for a custom runtime (likewise daytona)
90
+ uv sync --extra wandb # mirror metrics to Weights & Biases
91
+ uv sync --extra console # the rich live progress region (--output.console)
92
+ uv sync --extra vision # image inputs for vision models (brings torch)
93
+ uv sync --extra custom-loss # RL: your own loss through forward_backward_custom (brings torch)
94
+ ```
95
+
96
+ The cookbook reaches Loops through the
97
+ [`baseten-loops`](https://pypi.org/project/baseten-loops/) SDK, which it installs.
98
+ Copy [.env.example](.env.example) to `.env` and fill in `BASETEN_API_KEY`. The CLIs
99
+ load `.env` from the training config's directory or the working directory. Loops itself
100
+ needs nothing local: the trainer and sampler run on Baseten.
101
+
102
+ ## Serverless or dedicated
103
+
104
+ Loops runs each model in one of two ways:
105
+
106
+ - **Serverless.** The run trains and samples on a shared pool that Baseten keeps
107
+ ready, so the run starts in minutes.
108
+ - **Dedicated.** The run gets its own trainer and sampler deployment. This takes
109
+ longer to start. The deployment stays provisioned, and you pay for it, until you
110
+ deactivate the run.
111
+
112
+ The config does not choose between the two. The model and your workspace's access
113
+ decide it. Qwen3.6-35B-A3B, GLM-5.3 and GLM-5.3-Flash have serverless pools. The
114
+ quickstarts below train Qwen/Qwen3.6-35B-A3B.
115
+ Some patterns and examples train other models. The
116
+ [examples table](examples/README.md) gives the model of each example and how that
117
+ model runs.
118
+
119
+ > [!NOTE]
120
+ > Contact Baseten to get access to a serverless pool, to train a model that has no
121
+ > pool, or to get dedicated capacity.
122
+
123
+ ## RL
124
+
125
+ Loops trains on what your agent did; the cookbook runs your agent on your tasks and
126
+ turns each episode into training data with the exact tokens the model sampled.
127
+
128
+ ### How it works
129
+
130
+ <picture>
131
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/core-loop-dark.svg">
132
+ <img alt="The core loop as seven numbered steps: the run schedules episodes on the runtime; the runtime runs your agent in its environment; model calls go through the model client to the sampler; the client records the exact tokens; rewards come back through the runtime; the run sends training batches to the LoRA trainer; the trainer publishes the new policy to the sampler." src="docs/assets/core-loop.svg">
133
+ </picture>
134
+
135
+ 1. The **run** schedules episodes on the **runtime** (Harbor, or a custom runtime).
136
+ 2. The runtime runs your **agent** in its environment.
137
+ 3. Every model call the agent makes goes through the cookbook's **model client** to the
138
+ sampler.
139
+ 4. The model client records the exact tokens the sampler returned.
140
+ 5. The environment's verifier scores the episode, and the reward comes back through
141
+ the runtime.
142
+ 6. The run joins tokens and rewards into training batches for the LoRA trainer.
143
+ 7. The trainer publishes the new policy to the sampler, and the next episodes use it.
144
+
145
+ So the responsibilities split cleanly:
146
+
147
+ - **You bring** an environment (tasks, sandboxes, a verifier that produces rewards)
148
+ and an agent that decides what to do in it. The agent owns its prompts, tools,
149
+ history, and stopping rules.
150
+ - **The cookbook brings** the model client, which renders messages with the model's
151
+ own chat template and keeps the exact token IDs and logprobs; rollout scheduling
152
+ across sampling and grading, sync or async; GRPO advantages (reward minus the group
153
+ mean, not divided by its standard deviation) and datum packing; the
154
+ Loops trainer transport, checkpoints, and metrics.
155
+
156
+ ### Pick a pattern
157
+
158
+ Where your agent runs decides most of what you write:
159
+
160
+ - **in-process**: your agent is Python the runtime calls inside the training process,
161
+ such as a Harbor `LoopsAgent` class. It can call the model directly with `llm()`.
162
+ - **local**: your agent is its own program (a binary, a CLI, another language, code
163
+ you can't edit) that the runtime launches on the training machine. It reaches the
164
+ model through the run's OpenAI-compatible endpoint.
165
+ - **remote**: your agent runs inside the sandbox, such as an agent installed in the
166
+ environment. Not supported yet.
167
+
168
+ [patterns/README.md](patterns/README.md) defines the terms, then shows each placement with
169
+ a diagram, what you write, when to use it, and who owns the sandbox on each
170
+ environment backend. Every supported pattern is a runnable directory in
171
+ [patterns/](patterns/), with a training config per backend; [examples/](examples/)
172
+ builds settings and features on top of them.
173
+
174
+ Tasks with an environment also need an environment backend (see
175
+ [environment backends](patterns/README.md#environment-backends)): a local Docker daemon
176
+ is enough to start, and Blaxel or Daytona needs its extra and its credentials.
177
+
178
+ ### Quickstart
179
+
180
+ The smallest run needs only the core install and `BASETEN_API_KEY`: no Harbor, Docker
181
+ or sandbox.
182
+
183
+ ```sh
184
+ uv run loops check patterns/custom_runtime/in_process_direct/train.toml # resolves the config, asks Loops about the model; launches nothing
185
+ uv run loops run patterns/custom_runtime/in_process_direct/train.toml # provisions Loops resources (billable)
186
+ ```
187
+
188
+ `check` launches no sandbox and no Loops trainer (on a first run it still downloads the
189
+ tokenizer and any remote dataset), but it is not read-only: it writes a
190
+ fresh run directory under `<output_dir>/preflight/`, with its own resource journal,
191
+ and whatever the runtime writes while it prepares.
192
+
193
+ This is [custom runtime, in-process, direct](patterns/custom_runtime/in_process_direct/):
194
+ an `Episode` asks the model to name a hidden game once and scores the reply itself, so
195
+ the reward climbs within a few steps. Every training setting can be overridden on the
196
+ command line; `loops run --help` lists them with defaults.
197
+
198
+ With Harbor tasks, start from [Harbor, in-process, direct](patterns/harbor/in_process_direct/)
199
+ instead: the same one-call agent, on the shared [hill-climb task](tasks/hill_climb/).
200
+ A Harbor trial always starts an environment, for the agent's answer and the verifier,
201
+ so even this task runs in a sandbox: `train.toml` on local Docker (`--extra harbor`),
202
+ or `train_blaxel.toml` on Blaxel with no Docker (`--extra harbor-blaxel` and Blaxel
203
+ credentials). Every other pattern is a directory beside these in [patterns/](patterns/),
204
+ and [examples/](examples/) adds settings and features on top.
205
+
206
+ If a run crashes, the sandboxes it created on Blaxel or Daytona are in its resource
207
+ journal, and `cleanup` releases them:
208
+
209
+ ```sh
210
+ uv run loops cleanup patterns/harbor/in_process_direct/train_blaxel.toml --state-dir runs/harbor-direct-blaxel/<run-dir>/state
211
+ ```
212
+
213
+ Docker sandboxes are Harbor's and not in the journal; after a crashed Docker run, check
214
+ `docker ps`.
215
+
216
+ The training process runs where you start it. It renders every turn's prompt, holds
217
+ each live conversation's tokens and opens files and sockets for each live attempt
218
+ (`check` refuses an open-file limit too low for them), so its CPU, memory and open
219
+ files grow with `max_concurrent_rollouts` and context length. A laptop
220
+ is enough for the patterns here; for high concurrency with long contexts, or a run that
221
+ must outlast your laptop, start it on a dev box.
222
+
223
+ ## SFT
224
+
225
+ Supervised fine-tuning needs no runtime, pattern or sandbox: only your data and a
226
+ Loops trainer.
227
+
228
+ ### Quickstart
229
+
230
+ ```sh
231
+ uv run loops check examples/sft_tool_use/sft.toml # renders every row; launches nothing
232
+ uv run loops run examples/sft_tool_use/sft.toml # provisions a Loops trainer (billable)
233
+ ```
234
+
235
+ ### Data
236
+
237
+ Data is OpenAI chat fine-tuning JSONL (`messages`, `tools`, a per-turn `weight`), or
238
+ already tokenized `input_ids` and `weights` for full control. Each conversation is
239
+ rendered with the trained model's chat template, which decides the targets: every
240
+ trained turn learns its own stop token, in the context it was generated in. `check`
241
+ reports what trains, what is split per turn and what is refused, with the reason.
242
+ [docs/reference/sft.md](docs/reference/sft.md) has the contracts, the rule, the
243
+ metrics and resume. [examples/sft_toucan](examples/sft_toucan/) trains on real
244
+ tool-agent trajectories from Hugging Face and compares the base model and the adapter
245
+ on held-out conversations; [examples/sft_tool_use](examples/sft_tool_use/) is a small
246
+ synthetic one.
247
+
248
+ ## Use it as a library
249
+
250
+ ```python
251
+ from loops_cookbook.project import load
252
+
253
+ project = load("train.toml", env_file=".env")
254
+ report = await project.check()
255
+ print("\n".join(report.describe()))
256
+ outcome = await project.train()
257
+ ```
258
+
259
+ `load()` reads a TOML or JSON config, and its `recipe` key picks the recipe, as it does
260
+ for `loops`. It keeps `project.path`, `project.source` and `project.config`, and makes
261
+ the config's directory importable. Pass dotted overrides as
262
+ `overrides={"training.max_steps": 5}`. A path in the config is relative to the config.
263
+ A symlinked config is the file it points to, so its paths, modules and `.env` are
264
+ beside that file. A path in an override, and the output directory, are relative to the
265
+ working directory when `load()` runs.
266
+
267
+ `load()` reads `.env` only when you pass `env_file`, which is relative to the config.
268
+ It sets only variables that the process does not set. `loops` always loads `.env`
269
+ beside the config and in the working directory, with the same rule.
270
+
271
+ `loops check` first prints what the config used, and a run's `run.log` begins with
272
+ the same lines:
273
+
274
+ ```text
275
+ Config: /home/me/project/train.toml -> /home/me/shared/train.toml
276
+ paths, modules: beside /home/me/shared
277
+ .env: /home/me/shared/.env, /home/me/project/.env
278
+ runs: /home/me/project/runs
279
+ ```
280
+
281
+ Both operations are async. `check()` does what `loops check` does and returns a report;
282
+ `describe()` gives the lines `loops check` prints after those; `project.describe()`
283
+ gives those. A check can download model or data
284
+ files, and an RL check writes a run under `output_dir/preflight`. It starts no trainer.
285
+ `train()` does what `loops run` does and returns the run's `Outcome`. The library
286
+ does not configure logging; that stays with your application. For custom wiring, use
287
+ each recipe's `recipe.train` and `recipe.check` directly.
288
+
289
+ - `loops_cookbook.runtime`: the `RolloutRuntime` contract a runtime implements, and
290
+ the attempt and evidence types it receives. `[runtime].factory` names the
291
+ runtime's factory.
292
+ - `loops_cookbook.model_access`: attempt leases, capture, `ModelAccessMode`, and the
293
+ OpenAI-compatible gateway for agents that speak Chat Completions (a runtime whose
294
+ model access is `openai_http`).
295
+ - `loops_cookbook.rl`: the RL recipe. Its core is environment-agnostic: `Run`,
296
+ `Pipeline`, `Trainer`, GRPO. `rl.cli` and `rl.recipe` are the composition roots that
297
+ wire it to a runtime and providers, as `sft.cli` and `sft.recipe` are for SFT.
298
+ - `loops_cookbook.llm`: `LoopsLLM`, the handle a runtime's agents call the model
299
+ through, the model client, and the Prime renderer adapter.
300
+ - `loops_cookbook.resources` and `loops_cookbook.providers`: the provider-neutral
301
+ resource registry and journal behind `attempt.services.resources`, and the
302
+ `[providers.<name>]` adapters it acts through.
303
+ - `loops_cookbook.harbor`: Harbor as one runtime among others. `create_runtime`
304
+ and `LoopsAgent`.
305
+ - `loops_cookbook.sft`: supervised fine-tuning. Its core is its data contracts, the
306
+ target rule and `Run`; `sft.cli` and `sft.recipe` are its composition roots, and
307
+ `sft.recipe.train` is the entry point `loops run` calls.
308
+
309
+ Each name is imported from the one package that defines it.
310
+
311
+ A custom runtime is an `Episode` class (`loops_cookbook.episodes`), which the cookbook
312
+ runs as a `RolloutRuntime` and which reuses everything else;
313
+ [patterns/custom_runtime](patterns/custom_runtime/) has one for each supported agent
314
+ placement and model access, the smallest being
315
+ [in_process_direct](patterns/custom_runtime/in_process_direct/).
316
+
317
+ ## Docs
318
+
319
+ - [patterns/README.md](patterns/README.md): every pattern, with diagrams, what you write,
320
+ and when to use it; environment backends.
321
+ - [examples/README.md](examples/README.md): examples by setting and feature, built on
322
+ the patterns.
323
+ - [docs/reference/](docs/reference/README.md): the exact rules: the training loop,
324
+ model access and token capture, scheduling, resources, failures, the `Episode` API,
325
+ Harbor, Daytona, renderers, SFT, and every setting
326
+ ([KNOB_GLOSSARY.md](docs/reference/KNOB_GLOSSARY.md)).
327
+ - [docs/README.md](docs/README.md): how the cookbook is built, for developers changing
328
+ it: the principles, the engine, the interfaces, and the patterns' mechanics.
329
+ - [tests/README.md](tests/README.md): the test layout and the live tests.
330
+ - [ROADMAP.md](ROADMAP.md).
331
+
332
+ ## Contributing
333
+
334
+ Setting up, running the tests and cutting a release: [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -0,0 +1,291 @@
1
+ # loops-cookbook
2
+
3
+ Post-train models on [Baseten Loops](https://docs.baseten.co). Loops runs the
4
+ expensive half, a LoRA trainer and a paired sampler that hot-swaps to each new policy;
5
+ the cookbook runs the rest. It comes with two recipes, and the `loops` command runs
6
+ both: each config names its recipe with the `recipe` key.
7
+
8
+ | Recipe | Config key | Use it when |
9
+ | --- | --- | --- |
10
+ | [RL](#rl) | `recipe = "rl"` | your agent acts on tasks and a verifier rewards what it did |
11
+ | [SFT](#sft) | `recipe = "sft"` | you have conversations for the model to imitate |
12
+
13
+ ## Install
14
+
15
+ You need `uv`, and a Baseten workspace with Loops enabled and its API key. Gated or
16
+ private Hugging Face repos, including a tokenizer named by `[model] tokenizer`, also
17
+ need `HF_TOKEN`.
18
+
19
+ As a dependency of your own project, from [PyPI](https://pypi.org/p/baseten-loops-cookbook).
20
+ Add `==X.Y.Z` to pin a [release](https://github.com/basetenlabs/loops-cookbook/releases).
21
+
22
+ ```sh
23
+ uv add baseten-loops-cookbook # SFT, or RL with a custom runtime
24
+ uv add "baseten-loops-cookbook[harbor]" # RL with the Harbor runtime
25
+ ```
26
+
27
+ The package ships the [examples](examples/), [patterns](patterns/) and [tasks](tasks/).
28
+ Run one by its path in this repository, from any directory:
29
+
30
+ ```sh
31
+ uv run loops check examples/terminal_bench/train.toml
32
+ ```
33
+
34
+ A file at that path in your working directory wins over the installed one, so to change
35
+ an example, copy its directory there; `loops check` prints where the installed one is.
36
+ Copy it too for an example whose scripts write beside themselves, such as `sft_toucan`. The extras are the same as below: for
37
+ example, `uv add "baseten-loops-cookbook[harbor-blaxel]"`.
38
+
39
+ Or clone it to run the examples and hack on it:
40
+
41
+ ```sh
42
+ uv sync # the core: SFT, and RL with a custom runtime
43
+ uv sync --extra harbor # + the Harbor runtime on Docker
44
+ uv sync --extra harbor-blaxel # + the Harbor runtime on Blaxel sandboxes
45
+ uv sync --extra harbor-daytona # + the Harbor runtime on Daytona sandboxes
46
+ uv sync --extra blaxel # + the Blaxel provider alone, for a custom runtime (likewise daytona)
47
+ uv sync --extra wandb # mirror metrics to Weights & Biases
48
+ uv sync --extra console # the rich live progress region (--output.console)
49
+ uv sync --extra vision # image inputs for vision models (brings torch)
50
+ uv sync --extra custom-loss # RL: your own loss through forward_backward_custom (brings torch)
51
+ ```
52
+
53
+ The cookbook reaches Loops through the
54
+ [`baseten-loops`](https://pypi.org/project/baseten-loops/) SDK, which it installs.
55
+ Copy [.env.example](.env.example) to `.env` and fill in `BASETEN_API_KEY`. The CLIs
56
+ load `.env` from the training config's directory or the working directory. Loops itself
57
+ needs nothing local: the trainer and sampler run on Baseten.
58
+
59
+ ## Serverless or dedicated
60
+
61
+ Loops runs each model in one of two ways:
62
+
63
+ - **Serverless.** The run trains and samples on a shared pool that Baseten keeps
64
+ ready, so the run starts in minutes.
65
+ - **Dedicated.** The run gets its own trainer and sampler deployment. This takes
66
+ longer to start. The deployment stays provisioned, and you pay for it, until you
67
+ deactivate the run.
68
+
69
+ The config does not choose between the two. The model and your workspace's access
70
+ decide it. Qwen3.6-35B-A3B, GLM-5.3 and GLM-5.3-Flash have serverless pools. The
71
+ quickstarts below train Qwen/Qwen3.6-35B-A3B.
72
+ Some patterns and examples train other models. The
73
+ [examples table](examples/README.md) gives the model of each example and how that
74
+ model runs.
75
+
76
+ > [!NOTE]
77
+ > Contact Baseten to get access to a serverless pool, to train a model that has no
78
+ > pool, or to get dedicated capacity.
79
+
80
+ ## RL
81
+
82
+ Loops trains on what your agent did; the cookbook runs your agent on your tasks and
83
+ turns each episode into training data with the exact tokens the model sampled.
84
+
85
+ ### How it works
86
+
87
+ <picture>
88
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/core-loop-dark.svg">
89
+ <img alt="The core loop as seven numbered steps: the run schedules episodes on the runtime; the runtime runs your agent in its environment; model calls go through the model client to the sampler; the client records the exact tokens; rewards come back through the runtime; the run sends training batches to the LoRA trainer; the trainer publishes the new policy to the sampler." src="docs/assets/core-loop.svg">
90
+ </picture>
91
+
92
+ 1. The **run** schedules episodes on the **runtime** (Harbor, or a custom runtime).
93
+ 2. The runtime runs your **agent** in its environment.
94
+ 3. Every model call the agent makes goes through the cookbook's **model client** to the
95
+ sampler.
96
+ 4. The model client records the exact tokens the sampler returned.
97
+ 5. The environment's verifier scores the episode, and the reward comes back through
98
+ the runtime.
99
+ 6. The run joins tokens and rewards into training batches for the LoRA trainer.
100
+ 7. The trainer publishes the new policy to the sampler, and the next episodes use it.
101
+
102
+ So the responsibilities split cleanly:
103
+
104
+ - **You bring** an environment (tasks, sandboxes, a verifier that produces rewards)
105
+ and an agent that decides what to do in it. The agent owns its prompts, tools,
106
+ history, and stopping rules.
107
+ - **The cookbook brings** the model client, which renders messages with the model's
108
+ own chat template and keeps the exact token IDs and logprobs; rollout scheduling
109
+ across sampling and grading, sync or async; GRPO advantages (reward minus the group
110
+ mean, not divided by its standard deviation) and datum packing; the
111
+ Loops trainer transport, checkpoints, and metrics.
112
+
113
+ ### Pick a pattern
114
+
115
+ Where your agent runs decides most of what you write:
116
+
117
+ - **in-process**: your agent is Python the runtime calls inside the training process,
118
+ such as a Harbor `LoopsAgent` class. It can call the model directly with `llm()`.
119
+ - **local**: your agent is its own program (a binary, a CLI, another language, code
120
+ you can't edit) that the runtime launches on the training machine. It reaches the
121
+ model through the run's OpenAI-compatible endpoint.
122
+ - **remote**: your agent runs inside the sandbox, such as an agent installed in the
123
+ environment. Not supported yet.
124
+
125
+ [patterns/README.md](patterns/README.md) defines the terms, then shows each placement with
126
+ a diagram, what you write, when to use it, and who owns the sandbox on each
127
+ environment backend. Every supported pattern is a runnable directory in
128
+ [patterns/](patterns/), with a training config per backend; [examples/](examples/)
129
+ builds settings and features on top of them.
130
+
131
+ Tasks with an environment also need an environment backend (see
132
+ [environment backends](patterns/README.md#environment-backends)): a local Docker daemon
133
+ is enough to start, and Blaxel or Daytona needs its extra and its credentials.
134
+
135
+ ### Quickstart
136
+
137
+ The smallest run needs only the core install and `BASETEN_API_KEY`: no Harbor, Docker
138
+ or sandbox.
139
+
140
+ ```sh
141
+ uv run loops check patterns/custom_runtime/in_process_direct/train.toml # resolves the config, asks Loops about the model; launches nothing
142
+ uv run loops run patterns/custom_runtime/in_process_direct/train.toml # provisions Loops resources (billable)
143
+ ```
144
+
145
+ `check` launches no sandbox and no Loops trainer (on a first run it still downloads the
146
+ tokenizer and any remote dataset), but it is not read-only: it writes a
147
+ fresh run directory under `<output_dir>/preflight/`, with its own resource journal,
148
+ and whatever the runtime writes while it prepares.
149
+
150
+ This is [custom runtime, in-process, direct](patterns/custom_runtime/in_process_direct/):
151
+ an `Episode` asks the model to name a hidden game once and scores the reply itself, so
152
+ the reward climbs within a few steps. Every training setting can be overridden on the
153
+ command line; `loops run --help` lists them with defaults.
154
+
155
+ With Harbor tasks, start from [Harbor, in-process, direct](patterns/harbor/in_process_direct/)
156
+ instead: the same one-call agent, on the shared [hill-climb task](tasks/hill_climb/).
157
+ A Harbor trial always starts an environment, for the agent's answer and the verifier,
158
+ so even this task runs in a sandbox: `train.toml` on local Docker (`--extra harbor`),
159
+ or `train_blaxel.toml` on Blaxel with no Docker (`--extra harbor-blaxel` and Blaxel
160
+ credentials). Every other pattern is a directory beside these in [patterns/](patterns/),
161
+ and [examples/](examples/) adds settings and features on top.
162
+
163
+ If a run crashes, the sandboxes it created on Blaxel or Daytona are in its resource
164
+ journal, and `cleanup` releases them:
165
+
166
+ ```sh
167
+ uv run loops cleanup patterns/harbor/in_process_direct/train_blaxel.toml --state-dir runs/harbor-direct-blaxel/<run-dir>/state
168
+ ```
169
+
170
+ Docker sandboxes are Harbor's and not in the journal; after a crashed Docker run, check
171
+ `docker ps`.
172
+
173
+ The training process runs where you start it. It renders every turn's prompt, holds
174
+ each live conversation's tokens and opens files and sockets for each live attempt
175
+ (`check` refuses an open-file limit too low for them), so its CPU, memory and open
176
+ files grow with `max_concurrent_rollouts` and context length. A laptop
177
+ is enough for the patterns here; for high concurrency with long contexts, or a run that
178
+ must outlast your laptop, start it on a dev box.
179
+
180
+ ## SFT
181
+
182
+ Supervised fine-tuning needs no runtime, pattern or sandbox: only your data and a
183
+ Loops trainer.
184
+
185
+ ### Quickstart
186
+
187
+ ```sh
188
+ uv run loops check examples/sft_tool_use/sft.toml # renders every row; launches nothing
189
+ uv run loops run examples/sft_tool_use/sft.toml # provisions a Loops trainer (billable)
190
+ ```
191
+
192
+ ### Data
193
+
194
+ Data is OpenAI chat fine-tuning JSONL (`messages`, `tools`, a per-turn `weight`), or
195
+ already tokenized `input_ids` and `weights` for full control. Each conversation is
196
+ rendered with the trained model's chat template, which decides the targets: every
197
+ trained turn learns its own stop token, in the context it was generated in. `check`
198
+ reports what trains, what is split per turn and what is refused, with the reason.
199
+ [docs/reference/sft.md](docs/reference/sft.md) has the contracts, the rule, the
200
+ metrics and resume. [examples/sft_toucan](examples/sft_toucan/) trains on real
201
+ tool-agent trajectories from Hugging Face and compares the base model and the adapter
202
+ on held-out conversations; [examples/sft_tool_use](examples/sft_tool_use/) is a small
203
+ synthetic one.
204
+
205
+ ## Use it as a library
206
+
207
+ ```python
208
+ from loops_cookbook.project import load
209
+
210
+ project = load("train.toml", env_file=".env")
211
+ report = await project.check()
212
+ print("\n".join(report.describe()))
213
+ outcome = await project.train()
214
+ ```
215
+
216
+ `load()` reads a TOML or JSON config, and its `recipe` key picks the recipe, as it does
217
+ for `loops`. It keeps `project.path`, `project.source` and `project.config`, and makes
218
+ the config's directory importable. Pass dotted overrides as
219
+ `overrides={"training.max_steps": 5}`. A path in the config is relative to the config.
220
+ A symlinked config is the file it points to, so its paths, modules and `.env` are
221
+ beside that file. A path in an override, and the output directory, are relative to the
222
+ working directory when `load()` runs.
223
+
224
+ `load()` reads `.env` only when you pass `env_file`, which is relative to the config.
225
+ It sets only variables that the process does not set. `loops` always loads `.env`
226
+ beside the config and in the working directory, with the same rule.
227
+
228
+ `loops check` first prints what the config used, and a run's `run.log` begins with
229
+ the same lines:
230
+
231
+ ```text
232
+ Config: /home/me/project/train.toml -> /home/me/shared/train.toml
233
+ paths, modules: beside /home/me/shared
234
+ .env: /home/me/shared/.env, /home/me/project/.env
235
+ runs: /home/me/project/runs
236
+ ```
237
+
238
+ Both operations are async. `check()` does what `loops check` does and returns a report;
239
+ `describe()` gives the lines `loops check` prints after those; `project.describe()`
240
+ gives those. A check can download model or data
241
+ files, and an RL check writes a run under `output_dir/preflight`. It starts no trainer.
242
+ `train()` does what `loops run` does and returns the run's `Outcome`. The library
243
+ does not configure logging; that stays with your application. For custom wiring, use
244
+ each recipe's `recipe.train` and `recipe.check` directly.
245
+
246
+ - `loops_cookbook.runtime`: the `RolloutRuntime` contract a runtime implements, and
247
+ the attempt and evidence types it receives. `[runtime].factory` names the
248
+ runtime's factory.
249
+ - `loops_cookbook.model_access`: attempt leases, capture, `ModelAccessMode`, and the
250
+ OpenAI-compatible gateway for agents that speak Chat Completions (a runtime whose
251
+ model access is `openai_http`).
252
+ - `loops_cookbook.rl`: the RL recipe. Its core is environment-agnostic: `Run`,
253
+ `Pipeline`, `Trainer`, GRPO. `rl.cli` and `rl.recipe` are the composition roots that
254
+ wire it to a runtime and providers, as `sft.cli` and `sft.recipe` are for SFT.
255
+ - `loops_cookbook.llm`: `LoopsLLM`, the handle a runtime's agents call the model
256
+ through, the model client, and the Prime renderer adapter.
257
+ - `loops_cookbook.resources` and `loops_cookbook.providers`: the provider-neutral
258
+ resource registry and journal behind `attempt.services.resources`, and the
259
+ `[providers.<name>]` adapters it acts through.
260
+ - `loops_cookbook.harbor`: Harbor as one runtime among others. `create_runtime`
261
+ and `LoopsAgent`.
262
+ - `loops_cookbook.sft`: supervised fine-tuning. Its core is its data contracts, the
263
+ target rule and `Run`; `sft.cli` and `sft.recipe` are its composition roots, and
264
+ `sft.recipe.train` is the entry point `loops run` calls.
265
+
266
+ Each name is imported from the one package that defines it.
267
+
268
+ A custom runtime is an `Episode` class (`loops_cookbook.episodes`), which the cookbook
269
+ runs as a `RolloutRuntime` and which reuses everything else;
270
+ [patterns/custom_runtime](patterns/custom_runtime/) has one for each supported agent
271
+ placement and model access, the smallest being
272
+ [in_process_direct](patterns/custom_runtime/in_process_direct/).
273
+
274
+ ## Docs
275
+
276
+ - [patterns/README.md](patterns/README.md): every pattern, with diagrams, what you write,
277
+ and when to use it; environment backends.
278
+ - [examples/README.md](examples/README.md): examples by setting and feature, built on
279
+ the patterns.
280
+ - [docs/reference/](docs/reference/README.md): the exact rules: the training loop,
281
+ model access and token capture, scheduling, resources, failures, the `Episode` API,
282
+ Harbor, Daytona, renderers, SFT, and every setting
283
+ ([KNOB_GLOSSARY.md](docs/reference/KNOB_GLOSSARY.md)).
284
+ - [docs/README.md](docs/README.md): how the cookbook is built, for developers changing
285
+ it: the principles, the engine, the interfaces, and the patterns' mechanics.
286
+ - [tests/README.md](tests/README.md): the test layout and the live tests.
287
+ - [ROADMAP.md](ROADMAP.md).
288
+
289
+ ## Contributing
290
+
291
+ Setting up, running the tests and cutting a release: [CONTRIBUTING.md](CONTRIBUTING.md).