samagotchi 0.154.1 → 0.156.0

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 (185) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +29 -1
  3. data/bin/chi +1 -1
  4. data/docs/architecture.md +12 -7
  5. data/docs/bundles.md +21 -0
  6. data/docs/cli.md +1 -1
  7. data/docs/guardrails.md +2 -2
  8. data/docs/hooks.md +1 -1
  9. data/docs/internals/anthropic.md +5 -5
  10. data/docs/internals/attached-context.md +9 -6
  11. data/docs/internals/background-tasks.md +1 -1
  12. data/docs/internals/block-renderers.md +8 -1
  13. data/docs/internals/engine.md +642 -831
  14. data/docs/internals/inline-widgets.md +136 -0
  15. data/docs/internals/llm-context-forget.md +8 -3
  16. data/docs/internals/objectives.md +8 -6
  17. data/docs/internals/participants.md +5 -5
  18. data/docs/internals/prompt-caching.md +13 -6
  19. data/docs/internals/remote-sessions.md +3 -1
  20. data/docs/internals/web-frontend.md +1 -1
  21. data/docs/internals/working-set.md +2 -1
  22. data/docs/plugins.md +2 -0
  23. data/docs/releasing.md +1 -1
  24. data/docs/sessions.md +4 -4
  25. data/docs/system-one.md +3 -2
  26. data/docs/testing.md +1 -1
  27. data/lib/samagotchi/block_renderers.rb +5 -0
  28. data/lib/samagotchi/bootstrap/config_writer.rb +1 -1
  29. data/lib/samagotchi/broadcast_command.rb +3 -3
  30. data/lib/samagotchi/bundle_command/check.rb +1 -1
  31. data/lib/samagotchi/bundle_command/try/sandbox.rb +1 -1
  32. data/lib/samagotchi/bundles/dev/manifest.yml +3 -2
  33. data/lib/samagotchi/bundles/inline-widgets/manifest.yml +11 -0
  34. data/lib/samagotchi/bundles/inline-widgets/plugin.rb +76 -0
  35. data/lib/samagotchi/bundles/system/config_modification_protocol.md +2 -2
  36. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  37. data/lib/samagotchi/child_move.rb +7 -51
  38. data/lib/samagotchi/children_status.rb +1 -1
  39. data/lib/samagotchi/cli/parent_wait.rb +1 -1
  40. data/lib/samagotchi/config.rb +17 -112
  41. data/lib/samagotchi/context_command.rb +1 -2
  42. data/lib/samagotchi/context_window.rb +3 -3
  43. data/lib/samagotchi/desktop/macos.rb +1 -1
  44. data/lib/samagotchi/engine/context_judge.rb +21 -119
  45. data/lib/samagotchi/engine/guardrails.rb +4 -2
  46. data/lib/samagotchi/engine/messages.rb +9 -6
  47. data/lib/samagotchi/engine/models.rb +5 -2
  48. data/lib/samagotchi/engine/objectives.rb +30 -80
  49. data/lib/samagotchi/engine/participants.rb +15 -10
  50. data/lib/samagotchi/engine/plugins.rb +3 -1
  51. data/lib/samagotchi/engine/questions.rb +1 -1
  52. data/lib/samagotchi/engine/side_requests.rb +26 -13
  53. data/lib/samagotchi/engine/toolkit.rb +35 -191
  54. data/lib/samagotchi/engine/turn_end.rb +1 -1
  55. data/lib/samagotchi/engine/turn_helpers.rb +16 -39
  56. data/lib/samagotchi/engine/verify.rb +7 -143
  57. data/lib/samagotchi/engine.rb +166 -98
  58. data/lib/samagotchi/engine_peers.rb +1 -1
  59. data/lib/samagotchi/event_fanout.rb +18 -12
  60. data/lib/samagotchi/guardrail_wiring.rb +83 -82
  61. data/lib/samagotchi/guardrails/gate.rb +41 -40
  62. data/lib/samagotchi/guardrails/pair_boundary.rb +2 -1
  63. data/lib/samagotchi/guardrails/review_boundary.rb +2 -1
  64. data/lib/samagotchi/guardrails/targets.rb +28 -11
  65. data/lib/samagotchi/guardrails_command.rb +1 -1
  66. data/lib/samagotchi/host_config.rb +72 -1
  67. data/lib/samagotchi/host_model.rb +2 -6
  68. data/lib/samagotchi/host_registry.rb +1 -1
  69. data/lib/samagotchi/inline_widgets.rb +325 -0
  70. data/lib/samagotchi/kernel_loop.rb +215 -313
  71. data/lib/samagotchi/llm/anthropic_wire.rb +2 -2
  72. data/lib/samagotchi/llm/backend.rb +3 -1
  73. data/lib/samagotchi/llm/chat_loop.rb +87 -49
  74. data/lib/samagotchi/llm/native_backend.rb +3 -2
  75. data/lib/samagotchi/llm_context_apply.rb +54 -1
  76. data/lib/samagotchi/llm_context_forget.rb +5 -3
  77. data/lib/samagotchi/llm_context_notice.rb +1 -1
  78. data/lib/samagotchi/llm_context_strategy.rb +7 -9
  79. data/lib/samagotchi/llm_context_view.rb +9 -0
  80. data/lib/samagotchi/model_binding.rb +3 -3
  81. data/lib/samagotchi/model_price.rb +4 -10
  82. data/lib/samagotchi/model_profile.rb +6 -6
  83. data/lib/samagotchi/model_settings.rb +37 -2
  84. data/lib/samagotchi/note_command.rb +1 -2
  85. data/lib/samagotchi/objectives_audit.rb +4 -3
  86. data/lib/samagotchi/participants.rb +2 -2
  87. data/lib/samagotchi/plugin/context.rb +1 -1
  88. data/lib/samagotchi/plugin/prompt_sections.rb +7 -0
  89. data/lib/samagotchi/plugin/sessions.rb +2 -5
  90. data/lib/samagotchi/plugin/tool_spec.rb +5 -3
  91. data/lib/samagotchi/project_env.rb +1 -1
  92. data/lib/samagotchi/question_desk.rb +1 -1
  93. data/lib/samagotchi/reasoning_history.rb +3 -3
  94. data/lib/samagotchi/reminder_carry.rb +1 -1
  95. data/lib/samagotchi/reprefill_meter.rb +45 -0
  96. data/lib/samagotchi/review_command.rb +1 -1
  97. data/lib/samagotchi/revise_anchor.rb +1 -1
  98. data/lib/samagotchi/sampling_settings.rb +3 -3
  99. data/lib/samagotchi/self_report.rb +7 -7
  100. data/lib/samagotchi/session.rb +50 -7
  101. data/lib/samagotchi/session_access/local.rb +7 -5
  102. data/lib/samagotchi/session_access/remote.rb +17 -3
  103. data/lib/samagotchi/session_archive_command.rb +2 -2
  104. data/lib/samagotchi/session_chain.rb +7 -6
  105. data/lib/samagotchi/session_continue.rb +6 -5
  106. data/lib/samagotchi/session_delete_command.rb +1 -1
  107. data/lib/samagotchi/session_manager/delivery.rb +254 -0
  108. data/lib/samagotchi/session_manager/emptiness.rb +138 -0
  109. data/lib/samagotchi/session_manager/lifecycle.rb +274 -0
  110. data/lib/samagotchi/session_manager/listing.rb +189 -0
  111. data/lib/samagotchi/session_manager/removal.rb +190 -0
  112. data/lib/samagotchi/session_manager/spawn.rb +242 -0
  113. data/lib/samagotchi/session_manager/worker_command.rb +157 -0
  114. data/lib/samagotchi/session_manager.rb +26 -1540
  115. data/lib/samagotchi/session_metrics.rb +1 -1
  116. data/lib/samagotchi/sessions_command.rb +1 -1
  117. data/lib/samagotchi/share_command.rb +1 -1
  118. data/lib/samagotchi/starting_marker.rb +65 -0
  119. data/lib/samagotchi/steer_cut_after.rb +3 -3
  120. data/lib/samagotchi/system_one/recorder.rb +49 -0
  121. data/lib/samagotchi/system_prompt.rb +37 -30
  122. data/lib/samagotchi/terminal_ui/exit_lines.rb +1 -1
  123. data/lib/samagotchi/terminal_ui.rb +2 -6
  124. data/lib/samagotchi/testing/boundary.rb +7 -0
  125. data/lib/samagotchi/testing/bundle.rb +7 -5
  126. data/lib/samagotchi/testing/install.rb +3 -2
  127. data/lib/samagotchi/testing/sessions.rb +1 -1
  128. data/lib/samagotchi/thinking.rb +3 -3
  129. data/lib/samagotchi/token_usage.rb +1 -1
  130. data/lib/samagotchi/tool_activity.rb +15 -7
  131. data/lib/samagotchi/tool_declarations.rb +6 -6
  132. data/lib/samagotchi/tool_output_cut.rb +17 -0
  133. data/lib/samagotchi/tool_response.rb +4 -3
  134. data/lib/samagotchi/tool_runner.rb +96 -102
  135. data/lib/samagotchi/toolkit_binding.rb +40 -14
  136. data/lib/samagotchi/toolkit_command.rb +1 -1
  137. data/lib/samagotchi/tools/deferred_tools.rb +17 -21
  138. data/lib/samagotchi/tools/delegate.rb +10 -5
  139. data/lib/samagotchi/tools/delegate_result.rb +4 -4
  140. data/lib/samagotchi/tools/index_hint.rb +14 -0
  141. data/lib/samagotchi/tools/registry.rb +64 -44
  142. data/lib/samagotchi/tools/send_note.rb +4 -6
  143. data/lib/samagotchi/tools/tool_index.rb +150 -102
  144. data/lib/samagotchi/tools/tool_surface.rb +187 -0
  145. data/lib/samagotchi/turn_context.rb +68 -0
  146. data/lib/samagotchi/turn_stages/context_judge.rb +172 -0
  147. data/lib/samagotchi/turn_stages/objectives.rb +150 -0
  148. data/lib/samagotchi/turn_stages/toolkit_suggestion.rb +257 -0
  149. data/lib/samagotchi/turn_stages/verify_anchors.rb +168 -0
  150. data/lib/samagotchi/turn_stages/warmup.rb +82 -0
  151. data/lib/samagotchi/turn_state.rb +46 -4
  152. data/lib/samagotchi/version.rb +1 -1
  153. data/lib/samagotchi/vision_support.rb +3 -3
  154. data/lib/samagotchi/web/app.rb +15 -8
  155. data/lib/samagotchi/web/markdown_renderer.rb +39 -14
  156. data/lib/samagotchi/web/message_display.rb +1 -1
  157. data/lib/samagotchi/web/participant_access.rb +2 -2
  158. data/lib/samagotchi/web/public/app.js +5 -1
  159. data/lib/samagotchi/web/public/block_host.js +74 -199
  160. data/lib/samagotchi/web/public/block_renderers.css +2 -0
  161. data/lib/samagotchi/web/public/block_source.js +7 -4
  162. data/lib/samagotchi/web/public/block_watch.js +256 -0
  163. data/lib/samagotchi/web/public/composer_fold.js +3 -0
  164. data/lib/samagotchi/web/public/index.html +28 -9
  165. data/lib/samagotchi/web/public/inline_widgets.js +146 -0
  166. data/lib/samagotchi/web/public/owner_verify.js +1 -1
  167. data/lib/samagotchi/web/public/participant.js +1 -1
  168. data/lib/samagotchi/web/public/revise_stack.js +1 -1
  169. data/lib/samagotchi/web/public/stage_watch.js +6 -2
  170. data/lib/samagotchi/web/public/text_roots.js +1 -1
  171. data/lib/samagotchi/web/public/verify_target.js +1 -1
  172. data/lib/samagotchi/web/public/widget_picks.js +130 -0
  173. data/lib/samagotchi/web/public/widget_walk.js +230 -0
  174. data/lib/samagotchi/web/public/widgets.css +70 -0
  175. data/lib/samagotchi/web/session_access_routes.rb +3 -3
  176. data/lib/samagotchi/web/session_control.rb +3 -3
  177. data/lib/samagotchi/web/session_create.rb +3 -3
  178. data/lib/samagotchi/web/session_hub.rb +1 -1
  179. data/lib/samagotchi/web/session_show.rb +3 -3
  180. data/lib/samagotchi/web/session_summary.rb +3 -4
  181. data/lib/samagotchi/worker.rb +55 -27
  182. data/lib/samagotchi/worker_boot.rb +184 -0
  183. data/lib/samagotchi/worker_signals.rb +1 -1
  184. data/lib/samagotchi/worker_task_wakes.rb +2 -2
  185. metadata +29 -1
