pikuri-core 0.0.7 → 0.2.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 (60) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +17 -30
  3. data/lib/pikuri/agent/chat_transport.rb +168 -107
  4. data/lib/pikuri/agent/configurator.rb +194 -173
  5. data/lib/pikuri/agent/control/cancellable.rb +100 -70
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +107 -118
  8. data/lib/pikuri/agent/control.rb +13 -35
  9. data/lib/pikuri/agent/event.rb +144 -197
  10. data/lib/pikuri/agent/extension.rb +83 -95
  11. data/lib/pikuri/agent/history.rb +247 -0
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +169 -136
  14. data/lib/pikuri/agent/listener/token_log.rb +84 -157
  15. data/lib/pikuri/agent/listener.rb +24 -44
  16. data/lib/pikuri/agent/listener_list.rb +32 -47
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +1095 -577
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/bundler_env.rb +68 -0
  21. data/lib/pikuri/extractor/passthrough.rb +24 -31
  22. data/lib/pikuri/extractor.rb +125 -155
  23. data/lib/pikuri/file_type.rb +64 -136
  24. data/lib/pikuri/finalizers.rb +32 -47
  25. data/lib/pikuri/paths.rb +104 -13
  26. data/lib/pikuri/sanitizer.rb +46 -67
  27. data/lib/pikuri/subprocess.rb +86 -118
  28. data/lib/pikuri/testing.rb +369 -0
  29. data/lib/pikuri/tool/calculator.rb +168 -74
  30. data/lib/pikuri/tool/execute_context.rb +42 -0
  31. data/lib/pikuri/tool/parameters.rb +31 -29
  32. data/lib/pikuri/tool/result.rb +164 -0
  33. data/lib/pikuri/tool/trifecta_legs.rb +248 -0
  34. data/lib/pikuri/tool.rb +416 -67
  35. data/lib/pikuri/trifecta/contribution.rb +43 -0
  36. data/lib/pikuri/trifecta/node.rb +47 -0
  37. data/lib/pikuri/trifecta/report.rb +228 -0
  38. data/lib/pikuri/trifecta.rb +126 -0
  39. data/lib/pikuri/version.rb +1 -1
  40. data/lib/pikuri-core.rb +70 -92
  41. data/prompts/agent-loop.txt +5 -0
  42. data/prompts/pikuri-chat.txt +3 -12
  43. metadata +26 -72
  44. data/lib/pikuri/agent/context_window_detector.rb +0 -222
  45. data/lib/pikuri/agent/control/step_limit.rb +0 -111
  46. data/lib/pikuri/agent/extension_context.rb +0 -147
  47. data/lib/pikuri/agent/listener/rate_limited.rb +0 -172
  48. data/lib/pikuri/agent/synthesizer.rb +0 -171
  49. data/lib/pikuri/extractor/html.rb +0 -303
  50. data/lib/pikuri/tool/fetch.rb +0 -172
  51. data/lib/pikuri/tool/scraper.rb +0 -186
  52. data/lib/pikuri/tool/search/brave.rb +0 -198
  53. data/lib/pikuri/tool/search/duckduckgo.rb +0 -207
  54. data/lib/pikuri/tool/search/engines.rb +0 -186
  55. data/lib/pikuri/tool/search/exa.rb +0 -229
  56. data/lib/pikuri/tool/search/rate_limiter.rb +0 -92
  57. data/lib/pikuri/tool/search/result.rb +0 -29
  58. data/lib/pikuri/tool/web_scrape.rb +0 -121
  59. data/lib/pikuri/tool/web_search.rb +0 -57
  60. data/lib/pikuri/url_cache.rb +0 -112
