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.
- checksums.yaml +4 -4
- data/README.md +17 -30
- data/lib/pikuri/agent/chat_transport.rb +168 -107
- data/lib/pikuri/agent/configurator.rb +194 -173
- data/lib/pikuri/agent/control/cancellable.rb +100 -70
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +107 -118
- data/lib/pikuri/agent/control.rb +13 -35
- data/lib/pikuri/agent/event.rb +144 -197
- data/lib/pikuri/agent/extension.rb +83 -95
- data/lib/pikuri/agent/history.rb +247 -0
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +169 -136
- data/lib/pikuri/agent/listener/token_log.rb +84 -157
- data/lib/pikuri/agent/listener.rb +24 -44
- data/lib/pikuri/agent/listener_list.rb +32 -47
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +1095 -577
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/bundler_env.rb +68 -0
- data/lib/pikuri/extractor/passthrough.rb +24 -31
- data/lib/pikuri/extractor.rb +125 -155
- data/lib/pikuri/file_type.rb +64 -136
- data/lib/pikuri/finalizers.rb +32 -47
- data/lib/pikuri/paths.rb +104 -13
- data/lib/pikuri/sanitizer.rb +46 -67
- data/lib/pikuri/subprocess.rb +86 -118
- data/lib/pikuri/testing.rb +369 -0
- data/lib/pikuri/tool/calculator.rb +168 -74
- data/lib/pikuri/tool/execute_context.rb +42 -0
- data/lib/pikuri/tool/parameters.rb +31 -29
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +248 -0
- data/lib/pikuri/tool.rb +416 -67
- data/lib/pikuri/trifecta/contribution.rb +43 -0
- data/lib/pikuri/trifecta/node.rb +47 -0
- data/lib/pikuri/trifecta/report.rb +228 -0
- data/lib/pikuri/trifecta.rb +126 -0
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +70 -92
- data/prompts/agent-loop.txt +5 -0
- data/prompts/pikuri-chat.txt +3 -12
- metadata +26 -72
- data/lib/pikuri/agent/context_window_detector.rb +0 -222
- data/lib/pikuri/agent/control/step_limit.rb +0 -111
- data/lib/pikuri/agent/extension_context.rb +0 -147
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -172
- data/lib/pikuri/agent/synthesizer.rb +0 -171
- data/lib/pikuri/extractor/html.rb +0 -303
- data/lib/pikuri/tool/fetch.rb +0 -172
- data/lib/pikuri/tool/scraper.rb +0 -186
- data/lib/pikuri/tool/search/brave.rb +0 -198
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -207
- data/lib/pikuri/tool/search/engines.rb +0 -186
- data/lib/pikuri/tool/search/exa.rb +0 -229
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -92
- data/lib/pikuri/tool/search/result.rb +0 -29
- data/lib/pikuri/tool/web_scrape.rb +0 -121
- data/lib/pikuri/tool/web_search.rb +0 -57
- data/lib/pikuri/url_cache.rb +0 -112
|
@@ -3,152 +3,76 @@
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
class Agent
|
|
5
5
|
module Listener
|
|
6
|
-
# Logs the conversation's context-window consumption per
|
|
7
|
-
#
|
|
8
|
-
#
|
|
9
|
-
# {Event::
|
|
10
|
-
#
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
# next {Event::Tokens} self-corrects the headline to the new
|
|
14
|
-
# model's count.
|
|
15
|
-
#
|
|
16
|
-
# Existence rationale: catch context-window growth before the
|
|
17
|
-
# provider raises +RubyLLM::ContextLengthExceededError+.
|
|
18
|
-
# +ctx+ is the headline number — tokens consumed by the
|
|
19
|
-
# conversation *through* this turn: this turn's prompt plus
|
|
20
|
-
# its reply, both of which the model will re-process on the
|
|
21
|
-
# next turn. The +Δ+ field shows the climb between turns;
|
|
22
|
-
# +↑+ / +↓+ are the per-turn input / output sizes that drove
|
|
23
|
-
# it (matching Claude Code's convention: +↑+ is what's sent
|
|
24
|
-
# to the model, +↓+ is what comes back).
|
|
25
|
-
#
|
|
26
|
-
# == State and scope
|
|
27
|
-
#
|
|
28
|
-
# The latest snapshot lives on the instance, so one
|
|
29
|
-
# +TokenLog+ is per-conversation. Sub-agents (with their own
|
|
30
|
-
# +RubyLLM::Chat+) get a fresh instance via {#for_sub_agent}
|
|
31
|
-
# (dispatched by {ListenerList#for_sub_agent}) so their
|
|
32
|
-
# counts log against their own chat. The synthesizer rescue
|
|
33
|
-
# gets a derived list via the same hook because its synth
|
|
34
|
-
# chat is also fresh.
|
|
6
|
+
# Logs the conversation's context-window consumption per assistant
|
|
7
|
+
# turn via +Pikuri.logger_for('Tokens')+ — a running headline to catch
|
|
8
|
+
# growth before the provider raises
|
|
9
|
+
# +RubyLLM::ContextLengthExceededError+. Consumes {Event::Tokens} (one
|
|
10
|
+
# line each), {Event::HistoryLoaded} (seed the snapshot, see
|
|
11
|
+
# {#seed_snapshot}) and {Event::HistoryCompacted} (a status line only);
|
|
12
|
+
# every other variant is a no-op.
|
|
35
13
|
#
|
|
36
14
|
# == Log line shape
|
|
37
15
|
#
|
|
38
|
-
# Without a cap (no {Event::ContextCap} carrying a value):
|
|
39
|
-
#
|
|
40
16
|
# msg #1: ctx=6.8k Δ+6.8k ↑6.8k ↓0.0k
|
|
41
17
|
# msg #2: ctx=8.4k Δ+1.6k ↑1.0k ↓0.6k
|
|
18
|
+
# [researcher 0] msg #1: ctx=4.2k ... # sub-agent (Agent#id)
|
|
42
19
|
#
|
|
43
|
-
#
|
|
44
|
-
#
|
|
45
|
-
#
|
|
46
|
-
#
|
|
20
|
+
# +ctx+ is the through-this-turn snapshot (+input + cached +
|
|
21
|
+
# cache_creation + output+; see {Event::Tokens}), in absolute tokens: a
|
|
22
|
+
# host that knows the model's cap ({Agent::ChatTransport#context_window}) shows
|
|
23
|
+
# it beside. +Δ+ is the signed climb between turns
|
|
24
|
+
# (equal to +ctx+ on msg #1); +↑+/+↓+ are this turn's input/output
|
|
25
|
+
# (Claude Code's convention). Sizes are 1024-scaled with a +k+ suffix.
|
|
47
26
|
#
|
|
48
|
-
#
|
|
49
|
-
# sub-
|
|
50
|
-
#
|
|
51
|
-
# [researcher 0] msg #1: ctx=4.2k Δ+4.2k ↑4.2k ↓0.0k
|
|
52
|
-
#
|
|
53
|
-
# +ctx+ is the snapshot
|
|
54
|
-
# (+input + cached + cache_creation + output+; see
|
|
55
|
-
# {Event::Tokens}), optionally suffixed with +/<cap>+ when
|
|
56
|
-
# {#context_window_cap} is set so the operator can see how
|
|
57
|
-
# close the conversation is to the limit. Including +output+
|
|
58
|
-
# makes this turn's reply visible immediately — leaving it
|
|
59
|
-
# out would hide a long reply in the +ctx=+ headline until
|
|
60
|
-
# the next turn pulled it in as cached prompt. +Δ+ is
|
|
61
|
-
# signed: +Δ+X+ for growth, +Δ-X+ for shrinkage (legitimate
|
|
62
|
-
# if ruby_llm ever prunes between turns). On the first
|
|
63
|
-
# message the baseline is implicitly zero, so +Δ+ equals
|
|
64
|
-
# +ctx+. Sizes are scaled by 1024 and shown with one
|
|
65
|
-
# decimal + a +k+ suffix.
|
|
27
|
+
# One instance per conversation (the snapshot is instance state);
|
|
28
|
+
# sub-agents get a fresh zeroed one via {#for_sub_agent}.
|
|
66
29
|
class TokenLog < Base
|
|
67
|
-
# Subsystem logger; the per-turn
|
|
68
|
-
#
|
|
69
|
-
# +PIKURI_LOG_TOKENS+ or the global +PIKURI_LOG+.
|
|
30
|
+
# Subsystem logger; the per-turn line is +INFO+. Level via
|
|
31
|
+
# +PIKURI_LOG_TOKENS+ or +PIKURI_LOG+.
|
|
70
32
|
#
|
|
71
33
|
# @return [Logger]
|
|
72
34
|
LOGGER = Pikuri.logger_for('Tokens')
|
|
73
35
|
|
|
74
|
-
# Tokens consumed by the conversation through the most
|
|
75
|
-
#
|
|
76
|
-
#
|
|
77
|
-
# re-process. Equals +input + cached + cache_creation +
|
|
78
|
-
# output+ from the latest {Event::Tokens}. Zero until the
|
|
79
|
-
# first {Event::Tokens} arrives.
|
|
36
|
+
# Tokens consumed by the conversation through the most recent turn
|
|
37
|
+
# (+input + cached + cache_creation + output+ from the latest
|
|
38
|
+
# {Event::Tokens}). Zero until the first arrives.
|
|
80
39
|
#
|
|
81
40
|
# @return [Integer]
|
|
82
41
|
attr_reader :context_window_size
|
|
83
42
|
|
|
84
|
-
#
|
|
85
|
-
#
|
|
86
|
-
# set, the +ctx=+ field renders as +ctx=<used>/<cap>+
|
|
87
|
-
# instead of just +ctx=<used>+. {Agent#initialize} emits a
|
|
88
|
-
# one-shot {Event::ContextCap} at construction; this
|
|
89
|
-
# listener picks the value off it and caches it here. An
|
|
90
|
-
# instance constructed bare (e.g. in tests, or by
|
|
91
|
-
# {#for_sub_agent}) defaults to +nil+.
|
|
92
|
-
#
|
|
93
|
-
# @return [Integer, nil]
|
|
94
|
-
attr_accessor :context_window_cap
|
|
95
|
-
|
|
96
|
-
# @return [String] owning agent's id ({Agent#id}). Empty by
|
|
97
|
-
# default (main agent); set by {#for_sub_agent} from the
|
|
98
|
-
# sub-agent's generated id so the log lines can be
|
|
99
|
-
# prefixed with +[<id>] +. Read-only — for a sub-agent's
|
|
100
|
-
# listener you get a fresh instance via {#for_sub_agent}.
|
|
43
|
+
# @return [String] owning agent's id ({Agent#id}); empty for the main
|
|
44
|
+
# agent, set by {#for_sub_agent} so log lines get an +[<id>] + prefix.
|
|
101
45
|
attr_reader :id
|
|
102
46
|
|
|
103
|
-
# The most recent status line, *without* the +[<id>] +
|
|
104
|
-
# prefix
|
|
105
|
-
#
|
|
106
|
-
#
|
|
107
|
-
#
|
|
108
|
-
# {#on_status_line}
|
|
109
|
-
# themselves. Empty until the first {Event::Tokens} has
|
|
110
|
-
# been processed. Hosts that
|
|
111
|
-
# want to surface the current context-window snapshot in
|
|
112
|
-
# their own UI (e.g. a TUI status footer) read this
|
|
113
|
-
# instead of re-implementing the formatting. Hosts that
|
|
114
|
-
# want to be *pushed* each new line instead of polling
|
|
115
|
-
# set {#on_status_line}.
|
|
47
|
+
# The most recent status line, *without* the +[<id>] + prefix (the
|
|
48
|
+
# prefix is {LOGGER}'s concern; consumers get the id separately via
|
|
49
|
+
# {#id} / {#on_status_line} and choose their own presentation). Empty
|
|
50
|
+
# until the first {Event::Tokens}. Hosts surfacing the snapshot in
|
|
51
|
+
# their own UI (a TUI footer) read this; hosts wanting to be pushed set
|
|
52
|
+
# {#on_status_line}. Why these live here: +D_token_log_status_line+.
|
|
116
53
|
#
|
|
117
|
-
#
|
|
118
|
-
#
|
|
119
|
-
#
|
|
120
|
-
# {#on_event} call, which is acceptable for a status
|
|
121
|
-
# display.
|
|
54
|
+
# Safe to read from any thread (a single +String+ ivar read); a reader
|
|
55
|
+
# may briefly see the previous turn's line mid-{#on_event}, acceptable
|
|
56
|
+
# for a status display.
|
|
122
57
|
#
|
|
123
58
|
# @return [String]
|
|
124
59
|
attr_reader :status_line
|
|
125
60
|
|
|
126
|
-
# Optional status-line observer, +nil+ by default. When
|
|
127
|
-
#
|
|
128
|
-
#
|
|
129
|
-
#
|
|
130
|
-
#
|
|
131
|
-
#
|
|
132
|
-
#
|
|
133
|
-
# whatever thread runs the owning agent's loop, so the
|
|
134
|
-
# callable must hand off to its sink thread-safely; and
|
|
135
|
-
# like any listener it sits on the loop's path — an
|
|
136
|
-
# exception it raises propagates into the conversation,
|
|
137
|
-
# so handle dead connections inside the callable.
|
|
61
|
+
# Optional status-line observer, +nil+ by default. When callable, it's
|
|
62
|
+
# invoked with the owning agent's {#id} and the freshly formatted
|
|
63
|
+
# {#status_line} after every {Event::Tokens} — the push counterpart to
|
|
64
|
+
# polling {#status_line}. Fires on the agent's loop thread, so the
|
|
65
|
+
# callable must hand off to its sink thread-safely; it sits on the
|
|
66
|
+
# loop's path, so an exception it raises propagates into the
|
|
67
|
+
# conversation (handle dead connections inside it).
|
|
138
68
|
#
|
|
139
|
-
#
|
|
140
|
-
#
|
|
141
|
-
#
|
|
142
|
-
#
|
|
143
|
-
# for a sub-agent) is what lets the UI route each line to
|
|
144
|
-
# the right status row — the line itself is unprefixed
|
|
145
|
-
# (see {#status_line}). An observer assigned *after*
|
|
146
|
-
# a sub-agent spawned doesn't reach that sub-agent's
|
|
147
|
-
# instance.
|
|
69
|
+
# {#for_sub_agent} copies the observer by reference, so one callable
|
|
70
|
+
# receives parent and sub-agent lines alike — the +id+ parameter routes
|
|
71
|
+
# each to the right row. An observer assigned *after* a sub-agent
|
|
72
|
+
# spawned doesn't reach that sub-agent's instance.
|
|
148
73
|
#
|
|
149
|
-
# @return [Proc, nil] called with +(id, status_line)+ —
|
|
150
|
-
#
|
|
151
|
-
# {#status_line} +String+
|
|
74
|
+
# @return [Proc, nil] called with +(id, status_line)+ — the agent's id
|
|
75
|
+
# and the unprefixed {#status_line}
|
|
152
76
|
attr_accessor :on_status_line
|
|
153
77
|
|
|
154
78
|
# @param id [String] owning agent's id, prepended to each
|
|
@@ -159,23 +83,14 @@ module Pikuri
|
|
|
159
83
|
@id = id
|
|
160
84
|
@msg = 0
|
|
161
85
|
@context_window_size = 0
|
|
162
|
-
@context_window_cap = nil
|
|
163
86
|
@status_line = ''
|
|
164
87
|
@on_status_line = nil
|
|
165
88
|
end
|
|
166
89
|
|
|
167
|
-
# Sub-agent variant: a fresh +TokenLog+ with a zeroed
|
|
168
|
-
#
|
|
169
|
-
#
|
|
170
|
-
#
|
|
171
|
-
# forwarded params so its log lines carry the +[<id>] +
|
|
172
|
-
# prefix; defaults to +""+ when absent. The cap is left
|
|
173
|
-
# +nil+ here; the sub-agent's {Agent#initialize} emits a
|
|
174
|
-
# fresh {Event::ContextCap} immediately after construction
|
|
175
|
-
# and this listener picks it up off the stream. The
|
|
176
|
-
# {#on_status_line} observer carries over by reference, so
|
|
177
|
-
# a host streaming the parent's lines sees the sub-agent's
|
|
178
|
-
# too — distinguished by the +id+ the callable receives.
|
|
90
|
+
# Sub-agent variant: a fresh +TokenLog+ with a zeroed snapshot so the
|
|
91
|
+
# sub-agent tracks its own +RubyLLM::Chat+, carrying the sub-agent's
|
|
92
|
+
# +id:+ (for the +[<id>] + prefix) and the {#on_status_line} observer
|
|
93
|
+
# by reference.
|
|
179
94
|
#
|
|
180
95
|
# @param id [String] sub-agent's id
|
|
181
96
|
# @return [TokenLog]
|
|
@@ -191,22 +106,48 @@ module Pikuri
|
|
|
191
106
|
case event
|
|
192
107
|
in Event::Tokens => tokens
|
|
193
108
|
log_tokens(tokens)
|
|
194
|
-
in Event::
|
|
195
|
-
|
|
109
|
+
in Event::HistoryLoaded(tokens:)
|
|
110
|
+
seed_snapshot(tokens)
|
|
111
|
+
in Event::HistoryCompacted(messages_before:, messages_after:)
|
|
112
|
+
# The snapshot stays, so the next reply's Δ shows what the compaction freed.
|
|
113
|
+
@status_line = "compacted: #{messages_before} → #{messages_after} msgs, " \
|
|
114
|
+
"ctx was #{format_k(@context_window_size)}"
|
|
115
|
+
@on_status_line&.call(@id, @status_line)
|
|
196
116
|
else
|
|
197
117
|
# Every other variant: no-op.
|
|
198
118
|
end
|
|
199
119
|
end
|
|
200
120
|
|
|
201
|
-
# @return [String] short label for {
|
|
202
|
-
# the current context-window size
|
|
203
|
-
# set)
|
|
121
|
+
# @return [String] short label for {ListenerList#to_s}, including
|
|
122
|
+
# the current context-window size
|
|
204
123
|
def to_s
|
|
205
|
-
"TokenLog(ctx=#{
|
|
124
|
+
"TokenLog(ctx=#{format_k(@context_window_size)})"
|
|
206
125
|
end
|
|
207
126
|
|
|
208
127
|
private
|
|
209
128
|
|
|
129
|
+
# Restore the running size from a conversation just loaded off disk
|
|
130
|
+
# ({Event::HistoryLoaded}). Without this the footer reads +0.0k+
|
|
131
|
+
# against 40k of restored history until the next reply corrects it.
|
|
132
|
+
#
|
|
133
|
+
# The message counter deliberately stays at zero: it counts replies
|
|
134
|
+
# *this* session, and restored turns did not happen here. A history
|
|
135
|
+
# exported without usage (+tokens+ +nil+) leaves the zeroed snapshot
|
|
136
|
+
# alone rather than inventing a number.
|
|
137
|
+
#
|
|
138
|
+
# @param tokens [Event::Tokens, nil] usage of the last restored
|
|
139
|
+
# assistant message.
|
|
140
|
+
# @return [void]
|
|
141
|
+
def seed_snapshot(tokens)
|
|
142
|
+
return if tokens.nil?
|
|
143
|
+
|
|
144
|
+
@context_window_size = tokens.input.to_i + tokens.cached.to_i +
|
|
145
|
+
tokens.cache_creation.to_i + tokens.output.to_i
|
|
146
|
+
@status_line = "restored: ctx=#{format_k(@context_window_size)}"
|
|
147
|
+
@on_status_line&.call(@id, @status_line)
|
|
148
|
+
nil
|
|
149
|
+
end
|
|
150
|
+
|
|
210
151
|
# Update the snapshot, write one +INFO+ line to the
|
|
211
152
|
# subsystem logger, and push the line to the status-line
|
|
212
153
|
# observer (when one was given at construction).
|
|
@@ -231,25 +172,11 @@ module Pikuri
|
|
|
231
172
|
|
|
232
173
|
def format_line(input, output, delta)
|
|
233
174
|
sign = delta.negative? ? '-' : '+'
|
|
234
|
-
"msg ##{@msg}: ctx=#{
|
|
235
|
-
end
|
|
236
|
-
|
|
237
|
-
# +<used>+ when no cap is set, +<used>/<cap>+ when one is.
|
|
238
|
-
# Shared between {#format_line} and {#to_s} so the headline
|
|
239
|
-
# reads the same in the log stream and in {Agent#to_s}
|
|
240
|
-
# banners.
|
|
241
|
-
def format_ctx
|
|
242
|
-
base = format_k(@context_window_size)
|
|
243
|
-
return base if @context_window_cap.nil?
|
|
244
|
-
|
|
245
|
-
"#{base}/#{format_k(@context_window_cap)}"
|
|
175
|
+
"msg ##{@msg}: ctx=#{format_k(@context_window_size)} Δ#{sign}#{format_k(delta.abs)} ↑#{format_k(input)} ↓#{format_k(output)}"
|
|
246
176
|
end
|
|
247
177
|
|
|
248
|
-
# Format a token count as a 1024-scaled +k+-suffixed
|
|
249
|
-
#
|
|
250
|
-
# Uniform format keeps lines easy to scan at the cost of
|
|
251
|
-
# looking odd for very small per-turn outputs (+↓0.0k+ on
|
|
252
|
-
# tool-call acks).
|
|
178
|
+
# Format a token count as a 1024-scaled +k+-suffixed string
|
|
179
|
+
# (+nil+/+0+ → +0.0k+, 12_453 → +12.2k+).
|
|
253
180
|
#
|
|
254
181
|
# @param n [Integer, nil]
|
|
255
182
|
# @return [String]
|
|
@@ -3,56 +3,36 @@
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
class Agent
|
|
5
5
|
# Namespace for the +Agent+'s pure event consumers — {Terminal},
|
|
6
|
-
# {InMemoryEventList}, {TokenLog}, and any host
|
|
7
|
-
#
|
|
8
|
-
#
|
|
9
|
-
# everything else flows through unobserved.
|
|
6
|
+
# {InMemoryEventList}, {TokenLog}, and any host/test consumer. Each
|
|
7
|
+
# subclasses {Base} and overrides {Base#on_event} to pattern-match the
|
|
8
|
+
# {Event} variants it cares about; everything else flows through unobserved.
|
|
10
9
|
#
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
#
|
|
14
|
-
#
|
|
15
|
-
#
|
|
16
|
-
#
|
|
17
|
-
# {Agent::ExtensionContext#emit_event} (domain events) — and no
|
|
18
|
-
# listener reaches into ruby_llm's chat callbacks (that wiring
|
|
19
|
-
# lives in {Agent}).
|
|
20
|
-
#
|
|
21
|
-
# Host-facing signal holders — step budget, cancellation flag,
|
|
22
|
-
# mid-loop user input queue — are *controls*, not listeners.
|
|
23
|
-
# They live under {Pikuri::Agent::Control} and reach {Agent}
|
|
24
|
-
# through dedicated kwargs on {Agent#initialize}; they never
|
|
25
|
-
# appear in the {ListenerList} and they never receive events.
|
|
10
|
+
# These are *pure consumers*: no listener writes back into the stream
|
|
11
|
+
# (emission is the +Agent+'s and {Agent::Configurator#emit_event}'s job)
|
|
12
|
+
# or reaches into ruby_llm's callbacks (that's {Agent}'s). Host-facing signal
|
|
13
|
+
# holders (step budget, cancel flag, input queue) are *controls* under
|
|
14
|
+
# {Pikuri::Agent::Control}, not listeners — they never appear in a
|
|
15
|
+
# {ListenerList} or receive events.
|
|
26
16
|
module Listener
|
|
27
|
-
# Abstract base for event-stream consumers. Subclasses override
|
|
28
|
-
#
|
|
29
|
-
#
|
|
30
|
-
# single variant doesn't have to enumerate the rest.
|
|
17
|
+
# Abstract base for event-stream consumers. Subclasses override {#on_event}
|
|
18
|
+
# with a +case+ on the {Event} variant; the default is a no-op so a
|
|
19
|
+
# listener caring about one variant needn't enumerate the rest.
|
|
31
20
|
#
|
|
32
|
-
# Subclasses optionally define +for_sub_agent(**params)+
|
|
33
|
-
#
|
|
34
|
-
#
|
|
35
|
-
# +nil+ to opt out of propagation. See
|
|
36
|
-
# {ListenerList#for_sub_agent} for the dispatch and the
|
|
37
|
-
# per-listener semantics.
|
|
21
|
+
# Subclasses optionally define +for_sub_agent(**params)+ for a spawned
|
|
22
|
+
# sub-agent — a fresh instance, the same shared by reference, or +nil+ to
|
|
23
|
+
# opt out. See {ListenerList#for_sub_agent}.
|
|
38
24
|
class Base
|
|
39
25
|
# Single entry point for every event in the normalized stream.
|
|
40
|
-
#
|
|
41
|
-
#
|
|
42
|
-
#
|
|
43
|
-
# listener that only cares about a subset can match
|
|
44
|
-
# selectively and let everything else fall through.
|
|
26
|
+
# Subclasses override and dispatch on the variant (a +case event in
|
|
27
|
+
# Event::X(...)+); the default no-op lets a listener match a subset and
|
|
28
|
+
# ignore the rest.
|
|
45
29
|
#
|
|
46
|
-
# @param event [Event::UserTurn, Event::Thinking,
|
|
47
|
-
# Event::
|
|
48
|
-
# Event::
|
|
49
|
-
# Event::
|
|
50
|
-
#
|
|
51
|
-
#
|
|
52
|
-
# domain event emitted via
|
|
53
|
-
# {Agent::ExtensionContext#emit_event} (e.g.
|
|
54
|
-
# +Pikuri::Tasks::ListChanged+) — match the variants you
|
|
55
|
-
# know, let everything else fall through
|
|
30
|
+
# @param event [Event::UserTurn, Event::Thinking, Event::ThinkingDelta,
|
|
31
|
+
# Event::Assistant, Event::AssistantDelta, Event::ToolCall,
|
|
32
|
+
# Event::ToolResult, Event::Tokens, Event::ModelSwitched,
|
|
33
|
+
# Event::Cancelled, Object] a core
|
|
34
|
+
# loop-narration variant, or a gem domain event via
|
|
35
|
+
# {Agent::Configurator#emit_event} (e.g. a task list's +ListChanged+)
|
|
56
36
|
# @return [void]
|
|
57
37
|
def on_event(event); end
|
|
58
38
|
end
|
|
@@ -2,46 +2,42 @@
|
|
|
2
2
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
class Agent
|
|
5
|
-
#
|
|
6
|
-
#
|
|
7
|
-
# each; {Agent#initialize} stores one of these and is the sole
|
|
8
|
-
# caller of {#emit}.
|
|
5
|
+
# The composite listener an {Agent} owns: fans {#on_event} out to every
|
|
6
|
+
# wrapped {Listener::Base}, in registration order.
|
|
9
7
|
#
|
|
10
|
-
#
|
|
8
|
+
# list = ListenerList.new([Listener::Terminal.new, Listener::TokenLog.new])
|
|
9
|
+
# list.on_event(event) # both see it
|
|
10
|
+
# child = list.for_sub_agent(id: 'sub_agent 0') # the sub-agent's list
|
|
11
11
|
#
|
|
12
|
-
#
|
|
13
|
-
#
|
|
14
|
-
|
|
15
|
-
# rule lives in {#for_sub_agent}. Controls (step budget,
|
|
16
|
-
# cancellation flag, mid-loop input queue) are not listeners
|
|
17
|
-
# and do not appear in this list; their sub-agent derivation
|
|
18
|
-
# lives on each control class instead.
|
|
19
|
-
class ListenerList
|
|
12
|
+
# Being a listener itself, a list nests in another like any leaf, and
|
|
13
|
+
# {#for_sub_agent} recurses into it.
|
|
14
|
+
class ListenerList < Listener::Base
|
|
20
15
|
# @param listeners [Array<Listener::Base>] listeners that
|
|
21
16
|
# define +on_event(event)+
|
|
22
17
|
def initialize(listeners)
|
|
18
|
+
super()
|
|
23
19
|
@listeners = listeners.dup
|
|
24
20
|
end
|
|
25
21
|
|
|
22
|
+
# @param listener [Listener::Base]
|
|
23
|
+
# @return [void]
|
|
24
|
+
def add(listener)
|
|
25
|
+
@listeners << listener
|
|
26
|
+
nil
|
|
27
|
+
end
|
|
28
|
+
|
|
26
29
|
# Dispatch one event to every listener, in registration order.
|
|
27
|
-
# Exactly two callers: {Agent} (loop-narration {Event}
|
|
28
|
-
# variants) and {ExtensionContext#emit_event} (extension
|
|
29
|
-
# domain events). Listeners themselves never call this; the
|
|
30
|
-
# stream is one-way.
|
|
31
30
|
#
|
|
32
|
-
# @param event [Object] an {Agent::Event} variant or a
|
|
33
|
-
#
|
|
34
|
-
# convention a +Data+ instance)
|
|
31
|
+
# @param event [Object] an {Agent::Event} variant or a gem domain event
|
|
32
|
+
# (an immutable value, by convention a +Data+)
|
|
35
33
|
# @return [void]
|
|
36
|
-
def
|
|
34
|
+
def on_event(event)
|
|
37
35
|
@listeners.each { |l| l.on_event(event) }
|
|
38
36
|
end
|
|
39
37
|
|
|
40
|
-
# Iterate
|
|
41
|
-
#
|
|
42
|
-
#
|
|
43
|
-
# +pikuri-subagents+ when seeding a sub-agent's Configurator
|
|
44
|
-
# from the parent's list).
|
|
38
|
+
# Iterate the wrapped listeners in registration order — so a ListenerList
|
|
39
|
+
# can be passed to {Configurator#add_listeners} (the +agent+ tool seeds a
|
|
40
|
+
# sub-agent's Configurator from the parent's list).
|
|
45
41
|
#
|
|
46
42
|
# @yield [listener]
|
|
47
43
|
# @yieldparam listener [Listener::Base]
|
|
@@ -50,28 +46,17 @@ module Pikuri
|
|
|
50
46
|
@listeners.each(&block)
|
|
51
47
|
end
|
|
52
48
|
|
|
53
|
-
#
|
|
54
|
-
#
|
|
55
|
-
# +
|
|
56
|
-
#
|
|
57
|
-
#
|
|
58
|
-
#
|
|
59
|
-
#
|
|
60
|
-
# stateful sinks continue to flow into the parent's instances).
|
|
61
|
-
#
|
|
62
|
-
# The dispatch lives on each listener so adding a new
|
|
63
|
-
# listener type with sub-agent-specific behavior doesn't
|
|
64
|
-
# change this class — see {Listener::Terminal#for_sub_agent}
|
|
65
|
-
# (fresh padded instance) and
|
|
66
|
-
# {Listener::TokenLog#for_sub_agent} (fresh, zeroed snapshot
|
|
67
|
-
# with the forwarded +id:+).
|
|
49
|
+
# A new {ListenerList} where every listener has been asked for its
|
|
50
|
+
# sub-agent variant: a listener defining +for_sub_agent(**params)+ returns
|
|
51
|
+
# +self+, a replacement, or +nil+ to opt out (compacted away); listeners
|
|
52
|
+
# without the method are kept by reference (stateful sinks keep flowing
|
|
53
|
+
# into the parent's instances). The dispatch lives on each listener so a
|
|
54
|
+
# new listener type needs no change here — see
|
|
55
|
+
# {Listener::Terminal#for_sub_agent} / {Listener::TokenLog#for_sub_agent}.
|
|
68
56
|
#
|
|
69
|
-
# +params+ is
|
|
70
|
-
#
|
|
71
|
-
#
|
|
72
|
-
# bundled listeners is +id:+ (used by {Listener::TokenLog} to
|
|
73
|
-
# prefix its log lines with the sub-agent's id). Calling with
|
|
74
|
-
# no params is always valid.
|
|
57
|
+
# +params+ is forwarded as kwargs; each listener picks what it needs. The
|
|
58
|
+
# only key bundled listeners consume is +id:+ ({Listener::TokenLog}); no
|
|
59
|
+
# params is valid.
|
|
75
60
|
#
|
|
76
61
|
# @param params [Hash{Symbol => Object}]
|
|
77
62
|
# @return [ListenerList]
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Pikuri
|
|
4
|
+
class Agent
|
|
5
|
+
# Runs an +around_request:+ hook around every LLM HTTP request, by sitting
|
|
6
|
+
# in ruby_llm's +instrumenter+ slot on one +RubyLLM::Context+ — an agent's
|
|
7
|
+
# own, or any other connection that takes the same hook:
|
|
8
|
+
#
|
|
9
|
+
# RubyLLM.context do |c|
|
|
10
|
+
# c.openai_api_base = base
|
|
11
|
+
# RequestInstrumenter.install(c, hook: around_request, api_base: base, cancellable: nil)
|
|
12
|
+
# end
|
|
13
|
+
#
|
|
14
|
+
# What a hook looks like is on {Agent#initialize}. {.install} is the one
|
|
15
|
+
# place the slot is assigned: it holds a single instrumenter, so a second
|
|
16
|
+
# assignment would silently displace the hook.
|
|
17
|
+
#
|
|
18
|
+
# Only +request.ruby_llm+ reaches the hook. Every other event ruby_llm emits
|
|
19
|
+
# (+chat.ruby_llm+, +tool_call.ruby_llm+, ...) passes straight through —
|
|
20
|
+
# +chat.ruby_llm+ wraps ruby_llm's *whole* recursive loop, tool calls
|
|
21
|
+
# included, so hooking it would bracket a turn, and a throttle permit held
|
|
22
|
+
# that long deadlocks a parent against the sub-agent its tool spawns.
|
|
23
|
+
#
|
|
24
|
+
# == Implementation details
|
|
25
|
+
#
|
|
26
|
+
# One +request.ruby_llm+ block is exactly one HTTP request *including its
|
|
27
|
+
# streamed response* — measured, not assumed: every delta chunk of a
|
|
28
|
+
# streamed completion landed inside one block (ruby_llm streams through
|
|
29
|
+
# Faraday's +on_data+, driven from inside the +post+), and a forced
|
|
30
|
+
# +Faraday::TimeoutError+ retried inside that same block. So the hook spans
|
|
31
|
+
# the generation and ruby_llm's +retry_interval+ backoff, never just the
|
|
32
|
+
# first byte. Measurements: +design/decisions.md+ +D_llm_request_throttle+.
|
|
33
|
+
#
|
|
34
|
+
# Blocking inside an *instrumentation* hook is a semantic stretch — the name
|
|
35
|
+
# says observe, a throttle gates — accepted because the contract ruby_llm
|
|
36
|
+
# documents is "yield and return the block's result", which is all a gate
|
|
37
|
+
# needs.
|
|
38
|
+
#
|
|
39
|
+
# Immutable.
|
|
40
|
+
class RequestInstrumenter
|
|
41
|
+
# The one instrumented event that is exactly one HTTP request.
|
|
42
|
+
REQUEST_EVENT = 'request.ruby_llm'
|
|
43
|
+
|
|
44
|
+
# Install +hook+ on +config+'s instrumenter slot, chaining whatever it
|
|
45
|
+
# displaces (see +chain+ on {#initialize}).
|
|
46
|
+
#
|
|
47
|
+
# @param config [RubyLLM::Configuration] a context's config, inside its
|
|
48
|
+
# +RubyLLM.context+ block.
|
|
49
|
+
# @param hook [#call] an +around_request:+ hook.
|
|
50
|
+
# @param api_base [String, nil] the base URL the connection dials.
|
|
51
|
+
# @param cancellable [Control::Cancellable, nil] the turn's token, or
|
|
52
|
+
# +nil+ when no turn owns the requests.
|
|
53
|
+
# @return [RequestInstrumenter] the installed instrumenter.
|
|
54
|
+
def self.install(config, hook:, api_base:, cancellable:)
|
|
55
|
+
config.instrumenter = new(hook: hook, api_base: api_base, cancellable: cancellable,
|
|
56
|
+
chain: config.instrumenter)
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
# @param hook [#call] an +around_request:+ hook
|
|
60
|
+
# @param api_base [String, nil] the base URL the connection dials, handed
|
|
61
|
+
# to +hook+
|
|
62
|
+
# @param cancellable [Control::Cancellable, nil] handed to +hook+; +nil+
|
|
63
|
+
# when no turn owns the requests
|
|
64
|
+
# @param chain [#instrument, nil] the instrumenter this one displaces —
|
|
65
|
+
# +RubyLLM.context+ dups the global config, so a host that installed
|
|
66
|
+
# +ActiveSupport::Notifications+ would otherwise have it silently
|
|
67
|
+
# clobbered. Every event is delegated to it, hooked or not. Anything not
|
|
68
|
+
# answering +#instrument+ is dropped, as ruby_llm itself does.
|
|
69
|
+
def initialize(hook:, api_base:, cancellable:, chain: nil)
|
|
70
|
+
@hook = hook
|
|
71
|
+
@api_base = api_base
|
|
72
|
+
@cancellable = cancellable
|
|
73
|
+
@chain = chain if chain.respond_to?(:instrument)
|
|
74
|
+
freeze
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# ruby_llm's instrumenter protocol: run the block, return its value —
|
|
78
|
+
# inside the hook when +name+ is {REQUEST_EVENT}.
|
|
79
|
+
#
|
|
80
|
+
# @param name [String] the event name, e.g. +"request.ruby_llm"+
|
|
81
|
+
# @param payload [Hash, nil] ruby_llm's event payload, forwarded verbatim
|
|
82
|
+
# @yield the work being instrumented
|
|
83
|
+
# @return [Object] the block's value, or +nil+ when called without a block
|
|
84
|
+
def instrument(name, payload = nil, &block)
|
|
85
|
+
return pass(name, payload, &block) unless name.to_s == REQUEST_EVENT
|
|
86
|
+
|
|
87
|
+
@hook.call(@api_base, @cancellable) { pass(name, payload, &block) }
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
private
|
|
91
|
+
|
|
92
|
+
# @param name [String]
|
|
93
|
+
# @param payload [Hash, nil]
|
|
94
|
+
# @return [Object] the block's value
|
|
95
|
+
def pass(name, payload, &block)
|
|
96
|
+
return @chain.instrument(name, payload, &block) if @chain
|
|
97
|
+
|
|
98
|
+
block&.call
|
|
99
|
+
end
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
end
|