@@ -4,7 +4,7 @@ require "digest"
4
4
  require "json"
5
5
  require_relative "../log"
6
6
  require_relative "utf8_scrub"
7
- require_relative "../tools/tool_index"
7
+ require_relative "../tools/index_hint"
8
8
 
9
9
  module Samagotchi
10
10
  module LLM
@@ -278,7 +278,7 @@ module Samagotchi
278
278
  # don't change; only this wire says it).
279
279
  def loaded_text(text, names)
280
280
  line = "Loaded: #{names.join(", ")}. #{LOADED_HINT}"
281
- text = text.sub("#{Tools::ToolIndex::CALL_HINT}\n\n", "")
281
+ text = text.sub("#{Tools::IndexHint::CALL_HINT}\n\n", "")
282
282
  blank?(text) ? line : "#{line}\n\n#{text}"
283
283
  end
284
284
 
@@ -19,9 +19,11 @@ module Samagotchi
19
19
  # in +messages+ (Engine#run_turn resume_from:); the replies from there on
20
20
  # keep the model's reasoning (thought blocks), as within one run. nil:
21
21
  # the run starts here, as every other turn's does.
22
+ # +context+: the run's turn (TurnContext, Engine#generate's), handed down
23
+ # the tool path explicitly; nil: the backend's own (a bare kernel's).
22
24
  class ModelBackend