@@ -0,0 +1,369 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'json'
4
+ require 'faraday'
5
+
6
+ module Pikuri
7
+ # Test support: run the **real** {Pikuri::Agent} (real +run_loop+, real
8
+ # listeners, real tools/extensions, real +Event+ stream, real ruby_llm loop)
9
+ # against a **scripted HTTP backend** — no server, no network, no mock agent.
10
+ #
11
+ # Not loaded by default: +require 'pikuri/testing'+ from a spec. It lives off
12
+ # the production load path (the core Zeitwerk loader ignores it).
13
+ #
14
+ # == How it works
15
+ #
16
+ # {.fake_transport} returns an ordinary {Agent::ChatTransport} whose
17
+ # +faraday_adapter+ is an anonymous +Faraday::Adapter+ serving the responses
18
+ # you scripted. Because {Agent#build_context} installs that adapter on the
19
+ # agent's *per-chat* +RubyLLM::Context+ (never the global +RubyLLM.config+),
20
+ # ruby_llm's own loop runs for real — it parses tool calls, invokes your real
21
+ # registered tools, appends observations, and re-requests — and each scripted
22
+ # entry is the model's next turn. No hand-rolled agent loop, nothing to drift
23
+ # against a ruby_llm upgrade.
24
+ #
25
+ # require 'pikuri/testing'
26
+ #
27
+ # transport = Pikuri::Testing.fake_transport do |llm|
28
+ # llm.tool_call('calculator', expression: '2 + 2') # turn 1: call a real tool
29
+ # llm.reply('The answer is 4.') # turn 2: final answer
30
+ # end
31
+ #
32
+ # agent = Pikuri::Agent.new(transport:, system_prompt: 'test') do |c|
33
+ # c.add_listener capture
34
+ # c.add_tool Pikuri::Tool::CALCULATOR
35
+ # end
36
+ # agent.run_loop(user_message: 'What is 2 + 2?')
37
+ # # the real loop ran the real calculator; capture saw ToolCall/ToolResult/Assistant
38
+ #
39
+ # == Limitations
40
+ #
41
+ # A fake transport feeds **one ordered response list**. Propagation to
42
+ # sub-agents works (they derive their transport via
43
+ # +parent.transport.with(...)+, and +Data#with+ preserves the adapter), but
44
+ # they *share* that one list — fine for a single linear script, not for
45
+ # targeting a specific sub-agent's replies. Per-sub-agent scripting is a
46
+ # future upgrade (dispatch by model id / distinct fake +api_base+).
47
+ # Only the LLM is faked: a tool's own backend is not, so an agent wiring a
48
+ # tool that spawns a server or reaches the network does so for real in a
49
+ # fake-backed spec too.
50
+ #
51
+ # == Streaming
52
+ #
53
+ # One script drives a plain agent and a +streaming: true+ one alike: each
54
+ # verb queues a {Completion}, rendered only when served — a JSON body to a
55
+ # plain request, SSE chunks to a streamed one (a tool call's arguments in
56
+ # fragments, as a server sends them). {Script#stream} only adds the choice of
57
+ # where the text splits.
58
+ module Testing
59
+ # Build a fake transport from a scripted conversation. Pass a block that
60
+ # calls {Script} verbs in the order the model should "reply"; each verb
61
+ # queues one HTTP response.
62
+ #
63
+ # @example a two-turn tool loop
64
+ # Pikuri::Testing.fake_transport do |llm|
65
+ # llm.tool_call('calculator', expression: '2 + 2')
66
+ # llm.reply('The answer is 4.')
67
+ # end
68
+ #
69
+ # @param model [String] model id the fake reports (any string; the fake
70
+ # server "knows" it)
71
+ # @param context_window [Integer, nil] baked onto the transport as its
72
+ # stated cap
73
+ # @param modalities [Hash{Symbol => Boolean}, nil] baked onto the transport
74
+ # as stated, like +context_window+; the default +{}+ refuses nothing
75
+ # @param api_base [String] the transport's base URL. Never dialed (the
76
+ # adapter answers), but a host may key display/config off it — pass the
77
+ # base of the connection this fake impersonates so a UI resolves its name.
78
+ # @param gate [Gate, nil] a latch to hold turns open mid-flight. When
79
+ # engaged ({Gate#block!}), the adapter parks before serving each response
80
+ # until {Gate#release!} — so a test can observe spinner / queued-injection
81
+ # / Ctrl+C paths through the real turn lifecycle. Default +nil+ (no gating).
82
+ # @param params [Hash{String, Symbol => Object}] extra payload keys this
83
+ # fake connection carries; they reach the request body the scripted
84
+ # adapter is handed
85
+ # @yieldparam script [Script] the conversation builder
86
+ # @return [Agent::ChatTransport] carrying the scripted adapter; pass it as
87
+ # +Agent.new(transport:)+
88
+ def self.fake_transport(model: 'fake-model', context_window: 8192, modalities: {},
89
+ api_base: 'http://fake.invalid/v1', gate: nil, params: {})
90
+ script = Script.new
91
+ yield script if block_given?
92
+ Agent::ChatTransport.new(
93
+ model: model,
94
+ provider: :openai,
95
+ assume_model_exists: true,
96
+ # Never dialed (the adapter answers); it is the transport's identity to
97
+ # a host, and the +api_base+ an +around_request+ hook is handed.
98
+ api_base: api_base,
99
+ api_key: 'not-needed',
100
+ context_window: context_window,
101
+ modalities: modalities,
102
+ faraday_adapter: build_adapter(script.responses, gate),
103
+ params: params
104
+ )
105
+ end
106
+
107
+ # The {Agent::Configurator} of a throwaway agent, for a spec that drives an
108
+ # extension's +configure+ by hand and reads back what it registered:
109
+ #
110
+ # c = Pikuri::Testing.configurator
111
+ # Pikuri::Workspace::Extension.new(filesystem: fs, confirmer: confirmer).configure(c)
112
+ # c.tools.map(&:name) # => ["read", "write", ...]
113
+ #
114
+ # @return [Agent::Configurator]
115
+ def self.configurator
116
+ captured = nil
117
+ Agent.new(transport: fake_transport, system_prompt: '') { |c| captured = c }
118
+ captured
119
+ end
120
+
121
+ # An anonymous +Faraday::Adapter+ subclass that serves +responses+ in order,
122
+ # one per HTTP request. Closes over the (mutable) list, so the queue drains
123
+ # across the several requests of one conversation regardless of how Faraday
124
+ # reuses adapter instances.
125
+ #
126
+ # @param responses [Array<Completion>] as {Script} queues them
127
+ # @param gate [Gate, nil] awaited before each response when non-nil
128
+ # @return [Class] a +Faraday::Adapter+ subclass
129
+ def self.build_adapter(responses, gate = nil)
130
+ queue = responses # captured by reference; #call shifts from it
131
+ Class.new(Faraday::Adapter) do
132
+ # +define_method+ (not +def+) so the body closes over +queue+/+gate+;
133
+ # +super+ must be explicit here (implicit super is illegal in a
134
+ # define_method).
135
+ define_method(:call) do |env|
136
+ super(env) # base builds env.response; skipping it → "finish for nil"
137
+ gate&.await # park here while the test holds the turn open
138
+ completion = queue.shift or raise "Pikuri::Testing: no scripted response left for #{env.url}"
139
+
140
+ if env.request.stream_response? # ruby_llm set req.options.on_data
141
+ # v2 on_data routes to the chunk handler only at status 200; set it
142
+ # before feeding, mirroring how a real adapter reads the status line
143
+ # ahead of the body.
144
+ env.status = 200
145
+ on_data = env.request.on_data
146
+ size = 0
147
+ completion.to_sse.each do |chunk|
148
+ size += chunk.bytesize
149
+ on_data.call(chunk, size, env)
150
+ end
151
+ save_response(env, 200, '', { 'Content-Type' => 'text/event-stream' }, nil)
152
+ else
153
+ save_response(env, 200, JSON.generate(completion.to_json_body),
154
+ { 'Content-Type' => 'application/json' }, nil)
155
+ end
156
+ @app.call(env)
157
+ end
158
+ end
159
+ end
160
+
161
+ # Collects the scripted conversation: each verb queues one {Completion} on
162
+ # {#responses}, in call order. You don't build these directly —
163
+ # {Testing.fake_transport} yields one to your block.
164
+ #
165
+ # fake_transport do |llm|
166
+ # llm.reply('hi') # plain answer
167
+ # llm.tool_call('calculator', expression: '2+2') # a tool turn
168
+ # llm.stream('The ', 'answer ', 'is ', '4.') # an answer in chosen deltas
169
+ # end
170
+ class Script
171
+ # @return [Array<Completion>] queued completions in call order
172
+ attr_reader :responses
173
+
174
+ def initialize
175
+ @responses = []
176
+ @tool_call_seq = 0
177
+ end
178
+
179
+ # Queue a plain assistant-text turn (the model's final answer for that
180
+ # step). A streaming agent gets it as a single delta.
181
+ #
182
+ # @param text [String] the assistant message content
183
+ # @return [self]
184
+ def reply(text)
185
+ stream(text)
186
+ end
187
+
188
+ # Queue an assistant turn that calls one tool. The real ruby_llm loop
189
+ # parses it, runs the real registered tool, appends the observation, and
190
+ # re-requests — so the *next* queued entry is the model's follow-up.
191
+ #
192
+ # @example
193
+ # llm.tool_call('calculator', expression: '2 + 2')
194
+ #
195
+ # @param name [String] registered tool name (e.g. +"calculator"+)
196
+ # @param arguments [Hash{Symbol => Object}] tool arguments, JSON-encoded
197
+ # into the wire call
198
+ # @return [self]
199
+ def tool_call(name, **arguments)
200
+ tool_batch([name, arguments])
201
+ end
202
+
203
+ # Queue an assistant turn that calls several tools at once — one
204
+ # +tool_calls+ array, the shape a provider sends when the model batches.
205
+ # ruby_llm runs them in order, each answered by its own +:tool+ message.
206
+ #
207
+ # llm.tool_batch(['calculator', { expression: '1 + 1' }],
208
+ # ['calculator', { expression: '2 + 2' }])
209
+ #
210
+ # What a spec needs to exercise anything treating a batch as a unit — the
211
+ # interloper's drain boundary, or which call a mid-batch unwind blames.
212
+ #
213
+ # @param calls [Array<Array(String, Hash)>] +[name, arguments]+ pairs, in
214
+ # the order the model asked for them
215
+ # @return [self]
216
+ def tool_batch(*calls)
217
+ tool_calls = calls.map do |name, arguments|
218
+ @tool_call_seq += 1
219
+ Completion::ToolCall.new(id: "call_#{@tool_call_seq}", name: name,
220
+ arguments: JSON.generate(arguments || {}))
221
+ end
222
+ @responses << Completion.new(deltas: [], tool_calls: tool_calls)
223
+ self
224
+ end
225
+
226
+ # {#reply} with the text split where you choose: a +streaming: true+
227
+ # agent emits one {Agent::Event::AssistantDelta} per +delta+, then the
228
+ # assembled {Agent::Event::Assistant}. A plain agent gets them joined.
229
+ #
230
+ # @example
231
+ # llm.stream('The ', 'answer ', 'is ', '4.')
232
+ #
233
+ # @param deltas [Array<String>] content fragments, streamed in order
234
+ # @return [self]
235
+ def stream(*deltas)
236
+ @responses << Completion.new(deltas: deltas, tool_calls: [])
237
+ self
238
+ end
239
+ end
240
+
241
+ # One scripted assistant turn, rendered to the wire as whichever shape the
242
+ # request asked for.
243
+ #
244
+ # c = Completion.new(deltas: ['The ', 'answer.'], tool_calls: [])
245
+ # c.to_json_body # => {"choices" => [{"message" => {"content" => "The answer.", ...}}], ...}
246
+ # c.to_sse # => ["data: {...\"content\":\"The \"...}\n\n", ..., "data: [DONE]\n\n"]
247
+ #
248
+ # Immutable.
249
+ Completion = Data.define(:deltas, :tool_calls) do
250
+ # @!attribute [r] deltas
251
+ # @return [Array<String>] the text, in the fragments it streams as;
252
+ # empty for a tool-only turn
253
+ # @!attribute [r] tool_calls
254
+ # @return [Array<Completion::ToolCall>] in the order the model asked
255
+
256
+ # @return [Hash{String => Object}] the OpenAI chat-completion body
257
+ def to_json_body
258
+ message = { 'role' => 'assistant', 'content' => deltas.empty? ? nil : deltas.join }
259
+ unless tool_calls.empty?
260
+ message['tool_calls'] = tool_calls.map do |call|
261
+ { 'id' => call.id, 'type' => 'function',
262
+ 'function' => { 'name' => call.name, 'arguments' => call.arguments } }
263
+ end
264
+ end
265
+ { 'model' => 'fake', 'choices' => [{ 'message' => message }], 'usage' => usage }
266
+ end
267
+
268
+ # The SSE events a server streams. Each tool call goes out the way a
269
+ # server sends it: +id+ and +name+ first, then its JSON arguments in two
270
+ # fragments keyed only by +index+, which ruby_llm's own accumulator
271
+ # joins back together.
272
+ #
273
+ # @return [Array<String>] one +data:+ event per element, +[DONE]+ last
274
+ def to_sse
275
+ text = deltas.map { |d| { 'content' => d } }
276
+ calls = tool_calls.each_with_index.flat_map do |call, index|
277
+ half = call.arguments.length / 2
278
+ [{ 'index' => index, 'id' => call.id, 'type' => 'function',
279
+ 'function' => { 'name' => call.name, 'arguments' => '' } },
280
+ { 'index' => index, 'function' => { 'arguments' => call.arguments[0...half] } },
281
+ { 'index' => index, 'function' => { 'arguments' => call.arguments[half..] } }]
282
+ end.map { |fragment| { 'tool_calls' => [fragment] } }
283
+ last = { 'delta' => {} }
284
+ last['finish_reason'] = 'tool_calls' unless tool_calls.empty?
285
+ (text + calls).map { |delta| sse_data('choices' => [{ 'delta' => delta }]) } +
286
+ [sse_data('choices' => [last], 'usage' => usage), "data: [DONE]\n\n"]
287
+ end
288
+
289
+ private
290
+
291
+ # @param body [Hash{String => Object}] one streamed chunk, less its +model+
292
+ # @return [String] its SSE event
293
+ def sse_data(body)
294
+ "data: #{JSON.generate({ 'model' => 'fake' }.merge(body))}\n\n"
295
+ end
296
+
297
+ # Nominal token counts so a {Agent::Event::Tokens} still fires.
298
+ #
299
+ # @return [Hash{String => Integer}]
300
+ def usage
301
+ { 'prompt_tokens' => 10, 'completion_tokens' => 5, 'total_tokens' => 15 }
302
+ end
303
+ end
304
+
305
+ # One tool call of a {Completion}.
306
+ #
307
+ # @!attribute [r] id
308
+ # @return [String] e.g. +"call_1"+, numbered across the whole script
309
+ # @!attribute [r] name
310
+ # @return [String] the registered tool name
311
+ # @!attribute [r] arguments
312
+ # @return [String] the arguments, already JSON-encoded
313
+ Completion::ToolCall = Data.define(:id, :name, :arguments)
314
+
315
+ # A latch that holds a fake turn open mid-flight. Pass one to
316
+ # {Testing.fake_transport}; the adapter parks (inside the HTTP call, on the
317
+ # agent's worker thread) at every response while the gate is engaged, so a
318
+ # test can observe the turn-in-progress state — spinner, queued injections,
319
+ # a Ctrl+C landing mid-turn — then let it finish.
320
+ #
321
+ # gate = Pikuri::Testing::Gate.new
322
+ # transport = Pikuri::Testing.fake_transport(gate:) { |llm| llm.stream('done') }
323
+ # gate.block!
324
+ # session.submit('work') # the real turn parks in the adapter
325
+ # # ... assert spinner / press Ctrl+C ...
326
+ # gate.release! # the turn proceeds and completes
327
+ #
328
+ # A test that engages the gate is responsible for releasing it —
329
+ # {#await} blocks with no timeout, mirroring the old stubs' +Queue#pop+.
330
+ #
331
+ # Thread-safe.
332
+ class Gate
333
+ def initialize
334
+ @mutex = Mutex.new
335
+ @cv = ConditionVariable.new
336
+ @blocked = false
337
+ end
338
+
339
+ # Engage the latch: the *next* (and every subsequent) response parks in
340
+ # {#await} until {#release!}.
341
+ #
342
+ # @return [void]
343
+ def block!
344
+ @mutex.synchronize { @blocked = true }
345
+ nil
346
+ end
347
+
348
+ # Disengage the latch and wake every parked response.
349
+ #
350
+ # @return [void]
351
+ def release!
352
+ @mutex.synchronize do
353
+ @blocked = false
354
+ @cv.broadcast
355
+ end
356
+ nil
357
+ end
358
+
359
+ # Block the calling thread while the latch is engaged. Called by the
360
+ # adapter before serving each response; a no-op when not blocked.
361
+ #
362
+ # @return [void]
363
+ def await
364
+ @mutex.synchronize { @cv.wait(@mutex) while @blocked }
365
+ nil
366
+ end
367
+ end
368
+ end
369
+ end