23
25
  def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
24
- model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
26
+ model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
25
27
  raise NotImplementedError, "#{self.class}#complete must be implemented"
26
28
  end
27
29
  end
@@ -20,14 +20,18 @@ require_relative "../cut_policy"
20
20
  require_relative "../context_status"
21
21
  require_relative "../context_window"
22
22
  require_relative "../context_note"
23
+ require_relative "../tool_output_cut"
23
24
  require_relative "../tool_runner"
24
25
  require_relative "../tool_response"
25
26
  require_relative "../tool_ids"
26
27
  require_relative "../tool_declarations"
27
- require_relative "../tools/deferred_tools"
28
+ require_relative "../tools/tool_surface"
28
29
  require_relative "../tool_loads"
29
30
  require_relative "../vision_context"
31
+ require_relative "../llm_context_apply"
32
+ require_relative "../llm_context_view"
30
33
  require_relative "../log"
34
+ require_relative "../reprefill_meter"
31
35
  require_relative "../empty_answer_retry"
32
36
  require_relative "../steer"
33
37
  require_relative "../reasoning_history"
@@ -66,6 +70,12 @@ module Samagotchi
66
70
  # The session every request is for; Engine sets it with the adapter.
67
71
  # Goes out as a Session-Id header (OpenAIChat#chat).
68
72
  attr_accessor :session_id
73
+ # The effective model's host's client (EffectiveModel#client): what
74
+ # #context_window probes on a local host (a llama.cpp /props) and what
75
+ # a request's re-prefill is counted against. Engine sets it with the
76
+ # adapter (Engine#backend_for, under its chat backend mutex, from any
77
+ # thread a model switch runs on); nil until then (no probe).
78
+ attr_accessor :client
69
79
  # The last counted request's chars per token
70
80
  # (ContextStatus#counted_chars_per_token), carried to the next turn's
71
81
  # tracker: its first estimate counts the tool schemas the chars leave
@@ -73,14 +83,21 @@ module Samagotchi
73
83
  attr_accessor :counted_chars_per_token
74
84
 
75
85
  # @param kernel [KernelLoop] tool dispatch, thought stripping, hooks
86
+ # @param reprefill [ReprefillMeter, nil] the re-prefill baseline its
87
+ # requests count against (the Engine's, shared with its KernelLoop;
88
+ # its own by default)
76
89
  # @param adapter [OpenAIChat, nil] the host to talk to; Engine sets it
77
90
  # per turn for the effective model's host
78
91
  # @param stable_length [#call, nil] text → the length of the system
79
92
  # prompt's part every session shares (SystemPrompt#stable_length), or nil
80
93
  # @param sleeper [#call, nil] waits the given seconds before a dropped
81
94
  # stream's step is asked again (specs pass one that doesn't sleep)
82
- def initialize(kernel:, adapter: nil, stable_length: nil, sleeper: nil)
95
+ # @param context [TurnContext, nil] the turn its helpers read before any
96
+ # #complete (a bench building wire messages); a run's replaces it
97
+ def initialize(kernel:, reprefill: nil, adapter: nil, stable_length: nil, sleeper: nil, context: nil)
83
98
  @kernel = kernel
99
+ @reprefill = reprefill || ReprefillMeter.new
100
+ @turn_context = context
84
101
  @adapter = adapter
85
102
  @stable_length = stable_length
86
103
  @sleeper = sleeper || ->(seconds) { sleep(seconds) }
@@ -93,13 +110,17 @@ module Samagotchi
93
110
 
94
111
  # +reasoning_since+ (ModelBackend#complete): the resumed run's start,
95
112
  # the Run's own start then (Run#initialize, #reasoning_boundary).
113
+ # +context+: the run's turn (TurnContext, Engine#generate's): its
114
+ # settings are what the requests send, its tool calls run in it; a
115
+ # bare loop's (#turn_context) when none is given.
96
116
  def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
97
- model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
117
+ model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
98
118
  raise ArgumentError, "ChatLoop has no adapter" unless @adapter
99
119
 
120
+ @turn_context = context if context
100
121
  conversation = Array(messages).map(&:dup)
101
122
  Run.new(self, conversation, on_stream_event, cancel_controller, model_name, pending_input, start: reasoning_since)
102
- .call(max_iterations: max_iterations || 1, cap: KernelLoop.resolve_output_char_cap(max_tool_output_chars))
123
+ .call(max_iterations: max_iterations || 1, cap: ToolOutputCut.max_chars(max_tool_output_chars))
103
124
  rescue StandardError, Interrupt => e
104
125
  # A failure, or a Ctrl-C (its calls answered: ToolResponse.run_batch),
105
126
  # carries the conversation so far for the Engine to keep.
@@ -108,14 +129,14 @@ module Samagotchi
108
129
  end
109
130
 
110
131
  # Tool definitions for the request: the schemas the native prompts are
111
- # rendered from (the kernel's registry, the tools the turn's LLM
112
- # context layers offer), with the chat-only enums and closed
113
- # parameters. On an adapter that loads tools for +model+
114
- # (#loads_tools?), every tool the session reaches but doesn't declare
115
- # follows, deferred (Tools::DeferredTools: +conversation+, the
132
+ # rendered from (the turn's ToolSurface: what it declares), with the
133
+ # chat-only enums and closed parameters. On an adapter that loads
134
+ # tools for +model+ (#loads_tools?, asked per request: a refusal turns
135
+ # it off mid-turn), every tool the session reaches but doesn't declare
136
+ # follows, deferred (ToolSurface#deferred_for: +conversation+, the
116
137
  # request's, names the ones it loaded); never without a declared one.
117
138
  def tool_definitions(conversation = nil, model: nil)
118
- declared = ToolDeclarations.chat_schemas(tools.schemas(layers: llm_context_layers)).map do |schema|
139
+ declared = ToolDeclarations.chat_schemas(surface.schemas).map do |schema|
119
140
  { type: "function", function: schema.slice(:name, :description, :parameters) }
120
141
  end
121
142
  return declared if declared.empty? || !loads_tools?(model)
@@ -127,10 +148,12 @@ module Samagotchi
127
148
  end
128
149
 
129
150
  # The tools a request on a host that loads tools declares deferred
130
- # (Tools::DeferredTools).
131
- def deferred_tools(conversation)
132
- Tools::DeferredTools.list(tools, conversation, layers: llm_context_layers)
133
- end
151
+ # (ToolSurface#deferred_for).
152
+ def deferred_tools(conversation) = surface.deferred_for(conversation)
153
+
154
+ # The turn's ToolSurface (#turn_context's).
155
+ # @return [Tools::ToolSurface]
156
+ def surface = Tools::ToolSurface.of(turn_context)
134
157
 
135
158
  # Whether the adapter takes tools it doesn't declare up front for
136
159
  # +model+ (AnthropicMessages#loads_tools?); OpenAIChat doesn't.
@@ -147,22 +170,37 @@ module Samagotchi
147
170
  # The kernel's tools.
148
171
  def tools = @kernel.tools
149
172
 
150
- # The turn's LLM context layers (KernelLoop#llm_context_layers).
151
- def llm_context_layers = @kernel.llm_context_layers
173
+ # The TurnContext of the run in progress, else of the last run
174
+ # (#complete's context:); before any, the one it was built with, else a
175
+ # context of the kernel's own settings and a surface of its tools
176
+ # built now (a bare loop, Tools::ToolSurface.bare). Read on the turn's thread only.
177
+ # @return [TurnContext]
178
+ def turn_context
179
+ @turn_context || Tools::ToolSurface.bare(TurnContext.none(settings: @kernel.turn_settings), tools)
180
+ end
181
+
182
+ # The turn's LLM::TurnSettings (#turn_context's).
183
+ def settings = turn_context.settings
184
+
185
+ # The turn's LLM context layers (TurnContext#llm_context_layers).
186
+ def llm_context_layers = turn_context.llm_context_layers
152
187
 
153
188
  # The turn's LLM context strategy (LLMContextStrategy::Resolved), nil
154
189
  # when none was resolved.
155
- def llm_context = @kernel.turn_settings&.llm_context
190
+ def llm_context = settings&.llm_context
156
191
 
157
- # KernelLoop#reprefilled_tokens, the kernel's request history.
158
- def reprefilled_tokens(model, **) = @kernel.reprefilled_tokens(model, **)
192
+ # The request's re-prefilled tokens on the loop's meter, against this
193
+ # loop's host (#client): ReprefillMeter#tokens.
194
+ def reprefilled_tokens(model, **) = @reprefill.tokens(model, client: @client, **)
159
195
 
160
- # The kernel's LLMContextView, the turn's strategy.
161
- def llm_context_view = @kernel.llm_context_view
196
+ # The LLMContextView under the turn's strategy (LLMContextView.for).
197
+ def llm_context_view = LLMContextView.for(llm_context)
162
198
 
163
199
  # The strategy's own edits before a request and at turn end
164
- # (KernelLoop#apply_llm_context!).
165
- def apply_llm_context!(conversation, **) = @kernel.apply_llm_context!(conversation, **)
200
+ # (LLMContextApply.apply!), under the turn's strategy and model name.
201
+ def apply_llm_context!(conversation, **)
202
+ LLMContextApply.apply!(conversation, llm_context, model: settings&.model_name, **)
203
+ end
166
204
 
167
205
  # The running turn, for forget_outputs (KernelLoop#llm_context_turn).
168
206
  def llm_context_turn=(turn)
@@ -267,7 +305,7 @@ module Samagotchi
267
305
  TOOL_IMAGES_TEXT = "[images from tool results]"
268
306
 
269
307
  # Whether this turn's requests carry tool changes (the turn's model).
270
- def tool_change_wire? = tool_changes?(@kernel.turn_settings&.model_name)
308
+ def tool_change_wire? = tool_changes?(settings&.model_name)
271
309
 
272
310
  # The first index whose model entries carry their reasoning (nil:
273
311
  # none do) under +level+. Under turn: +since+ when given, where a
@@ -298,14 +336,14 @@ module Samagotchi
298
336
  conversation.drop(boundary).sum { |entry| entry[:role].to_s == "model" && thought?(entry) ? entry[:thinking].length : 0 }
299
337
  end
300
338
 
301
- # The turn's ReasoningHistory level (the kernel's turn_settings); drop
339
+ # The turn's ReasoningHistory level (the turn's settings); drop
302
340
  # without settings, and for a +model+ whose host refused it
303
341
  # (#reasoning_history_refused!). An adapter that sends its blocks back
304
342
  # (#replays_content?) is floored at turn: the running run's thinking
305
343
  # blocks always go back (a tool loop with thinking needs the last
306
344
  # assistant turn's), whatever the level says.
307
345
  def reasoning_history(model = nil)
308
- level = model && @refusals.refused?(:reasoning_history, model) ? :drop : @kernel.turn_settings&.reasoning_history
346
+ level = model && @refusals.refused?(:reasoning_history, model) ? :drop : settings&.reasoning_history
309
347
  level ||= :drop
310
348
  level == :drop && replays_content? ? :turn : level
311
349
  end
@@ -320,18 +358,17 @@ module Samagotchi
320
358
  @refusals.remember(:reasoning_history, model)
321
359
  end
322
360
 
323
- # The turn's VisionContext (the Engine sets the kernel's
324
- # turn_settings), or nil.
325
- def vision = @kernel.turn_settings.vision
361
+ # The turn's VisionContext (its settings'), or nil.
362
+ def vision = settings.vision
326
363
 
327
- # The turn's configured price (the kernel's turn_settings), or nil.
328
- def price = (@kernel.turn_settings&.price if @kernel.respond_to?(:turn_settings))
364
+ # The turn's configured price (its settings'), or nil.
365
+ def price = settings&.price
329
366
 
330
- # The turn's request parameters (the kernel's turn_settings).
331
- def sampling = @kernel.turn_settings.sampling || {}
367
+ # The turn's request parameters (its settings').
368
+ def sampling = settings.sampling || {}
332
369
 
333
- # The turn's thinking level (the kernel's turn_settings).
334
- def thinking = @kernel.turn_settings.thinking || Thinking::DEFAULT
370
+ # The turn's thinking level (its settings').
371
+ def thinking = settings.thinking || Thinking::DEFAULT
335
372
 
336
373
  # The request fields the thinking level adds, as the adapter's wire
337
374
  # takes them (OpenAIChat#thinking_fields: Thinking.chat_fields); none
@@ -375,24 +412,23 @@ module Samagotchi
375
412
  def strip_model_thought(text) = @kernel.strip_model_thought(text)
376
413
 
377
414
  def tool_runner
378
- @tool_runner ||= ToolRunner.new(@kernel, window: -> { context_window(@kernel.turn_settings&.model_name) })
415
+ @tool_runner ||= ToolRunner.new(@kernel, window: ->(run_settings) { context_window(run_settings&.model_name, run_settings) })
379
416
  end
380
417
 
381
- # The window for +model+: the kernel's client probes the server it
382
- # points at (Engine keeps it on the effective model's host; a local
383
- # llama.cpp answers /props), then the host's model list, the model's
418
+ # The window for +model+: the loop's client (#client) probes the server
419
+ # it points at (a local llama.cpp answers /props), then the host's model list, the model's
384
420
  # or host's window_tokens, config, env and the default. A remote
385
- # provider has no /props to probe.
386
- def context_window(model)
387
- client = @adapter.remote? ? nil : @kernel.client
388
- ContextWindow.resolve(client: client, model: model, adapter: @adapter,
389
- setting: (@kernel.turn_settings&.window_setting if @kernel.respond_to?(:turn_settings)))
421
+ # provider has no /props to probe. +run_settings+: the LLM::TurnSettings
422
+ # whose window_setting counts (the turn's by default).
423
+ def context_window(model, run_settings = settings)
424
+ client = @adapter.remote? ? nil : @client
425
+ ContextWindow.resolve(client: client, model: model, adapter: @adapter, setting: run_settings&.window_setting)
390
426
  rescue StandardError
391
427
  nil
392
428
  end
393
429
 
394
- # The kernel's generation guard (KernelLoop#guard_generation).
395
- def guard_generation = @kernel.respond_to?(:guard_generation) ? @kernel.guard_generation : nil
430
+ # The kernel's generation guard for the turn (KernelLoop#guard_generation).
431
+ def guard_generation = @kernel.respond_to?(:guard_generation) ? @kernel.guard_generation(turn_context) : nil
396
432
 
397
433
  # A hook failing must not break the turn (as in ToolRunner).
398
434
  def fire_hook(name, event)
@@ -609,8 +645,10 @@ module Samagotchi
609
645
  @deferred = []
610
646
  @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context,
611
647
  counted_chars_per_token: loop.counted_chars_per_token)
648
+ # The run's turn: its tool calls run in it.
649
+ @turn_context = loop.turn_context
612
650
  loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context,
613
- emit: method(:emit))
651
+ emit: method(:emit), turn_id: @turn_context.id)
614
652
  end
615
653
 
616
654
  def call(max_iterations:, cap:)
@@ -875,7 +913,7 @@ module Samagotchi
875
913
  count
876
914
  end
877
915
 
878
- # The request's re-prefilled tokens (KernelLoop#reprefilled_tokens).
916
+ # The request's re-prefilled tokens (ChatLoop#reprefilled_tokens).
879
917
  def reprefill_field(usage)
880
918
  return {} unless usage&.source == :server
881
919
 
@@ -1094,7 +1132,7 @@ module Samagotchi
1094
1132
  def dispatch(tool_calls, iteration, cap)
1095
1133
  log_direct_deferred(tool_calls)
1096
1134
  calls = tool_calls.map { |tool_call| NativeToolNormalizer.normalize(tool_call) }
1097
- runs = ToolResponse.run_batch(@loop.tool_runner, calls, iteration: iteration, emit: method(:emit),
1135
+ runs = ToolResponse.run_batch(@loop.tool_runner, calls, context: @turn_context, iteration: iteration, emit: method(:emit),
1098
1136
  on_stream_event: @on_stream_event, cap: cap) do |run, index|
1099
1137
  @conversation << ToolResponse.single(run, tool_call_id: tool_calls[index].id,
1100
1138
  ids: ToolIds.next_ids(@conversation, 1))
@@ -17,7 +17,7 @@ module Samagotchi
17
17
  def provider = :native
18
18
 
19
19
  def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
20
- model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
20
+ model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
21
21
  @kernel.run(
22
22
  messages,
23
23
  max_iterations: max_iterations,
@@ -26,7 +26,8 @@ module Samagotchi
26
26
  model_name: model_name,
27
27
  max_tool_output_chars: max_tool_output_chars,
28
28
  pending_input: pending_input,
29
- reasoning_since: reasoning_since
29
+ reasoning_since: reasoning_since,
30
+ context: context || @kernel.own_context
30
31
  )
31
32
  end
32
33
  end
@@ -4,8 +4,14 @@ require "time"
4
4
  require_relative "llm_context_edit"
5
5
  require_relative "llm_context_stale"
6
6
  require_relative "llm_context_view"
7
+ require_relative "log"
8
+ require_relative "token_usage"
7
9
 
8
10
  module Samagotchi
11
+ # The ✂ row's builder (#apply!), loaded on first use: the test kit loads
12
+ # this file (through the strategy) and never emits a row.
13
+ autoload :LLMContextNotice, File.expand_path("llm_context_notice", __dir__)
14
+
9
15
  # When a layer's edits reach the prompt: the apply rule
10
16
  # (llm_context.apply, LLMContextStrategy). Every edit breaks the prompt
11
17
  # cache from the earliest entry it changes, so the edits due at one point
@@ -59,6 +65,53 @@ module Samagotchi
59
65
 
60
66
  module_function
61
67
 
68
+ # Before each request of both loops (+moment+ :request; the warm-up
69
+ # too, on its own copy, as the next turn's first request) and at the
70
+ # end of a turn the model answered (:turn_end): +llm_context+'s layers
71
+ # (LLMContextStrategy::Resolved, the turn's) stage their edits on
72
+ # +conversation+ and its apply rule (#run!) saves the batch it lets
73
+ # through as applied, so the request about to be sent (or the next
74
+ # turn's first, and the warm-up) is the first with the stubs.
75
+ # +context+: the turn's ContextStatus (payoff applies in its top bucket;
76
+ # an applied batch rebases its estimate, ContextStatus#edited!). none
77
+ # changes nothing. Logged as llm_context_apply when a batch is applied
78
+ # (+model+: the run's model name, in the line), and shown to the user as
79
+ # a ✂ row (+emit+ takes the :llm_context_edited event, LLMContextNotice;
80
+ # the warm-up's own copy, +warmup+, has neither).
81
+ # @return [Outcome]
82
+ def apply!(conversation, llm_context, moment: :request, context: nil, warmup: false, emit: nil, model: nil)
83
+ view = LLMContextView.for(llm_context)
84
+ return Outcome.none if view.none?
85
+
86
+ outcome = run!(conversation, layers: view.layers, rule: llm_context.apply, moment: moment,
87
+ protect_steps: llm_context.protect_steps, top_bucket: context&.top_bucket? || false,
88
+ changes: llm_context.stale_edits)
89
+ if outcome.applied?
90
+ # The prompt just shrank: the context estimate counts from it.
91
+ context&.edited!
92
+ unless warmup
93
+ log_applied(outcome, llm_context, moment, model)
94
+ emit_applied(emit, conversation, outcome, moment) if emit
95
+ end
96
+ end
97
+ outcome
98
+ end
99
+
100
+ def log_applied(outcome, llm_context, moment, model)
101
+ Log.info(:model, "llm_context_apply", rule: llm_context.apply, at: moment, why: outcome.why,
102
+ applied: outcome.applied.size, ids: outcome.applied.map(&:id).join(","),
103
+ staged: outcome.staged, freed: (outcome.freed_chars / TokenUsage::CHARS_PER_TOKEN).ceil,
104
+ tail: (outcome.tail_chars / TokenUsage::CHARS_PER_TOKEN).ceil,
105
+ model: model)
106
+ end
107
+
108
+ # The batch's ✂ row; a row that can't be built never breaks the turn.
109
+ def emit_applied(emit, conversation, outcome, moment)
110
+ emit.call(LLMContextNotice.event(conversation, outcome, moment: moment))
111
+ rescue StandardError => e
112
+ Log.warn(:model, "llm_context_notice_failed", error: e.class.name, message: e.message)
113
+ end
114
+
62
115
  # Stages what +layers+ find on +conversation+ and applies what +rule+
63
116
  # lets through at +moment+.
64
117
  # @param top_bucket [Boolean] the context is in the top ContextStatus bucket
@@ -160,6 +213,6 @@ module Samagotchi
160
213
  end
161
214
  end
162
215
 
163
- private_class_method :stage, :choose, :measure, :saved_staged
216
+ private_class_method :stage, :choose, :measure, :saved_staged, :log_applied, :emit_applied
164
217
  end
165
218
  end
@@ -52,9 +52,11 @@ module Samagotchi
52
52
  # The turn a forget_outputs call runs in: its conversation (the
53
53
  # entries the edits are saved on), its ContextStatus (nil: none) and
54
54
  # its stream (+emit+, nil: none), which gets an applied batch's ✂ row
55
- # (LLMContextNotice).
56
- Turn = Data.define(:conversation, :context, :emit) do
57
- def initialize(emit: nil, **fields) = super
55
+ # (LLMContextNotice); +turn_id+: the Engine turn the run is for
56
+ # (TurnContext#id; nil: none), so a reader tells the running turn's
57
+ # conversation from the last one's (Engine#live_conversation).
58
+ Turn = Data.define(:conversation, :context, :emit, :turn_id) do
59
+ def initialize(emit: nil, turn_id: nil, **fields) = super
58
60
  end
59
61
 
60
62
  # One output a call may name: its entry, its ToolIds ref, its tool,
@@ -7,7 +7,7 @@ require_relative "token_usage"
7
7
  module Samagotchi
8
8
  # The ✂ row a turn gets for a batch of LLM context edits the apply rule
9
9
  # let through (LLMContextApply::Outcome#applied?): the :llm_context_edited
10
- # event both loops emit (KernelLoop#apply_llm_context!, its +emit+), at a
10
+ # event both loops emit (LLMContextApply.apply!, its +emit+), at a
11
11
  # request (+moment+ :request; a forget_outputs call's batch too) or at the
12
12
  # end of a turn (:turn_end); never for the warm-up, a held or a staged
13
13
  # batch, or a restore (the forget_outputs row says it). The web and the
@@ -35,11 +35,9 @@ module Samagotchi
35
35
  LAYERS = %i[stale forget].freeze
36
36
  # The layers a turn can run under so far.
37
37
  BUILT = %i[stale forget].freeze
38
- # The sentence forget_outputs' description carries (global only):
39
- # the plan's D7 line, adapted from CLM's steering example.
38
+ # The sentence forget_outputs' description carries (global only; its
39
+ # default is Config::DEFAULT_LLM_CONTEXT_POLICY).
40
40
  POLICY_SETTING = "llm_context.policy"
41
- DEFAULT_POLICY = "Tidy at subtask boundaries: once a subtask is done, forget its tool outputs and note what it " \
42
- "established; keep anything you'll still edit against."
43
41
 
44
42
  APPLY_SETTING = "llm_context.apply"
45
43
  APPLY_KEY = "llm_context_apply"
@@ -174,7 +172,7 @@ module Samagotchi
174
172
  # The strategy for +target+'s turn.
175
173
  # @param target [HostRegistry::ModelTarget, nil]
176
174
  # @param names [Array<String>] HostRegistry#lookup_names
177
- # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
175
+ # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
178
176
  # @param session [Array<Symbol>, nil] the session's own layers ([]: none)
179
177
  # @param session_apply [Symbol, nil] the session's own apply rule
180
178
  # @param session_budget [Integer, nil] the session's own budget (0: off)
@@ -187,7 +185,7 @@ module Samagotchi
187
185
  # #resolve, with where each value came from.
188
186
  # @return [Explained]
189
187
  def explain(target, names:, models: nil, session: nil, session_apply: nil, session_budget: nil)
190
- models ||= ConfigFile.model_settings
188
+ models ||= ModelSettings.all
191
189
  layers, source, where = layers_for(target, names, models, session)
192
190
  apply, apply_origin = apply_for(target, names, models, session_apply)
193
191
  budget, budget_origin = budget_for(target, names, models, session_budget)
@@ -236,7 +234,7 @@ module Samagotchi
236
234
  def budget_for(target, names, models, session_budget)
237
235
  return [session_budget.positive? ? session_budget : nil, SESSION_ORIGIN] unless session_budget.nil?
238
236
 
239
- if (setting = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models))
237
+ if (setting = ModelSettings.find(names, :llm_context_budget_tokens, models: models))
240
238
  return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
241
239
  end
242
240
 
@@ -249,7 +247,7 @@ module Samagotchi
249
247
  def layers_for(target, names, models, session)
250
248
  return [session, :session, SESSION_ORIGIN.where] if session
251
249
 
252
- if (setting = ConfigFile.model_setting(names, :llm_context_strategy, models: models))
250
+ if (setting = ModelSettings.find(names, :llm_context_strategy, models: models))
253
251
  return [setting.value, :model_setting, "models: #{setting.key}"]
254
252
  end
255
253
 
@@ -263,7 +261,7 @@ module Samagotchi
263
261
  def apply_for(target, names, models, session_apply)
264
262
  return [session_apply, SESSION_ORIGIN] if session_apply
265
263
 
266
- if (setting = ConfigFile.model_setting(names, :llm_context_apply, models: models))
264
+ if (setting = ModelSettings.find(names, :llm_context_apply, models: models))
267
265
  return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
268
266
  end
269
267
 
@@ -73,6 +73,15 @@ module Samagotchi
73
73
  end
74
74
  end
75
75
 
76
+ # The view under +llm_context+'s strategy (LLMContextStrategy::Resolved,
77
+ # a turn's TurnSettings#llm_context), none without one: what both loops
78
+ # format the conversation through, so the warm-up warms the prompt the
79
+ # next turn sends.
80
+ # @return [LLMContextView]
81
+ def self.for(llm_context)
82
+ new(strategy: llm_context&.strategy || NONE)
83
+ end
84
+
76
85
  # @param strategy [Symbol, Array<Symbol>] :none, or the layers
77
86
  def initialize(strategy: NONE)
78
87
  @layers = strategy == NONE ? [] : Array(strategy).map(&:to_sym) & LAYERS
@@ -8,7 +8,7 @@ module Samagotchi
8
8
  # An Engine's model choice (ModelChoice: the model as given and as typed)
9
9
  # and the prompt profile resolved for it, under one mutex; the counterpart
10
10
  # of ToolkitBinding. The memory overlay keys follow the choice
11
- # (#sync_model_key!).
11
+ # (#sync_model_key!), which each turn's TurnContext takes.
12
12
  #
13
13
  # The choice changes in one assignment under the mutex (#switch!), so a
14
14
  # reader on another thread sees the old pair or the new one. A resolution
@@ -126,13 +126,13 @@ module Samagotchi
126
126
  # The memory overlay key follows the model sent (ModelOverlay.key_for
127
127
  # its id). A model typed as an alias used to key overlays by the alias
128
128
  # (before aliases were applied there): that key is read when the
129
- # target's overlay is missing (KernelLoop#sync_model_key!).
129
+ # target's overlay is missing. A turn takes both in its TurnContext
130
+ # (Engine#generate): memory_read and the gate read them there.
130
131
  def sync_model_key!
131
132
  choice = @choice
132
133
  @model_key = ModelOverlay.key_for(@bare_name.call(choice.name))
133
134
  typed_key = ModelOverlay.key_for(@registry.parse_qualified_model(choice.typed).last)
134
135
  @fallback_model_key = typed_key == @model_key ? nil : typed_key
135
- @kernel.call.sync_model_key!(@model_key, fallback: @fallback_model_key)
136
136
  end
137
137
  end
138
138
  end
@@ -1,5 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "config"
4
+
3
5
  module Samagotchi
4
6
  # A model's price on a host (hosts.<name>.models.<id>.price), in USD per
5
7
  # 1M tokens: what a generation's cost is estimated from when the provider
@@ -13,7 +15,7 @@ module Samagotchi
13
15
  def self.parse(raw, where)
14
16
  return nil if raw.nil?
15
17
 
16
- values = raw.is_a?(Hash) ? raw.transform_keys(&:to_s).slice(*ModelPrice::KEYS) : nil
18
+ values = raw.is_a?(Hash) ? raw.transform_keys(&:to_s).slice(*Config::MODEL_PRICE_KEYS) : nil
17
19
  valid = values && values.key?("input") && values.key?("output") &&
18
20
  # YAML's .inf and .nan are Floats too: an infinite price
19
21
  # isn't one, and NaN poisons the sums.
@@ -26,12 +28,7 @@ module Samagotchi
26
28
  cache_write: values.fetch("cache_write", values["input"]), output: values["output"])
27
29
  end
28
30
 
29
- # config.rb requires model_price through host_model, so config is
30
- # required here only when a warning needs it.
31
- def self.warn_once(message)
32
- require_relative "config"
33
- ConfigFile.warn_once(message)
34
- end
31
+ def self.warn_once(message) = ConfigFile.warn_once(message)
35
32
  private_class_method :warn_once
36
33
 
37
34
  # The cost rule, one place for a turn's generation (SessionMetrics) and
@@ -63,7 +60,4 @@ module Samagotchi
63
60
  (completion_tokens * output)) / 1e6
64
61
  end
65
62
  end
66
-
67
- # The keys a price may hold (config validation checks them too).
68
- ModelPrice::KEYS = %w[input cache_read cache_write output].freeze
69
63
  end
@@ -176,8 +176,8 @@ module Samagotchi
176
176
  # @return [String] +model_name+
177
177
  def self.check_host!(model_name, env: ENV, hosts: nil)
178
178
  require_relative "config"
179
- hosts ||= Samagotchi::ConfigFile.hosts_config(env: env)
180
- parsed = Samagotchi::ConfigFile.model_ref(model_name, env: env, hosts: hosts)
179
+ hosts ||= Samagotchi::HostConfig.all(env: env)
180
+ parsed = Samagotchi::HostConfig.model_ref(model_name, env: env, hosts: hosts)
181
181
  if (other = parsed.host_conflict)
182
182
  raise UnknownHost, "alias '#{parsed.alias_name}' names host '#{other}', not '#{parsed.host_name}'; " \
183
183
  "use #{parsed.alias_name} or #{other}:#{parsed.alias_name}"
@@ -234,9 +234,9 @@ module Samagotchi
234
234
  def self.model_warning(model_name, env: ENV, hosts: nil, lists: nil, relist: nil, now: Time.now.to_i)
235
235
  require_relative "config"
236
236
  require_relative "model_list_store"
237
- hosts ||= Samagotchi::ConfigFile.hosts_config(env: env)
237
+ hosts ||= Samagotchi::HostConfig.all(env: env)
238
238
  lists ||= Samagotchi::ModelListStore
239
- parsed = Samagotchi::ConfigFile.model_ref(model_name, env: env, hosts: hosts)
239
+ parsed = Samagotchi::HostConfig.model_ref(model_name, env: env, hosts: hosts)
240
240
  host = parsed.host_name
241
241
  return nil unless host
242
242
  # Declared under hosts.<name>.models: served whatever the host lists.
@@ -323,7 +323,7 @@ module Samagotchi
323
323
  prefix = prefix.strip.downcase
324
324
  return nil if hosts.keys.any? { |k| k.to_s.downcase == prefix }
325
325
 
326
- Samagotchi::ConfigFile.disabled_host_names(env: env).include?(prefix) ? prefix : nil
326
+ Samagotchi::HostConfig.disabled_names(env: env).include?(prefix) ? prefix : nil
327
327
  end
328
328
 
329
329
  # "box/x" named host box until '/' stopped naming a host: a saved
@@ -437,7 +437,7 @@ module Samagotchi
437
437
  def self.resolve(names:, entry:, client:, bare_model:, override: nil, models: nil)
438
438
  require_relative "config"
439
439
  override ||= Samagotchi::Config.get_with_origin("model.profile")
440
- models ||= Samagotchi::ConfigFile.model_settings
440
+ models ||= Samagotchi::ModelSettings.all
441
441
  names = Array(names).map { |n| n.to_s.strip }.reject(&:empty?).uniq
442
442
 
443
443
  value, origin = override