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
|
@@ -2,38 +2,70 @@
|
|
|
2
2
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
class Tool
|
|
5
|
-
# Evaluates a basic arithmetic expression with Python operator
|
|
6
|
-
#
|
|
7
|
-
# {
|
|
5
|
+
# Evaluates a basic arithmetic expression with Python operator syntax and
|
|
6
|
+
# semantics, via the hand-rolled recursive-descent {Parser} below. A
|
|
7
|
+
# great-circle distance, the call that motivated {FUNCTIONS}:
|
|
8
8
|
#
|
|
9
|
-
#
|
|
10
|
-
#
|
|
11
|
-
#
|
|
12
|
-
# bigdecimal and tsort, all to evaluate four-function arithmetic.
|
|
13
|
-
# The ~100 lines here implement Python's expression grammar
|
|
14
|
-
# directly, which also retires the old preprocessing step that
|
|
15
|
-
# rewrote Python's +**+ into dentaku's +^+ dialect — the model's
|
|
16
|
-
# native syntax is now simply the grammar.
|
|
9
|
+
# Calculator.calculate('6371 * acos(sin(radians(60.1699)) * sin(radians(41.3874)) + ' \
|
|
10
|
+
# 'cos(radians(60.1699)) * cos(radians(41.3874)) * ' \
|
|
11
|
+
# 'cos(radians(2.1734) - radians(24.9410)))') # => "2603.339"
|
|
17
12
|
#
|
|
18
|
-
# Scope is intentionally narrow: operators (+, -, *, /, //, %, **),
|
|
19
|
-
#
|
|
20
|
-
#
|
|
21
|
-
#
|
|
22
|
-
#
|
|
13
|
+
# Scope is intentionally narrow: operators (+, -, *, /, //, %, **), unary
|
|
14
|
+
# minus, parentheses, numeric literals, and the fixed-arity real functions
|
|
15
|
+
# and constants in {FUNCTIONS} / {CONSTANTS}. No variables, sequences,
|
|
16
|
+
# assignment or comparisons — every name is spelled the way Python spells
|
|
17
|
+
# it rather than as a pikuri dialect. See +design/decisions.md+
|
|
18
|
+
# +D_calculator_functions+.
|
|
19
|
+
#
|
|
20
|
+
# Hand-rolled rather than a gem: the previous backend (dentaku) pulled in
|
|
21
|
+
# concurrent-ruby (~16k lines — pikuri's single heaviest audit item) plus
|
|
22
|
+
# bigdecimal and tsort just for four-function arithmetic. The parser here
|
|
23
|
+
# implements Python's grammar directly, which also retires the old
|
|
24
|
+
# +**+→+^+ preprocessing (the model's native syntax is now the grammar).
|
|
23
25
|
module Calculator
|
|
24
|
-
# Raised internally for anything {.calculate} should
|
|
25
|
-
#
|
|
26
|
-
#
|
|
27
|
-
# non-finite results. The message always names the offending
|
|
28
|
-
# token or operands.
|
|
26
|
+
# Raised internally for anything {.calculate} should return as an
|
|
27
|
+
# +"Error: ..."+ observation rather than crash the loop. Names the
|
|
28
|
+
# offending token, operands or call.
|
|
29
29
|
class Error < StandardError; end
|
|
30
30
|
|
|
31
|
-
#
|
|
32
|
-
#
|
|
33
|
-
#
|
|
34
|
-
# as
|
|
35
|
-
#
|
|
36
|
-
#
|
|
31
|
+
# The callable names, as +name => [permitted argument counts, callable]+.
|
|
32
|
+
# Every entry is pure, fixed-arity and real→real: that shape *is* the
|
|
33
|
+
# closed surface, so a new entry has to fit it. Trigonometry is in
|
|
34
|
+
# radians, as Python's is — +radians+ / +degrees+ are here because the
|
|
35
|
+
# conversion is otherwise unexpressible, and a model that feeds degrees
|
|
36
|
+
# to +sin+ gets a plausible wrong answer rather than an error.
|
|
37
|
+
#
|
|
38
|
+
# @return [Hash{String => Array(Range, #call)}]
|
|
39
|
+
FUNCTIONS = {
|
|
40
|
+
'sin' => [1..1, Math.method(:sin)],
|
|
41
|
+
'cos' => [1..1, Math.method(:cos)],
|
|
42
|
+
'tan' => [1..1, Math.method(:tan)],
|
|
43
|
+
'asin' => [1..1, Math.method(:asin)],
|
|
44
|
+
'acos' => [1..1, Math.method(:acos)],
|
|
45
|
+
'atan' => [1..1, Math.method(:atan)],
|
|
46
|
+
'atan2' => [2..2, Math.method(:atan2)],
|
|
47
|
+
'hypot' => [2..2, Math.method(:hypot)],
|
|
48
|
+
'sqrt' => [1..1, Math.method(:sqrt)],
|
|
49
|
+
'exp' => [1..1, Math.method(:exp)],
|
|
50
|
+
'log' => [1..2, Math.method(:log)], # log(x) is natural; log(x, base) is Python's second form
|
|
51
|
+
'log10' => [1..1, Math.method(:log10)],
|
|
52
|
+
'log2' => [1..1, Math.method(:log2)],
|
|
53
|
+
'floor' => [1..1, ->(x) { x.floor }],
|
|
54
|
+
'ceil' => [1..1, ->(x) { x.ceil }],
|
|
55
|
+
'abs' => [1..1, ->(x) { x.abs }],
|
|
56
|
+
'radians' => [1..1, ->(deg) { deg * Math::PI / 180 }],
|
|
57
|
+
'degrees' => [1..1, ->(rad) { rad * 180 / Math::PI }]
|
|
58
|
+
}.freeze
|
|
59
|
+
|
|
60
|
+
# The names that evaluate to a number with no call syntax.
|
|
61
|
+
#
|
|
62
|
+
# @return [Hash{String => Float}]
|
|
63
|
+
CONSTANTS = { 'pi' => Math::PI, 'e' => Math::E }.freeze
|
|
64
|
+
|
|
65
|
+
# Evaluate +expression+ and return the result as a String. Parse and
|
|
66
|
+
# arithmetic failures (division by zero, overflow to infinity, complex
|
|
67
|
+
# results, a function outside its domain) come back as +"Error: ..."+ so
|
|
68
|
+
# the model self-corrects.
|
|
37
69
|
#
|
|
38
70
|
# @param expression [String] Python-syntax arithmetic expression
|
|
39
71
|
# @return [String] numeric result, or +"Error: ..."+ on failure
|
|
@@ -48,11 +80,9 @@ module Pikuri
|
|
|
48
80
|
"Error: #{e.message}"
|
|
49
81
|
end
|
|
50
82
|
|
|
51
|
-
# Integers (never
|
|
52
|
-
# true division)
|
|
53
|
-
#
|
|
54
|
-
# whole-valued floats drop the trailing +.0+ (+4 / 2+ renders as
|
|
55
|
-
# +"2"+, not +"2.0"+).
|
|
83
|
+
# Integers pass through exact (division never produces them — +/+ is
|
|
84
|
+
# Python-3 true division). Floats round to 3 places, and whole-valued
|
|
85
|
+
# floats drop the +.0+ (+4 / 2+ → +"2"+).
|
|
56
86
|
def self.format_result(result)
|
|
57
87
|
return result.to_s if result.is_a?(Integer)
|
|
58
88
|
|
|
@@ -61,32 +91,37 @@ module Pikuri
|
|
|
61
91
|
end
|
|
62
92
|
private_class_method :format_result
|
|
63
93
|
|
|
64
|
-
# Recursive-descent parser-evaluator for Python's arithmetic
|
|
65
|
-
# expression grammar:
|
|
94
|
+
# Recursive-descent parser-evaluator for Python's arithmetic grammar:
|
|
66
95
|
#
|
|
67
96
|
# additive := multiplicative (('+' | '-') multiplicative)*
|
|
68
97
|
# multiplicative := unary (('*' | '/' | '//' | '%') unary)*
|
|
69
98
|
# unary := ('+' | '-') unary | power
|
|
70
99
|
# power := atom ('**' unary)?
|
|
71
|
-
# atom := NUMBER | '(' additive ')'
|
|
100
|
+
# atom := NUMBER | NAME '(' additive (',' additive)* ')'
|
|
101
|
+
# | NAME | '(' additive ')'
|
|
72
102
|
#
|
|
73
|
-
# The +power
|
|
74
|
-
#
|
|
75
|
-
#
|
|
76
|
-
#
|
|
77
|
-
# Python parses them.
|
|
103
|
+
# The +power+→+unary+ recursion on the right operand makes +**+
|
|
104
|
+
# right-associative (+2**3**2+ is 512) and lets a sign follow it
|
|
105
|
+
# (+2**-3+); +unary+ *above* +power+ on the left makes +-2**2+ evaluate to
|
|
106
|
+
# -4 — both as Python parses them.
|
|
78
107
|
#
|
|
79
|
-
# Semantics follow Python 3 where Ruby differs: +/+ is always
|
|
80
|
-
#
|
|
81
|
-
#
|
|
82
|
-
# fractional exponent is rejected (Ruby would return a Complex).
|
|
108
|
+
# Semantics follow Python 3 where Ruby differs: +/+ is always true (float)
|
|
109
|
+
# division, +//+ floors, +2**-1+ is Float 0.5 (not a Rational), and a
|
|
110
|
+
# negative base under a fractional exponent is rejected (not a Complex).
|
|
83
111
|
class Parser
|
|
84
|
-
# One number or operator.
|
|
85
|
-
# single-
|
|
86
|
-
#
|
|
87
|
-
#
|
|
88
|
-
#
|
|
89
|
-
|
|
112
|
+
# One number, name or operator. +**+/+//+ listed before their
|
|
113
|
+
# single-char prefixes so the two-char operators win; number literals
|
|
114
|
+
# cover +42+, +4.2+, +5.+, +.5+, and e-notation; a name carries an
|
|
115
|
+
# optional +math.+ / +Math.+ qualifier as part of the token, so
|
|
116
|
+
# +math.cos+ and a bare +cos+ both parse. +\G+ anchors each match at
|
|
117
|
+
# the scan position so nothing between tokens is missed.
|
|
118
|
+
TOKEN_RE = %r{\G\s*(\*\*|//|\d+(?:\.\d*)?(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?|(?:[Mm]ath\.)?[A-Za-z_]\w*|[-+*/%(),])}
|
|
119
|
+
|
|
120
|
+
# Tail of every unknown-name error: the tool description lists the same
|
|
121
|
+
# set, but a small model recovers from the error string on the next
|
|
122
|
+
# turn instead of guessing a second name.
|
|
123
|
+
AVAILABLE = "available functions: #{FUNCTIONS.keys.join(', ')}; " \
|
|
124
|
+
"constants: #{CONSTANTS.keys.join(', ')}"
|
|
90
125
|
|
|
91
126
|
# @param expression [String] raw expression as the model wrote it
|
|
92
127
|
# @raise [Error] when +expression+ contains a character no token matches
|
|
@@ -158,13 +193,16 @@ module Pikuri
|
|
|
158
193
|
def atom
|
|
159
194
|
return parenthesized if accept('(')
|
|
160
195
|
|
|
161
|
-
token = peek
|
|
162
|
-
|
|
163
|
-
|
|
196
|
+
case (token = peek)
|
|
197
|
+
when nil then raise Error, 'unexpected end of expression'
|
|
198
|
+
when /\A[.\d]/
|
|
199
|
+
@pos += 1
|
|
200
|
+
token.match?(/[.eE]/) ? token.to_f : token.to_i
|
|
201
|
+
when /\A[A-Za-z_]/
|
|
202
|
+
@pos += 1
|
|
203
|
+
named(token)
|
|
204
|
+
else raise Error, "unexpected #{token.inspect}"
|
|
164
205
|
end
|
|
165
|
-
|
|
166
|
-
@pos += 1
|
|
167
|
-
token.match?(/[.eE]/) ? token.to_f : token.to_i
|
|
168
206
|
end
|
|
169
207
|
|
|
170
208
|
def parenthesized
|
|
@@ -174,6 +212,42 @@ module Pikuri
|
|
|
174
212
|
value
|
|
175
213
|
end
|
|
176
214
|
|
|
215
|
+
# A function call if a +(+ follows, a constant otherwise.
|
|
216
|
+
def named(token)
|
|
217
|
+
name = token.sub(/\A[Mm]ath\./, '')
|
|
218
|
+
return apply_function(name, arguments) if accept('(')
|
|
219
|
+
return CONSTANTS[name] if CONSTANTS.key?(name)
|
|
220
|
+
raise Error, "#{name} takes arguments; write #{name}(x)" if FUNCTIONS.key?(name)
|
|
221
|
+
|
|
222
|
+
raise Error, "unknown name #{token.inspect}; #{AVAILABLE}"
|
|
223
|
+
end
|
|
224
|
+
|
|
225
|
+
# The argument list of a call, positioned just past the opening +(+.
|
|
226
|
+
#
|
|
227
|
+
# @return [Array<Integer, Float>] one or more evaluated arguments
|
|
228
|
+
def arguments
|
|
229
|
+
args = [additive]
|
|
230
|
+
args << additive while accept(',')
|
|
231
|
+
raise Error, 'missing closing parenthesis' unless accept(')')
|
|
232
|
+
|
|
233
|
+
args
|
|
234
|
+
end
|
|
235
|
+
|
|
236
|
+
# +Math+ raises +DomainError+ where Python's +math+ raises +ValueError+
|
|
237
|
+
# (+acos(1.0000000001)+, reachable from real haversine rounding), and
|
|
238
|
+
# +floor+/+ceil+ raise +FloatDomainError+ on an infinite argument.
|
|
239
|
+
# Both are the model's error to see, not the loop's to die on.
|
|
240
|
+
def apply_function(name, args)
|
|
241
|
+
arities, callable = FUNCTIONS.fetch(name) { raise Error, "unknown function #{name.inspect}; #{AVAILABLE}" }
|
|
242
|
+
unless arities.cover?(args.size)
|
|
243
|
+
raise Error, "#{name} takes #{arities.to_a.join(' or ')} argument(s), got #{args.size}"
|
|
244
|
+
end
|
|
245
|
+
|
|
246
|
+
callable.call(*args)
|
|
247
|
+
rescue Math::DomainError, FloatDomainError
|
|
248
|
+
raise Error, "#{name}(#{args.join(', ')}) is undefined"
|
|
249
|
+
end
|
|
250
|
+
|
|
177
251
|
# @return [String, nil] the next token without consuming it
|
|
178
252
|
def peek
|
|
179
253
|
@tokens[@pos]
|
|
@@ -190,11 +264,9 @@ module Pikuri
|
|
|
190
264
|
token
|
|
191
265
|
end
|
|
192
266
|
|
|
193
|
-
# +/+ is Python-3 true division (always Float); +//+ floors
|
|
194
|
-
#
|
|
195
|
-
#
|
|
196
|
-
# floors like Python's +//+); +%+ delegates to Ruby's +%+,
|
|
197
|
-
# whose sign-of-divisor semantics match Python's exactly.
|
|
267
|
+
# +/+ is Python-3 true division (always Float); +//+ floors (Ruby's
|
|
268
|
+
# +Integer#/+ already floors like Python's +//+ for two Integers); +%+
|
|
269
|
+
# delegates to Ruby's +%+, whose sign-of-divisor matches Python's.
|
|
198
270
|
def apply_multiplicative(op, lhs, rhs)
|
|
199
271
|
return lhs * rhs if op == '*'
|
|
200
272
|
raise Error, 'division by zero' if rhs.zero?
|
|
@@ -206,10 +278,9 @@ module Pikuri
|
|
|
206
278
|
end
|
|
207
279
|
end
|
|
208
280
|
|
|
209
|
-
# Two Python-
|
|
210
|
-
#
|
|
211
|
-
#
|
|
212
|
-
# under a fractional exponent — is rejected loudly.
|
|
281
|
+
# Two Python-compat shims over Ruby's +**+: an Integer to a negative
|
|
282
|
+
# Integer yields a Float (Ruby → Rational), and a Complex result
|
|
283
|
+
# (negative base, fractional exponent) is rejected loudly.
|
|
213
284
|
def apply_power(base, exponent)
|
|
214
285
|
if base.is_a?(Integer) && exponent.is_a?(Integer) && exponent.negative?
|
|
215
286
|
raise Error, 'division by zero' if base.zero?
|
|
@@ -226,10 +297,18 @@ module Pikuri
|
|
|
226
297
|
end
|
|
227
298
|
end
|
|
228
299
|
|
|
229
|
-
# Arithmetic-evaluation tool backed by {Tool::Calculator.calculate}.
|
|
230
|
-
#
|
|
231
|
-
#
|
|
232
|
-
#
|
|
300
|
+
# Arithmetic-evaluation tool backed by {Tool::Calculator.calculate}. Accepts
|
|
301
|
+
# Python expression syntax (+, -, *, /, //, %, **, unary minus, parentheses,
|
|
302
|
+
# decimals) plus {Tool::Calculator::FUNCTIONS} / {Tool::Calculator::CONSTANTS},
|
|
303
|
+
# so the model emits syntax it already knows.
|
|
304
|
+
#
|
|
305
|
+
# Stays wired even beside a shell (pikuri-workshop's): it is the only
|
|
306
|
+
# *unconfirmed* float arithmetic there, since a shell's own +$((…))+ is
|
|
307
|
+
# integer-only and every interpreter that isn't must stay off the passive
|
|
308
|
+
# allowlist. See +design/decisions.md+ +D_keep_calculator+.
|
|
309
|
+
#
|
|
310
|
+
# Sharing: +P_stateless+ — arithmetic over the argument, no I/O, no state.
|
|
311
|
+
# Hand this one constant to every agent in the VM.
|
|
233
312
|
#
|
|
234
313
|
# @return [Tool]
|
|
235
314
|
CALCULATOR = new(
|
|
@@ -239,16 +318,31 @@ module Pikuri
|
|
|
239
318
|
|
|
240
319
|
Usage:
|
|
241
320
|
- Use this for any arithmetic beyond simple mental math — do not eyeball multi-digit work.
|
|
242
|
-
- Python expression syntax: +, -, *, / (true division), // (floor division), % (modulo), ** (exponentiation), unary minus, parentheses, decimal numbers.
|
|
243
321
|
- Decimal results are rounded to 3 places; integer results are exact.
|
|
244
|
-
- Failures (parse error, division by zero) come back as "Error: ..." — read the message and re-call with a corrected expression.
|
|
245
322
|
DESC
|
|
246
323
|
parameters: Parameters.build { |p|
|
|
247
324
|
p.required_string :expression,
|
|
248
|
-
'Arithmetic expression
|
|
249
|
-
'
|
|
325
|
+
'Arithmetic expression in Python syntax: + - * ' \
|
|
326
|
+
'/ (true division), // (floor division), % (modulo), ' \
|
|
327
|
+
'** (exponentiation), unary minus, parentheses, ' \
|
|
328
|
+
'decimals. Also these functions, with or without a ' \
|
|
329
|
+
'math. prefix: sin cos tan asin acos atan atan2 ' \
|
|
330
|
+
'hypot sqrt exp log (log(x) natural, log(x, base) ' \
|
|
331
|
+
'for another base) log10 log2 floor ceil abs ' \
|
|
332
|
+
'radians degrees, and the constants pi and e. ' \
|
|
333
|
+
'Trigonometric functions take RADIANS, so convert ' \
|
|
334
|
+
'degrees first: sin(radians(30)), never sin(30). ' \
|
|
335
|
+
'E.g. "155 / (58 * 1000.0 / 3600)", "2**10", or ' \
|
|
336
|
+
'"hypot(3, 4)".'
|
|
337
|
+
},
|
|
338
|
+
# The one tool whose display line *is* its observation: the value was
|
|
339
|
+
# computed here, so echoing it is structural rather than an excerpt.
|
|
340
|
+
execute: ->(expression:) {
|
|
341
|
+
value = Calculator.calculate(expression)
|
|
342
|
+
Tool::Result.new(content: value, summary: value)
|
|
250
343
|
},
|
|
251
|
-
|
|
344
|
+
# No legs: pure arithmetic over the argument, no I/O of any kind.
|
|
345
|
+
trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
|
|
252
346
|
)
|
|
253
347
|
end
|
|
254
348
|
end
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Pikuri
|
|
4
|
+
class Tool
|
|
5
|
+
# The per-call environment handed to an +execute+ Proc alongside its
|
|
6
|
+
# validated arguments — everything a tool might need to know about *this
|
|
7
|
+
# invocation* that the LLM did not supply.
|
|
8
|
+
#
|
|
9
|
+
# Tool.new(
|
|
10
|
+
# name: 'web_search', description: DESCRIPTION, parameters: params,
|
|
11
|
+
# wants_context: true,
|
|
12
|
+
# execute: ->(query:, context:) { cascade.search(query, cancellable: context.cancellable) }
|
|
13
|
+
# )
|
|
14
|
+
#
|
|
15
|
+
# A tool opts in with +wants_context: true+ and takes a +context:+ keyword;
|
|
16
|
+
# both halves are required, so getting one without the other is an
|
|
17
|
+
# +ArgumentError+ on the first call rather than a silent +nil+. Most tools
|
|
18
|
+
# want neither.
|
|
19
|
+
#
|
|
20
|
+
# == Why the arguments are *not* in here
|
|
21
|
+
#
|
|
22
|
+
# The obvious shape is +context.args[:query]+, with one object carrying
|
|
23
|
+
# everything. It loses to a plain fact about {Parameters#validate}: it
|
|
24
|
+
# returns only the keys the model actually sent and applies no defaults, so
|
|
25
|
+
# tools declare theirs in the +execute+ signature (+web_search+'s
|
|
26
|
+
# +max_results: 10+). Fold the arguments in here and every one of those
|
|
27
|
+
# defaults has to be re-expressed. Arguments therefore stay kwargs, and this
|
|
28
|
+
# object carries only what has no other home.
|
|
29
|
+
#
|
|
30
|
+
# Growing it is the point: a new field is added here and read by the tools
|
|
31
|
+
# that care, with no signature change anywhere else.
|
|
32
|
+
ExecuteContext = Data.define(:cancellable) do
|
|
33
|
+
# The context a {Tool#run} with no caller-supplied one uses: cancellation
|
|
34
|
+
# that never trips. Frozen like every +Data+, so it is safe to share.
|
|
35
|
+
#
|
|
36
|
+
# @return [ExecuteContext]
|
|
37
|
+
def self.default
|
|
38
|
+
@default ||= new(cancellable: Pikuri::Agent::Control::Cancellable::NEVER)
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
end
|
|
@@ -40,6 +40,9 @@ module Pikuri
|
|
|
40
40
|
@required = []
|
|
41
41
|
end
|
|
42
42
|
|
|
43
|
+
# @return [Parameters]
|
|
44
|
+
EMPTY = new.freeze
|
|
45
|
+
|
|
43
46
|
# Freeze the builder along with its internal collections, so post-build
|
|
44
47
|
# mutation attempts raise +FrozenError+ instead of silently succeeding.
|
|
45
48
|
#
|
|
@@ -68,22 +71,13 @@ module Pikuri
|
|
|
68
71
|
add(name, 'string', description, required: false)
|
|
69
72
|
end
|
|
70
73
|
|
|
71
|
-
# Add a required +array+-of-+string+ property
|
|
72
|
-
#
|
|
73
|
-
#
|
|
74
|
-
#
|
|
75
|
-
#
|
|
76
|
-
#
|
|
77
|
-
#
|
|
78
|
-
# mirrors the scalar fields' one documented leniency, in
|
|
79
|
-
# reverse: Integers and finite Floats are converted to their
|
|
80
|
-
# +to_s+ form (a model emitting +["Fix issue 12", 42]+ meant a
|
|
81
|
-
# string list — the conversion is unambiguous), while booleans,
|
|
82
|
-
# +nil+, and nested structures are rejected — those signal a
|
|
83
|
-
# genuinely wrong call shape, not a representational quirk.
|
|
84
|
-
# An empty array is type-valid; rejecting it (if the tool needs
|
|
85
|
-
# at least one element) is the tool's job, with a tool-specific
|
|
86
|
-
# error message.
|
|
74
|
+
# Add a required +array+-of-+string+ property (+{type: 'array', items:
|
|
75
|
+
# {type: 'string'}}+). The value must arrive as a native JSON Array — no
|
|
76
|
+
# JSON-in-a-string fallback. Element coercion mirrors the scalars in
|
|
77
|
+
# reverse: Integers and finite Floats become their +to_s+ (a model
|
|
78
|
+
# emitting +["Fix issue 12", 42]+ meant a string list), while booleans,
|
|
79
|
+
# +nil+, and nested structures are rejected. An empty array is type-valid
|
|
80
|
+
# — rejecting it is the tool's job.
|
|
87
81
|
#
|
|
88
82
|
# @param name [Symbol] property name
|
|
89
83
|
# @param description [String] human-readable description shown to the LLM
|
|
@@ -198,24 +192,32 @@ module Pikuri
|
|
|
198
192
|
# Schema in OpenAI JSON-Schema shape.
|
|
199
193
|
#
|
|
200
194
|
# @return [Hash] +{type: 'object', properties: {...}, required: [...]}+
|
|
201
|
-
def
|
|
195
|
+
def to_openai
|
|
202
196
|
{ type: 'object', properties: @properties, required: @required }
|
|
203
197
|
end
|
|
204
198
|
|
|
205
|
-
#
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
#
|
|
211
|
-
#
|
|
212
|
-
#
|
|
199
|
+
# @return [Array<Symbol>] every declared property, in declaration order.
|
|
200
|
+
def names
|
|
201
|
+
@properties.keys
|
|
202
|
+
end
|
|
203
|
+
|
|
204
|
+
# @return [Array<String>] the required properties, in declaration order —
|
|
205
|
+
# so +required.first+ is the argument a tool was declared around, which
|
|
206
|
+
# is what {Pikuri::Tool#describe_call} shows.
|
|
207
|
+
attr_reader :required
|
|
208
|
+
|
|
209
|
+
# Validate a tool-call argument hash against the schema. Returns a
|
|
210
|
+
# symbol-keyed hash safe to splat as kwargs into a tool's +execute+;
|
|
211
|
+
# raises {ValidationError} with an LLM-actionable message listing every
|
|
212
|
+
# missing/unknown/mistyped field and reprinting the schema. Strict:
|
|
213
|
+
# unknown keys rejected (with DidYouMean suggestions), wrong types
|
|
214
|
+
# rejected, all issues collected so the LLM fixes them in one round trip.
|
|
213
215
|
#
|
|
214
|
-
# @param args [Hash] arguments
|
|
215
|
-
#
|
|
216
|
+
# @param args [Hash] arguments decoded from the tool-call JSON; keys may
|
|
217
|
+
# be Strings or Symbols
|
|
216
218
|
# @return [Hash{Symbol=>Object}] validated, symbol-keyed arguments
|
|
217
|
-
# @raise [ValidationError] if +args+
|
|
218
|
-
#
|
|
219
|
+
# @raise [ValidationError] if +args+ isn't a Hash, has unknown keys, omits
|
|
220
|
+
# a required key, or has a wrong-typed value
|
|
219
221
|
def validate(args)
|
|
220
222
|
raise ValidationError, "Arguments must be an object, got #{args.class}." unless args.is_a?(Hash)
|
|
221
223
|
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Pikuri
|
|
4
|
+
class Tool
|
|
5
|
+
# What every {Pikuri::Tool} returns: the observation the model reads, plus
|
|
6
|
+
# the one-line status a chrome renders in its place.
|
|
7
|
+
#
|
|
8
|
+
# hits = cascade.search(query, max_results: max_results)
|
|
9
|
+
# Tool::Result.new(content: render_markdown(hits),
|
|
10
|
+
# summary: "Returned #{hits.size} search results")
|
|
11
|
+
#
|
|
12
|
+
# # → WebSearch(rails 8 credentials)
|
|
13
|
+
# # Returned 23 search results
|
|
14
|
+
#
|
|
15
|
+
# A recoverable failure is a {.error} — the +"Error: ..."+ observation the
|
|
16
|
+
# LLM reacts to, with the message as its own display line:
|
|
17
|
+
#
|
|
18
|
+
# return Tool::Result.error("offset must be >= 1, got #{offset}") if offset < 1
|
|
19
|
+
#
|
|
20
|
+
# == Text or an attachment, and the one rule for choosing
|
|
21
|
+
#
|
|
22
|
+
# +content+ is always the text the model reads. +attachments+ is non-empty
|
|
23
|
+
# only when the observation **is** the attached bytes — the image
|
|
24
|
+
# {Pikuri::Workspace::Read} answers for a PNG, with +content+ a short note:
|
|
25
|
+
#
|
|
26
|
+
# image = Pikuri::Attachment.new(mime: mime, filename: resolved.basename.to_s, bytes: bytes)
|
|
27
|
+
# note = "Read image: #{path} (#{bytes.bytesize} bytes, #{mime})"
|
|
28
|
+
# Tool::Result.new(content: note, attachments: [image], summary: Pikuri::Tool.one_line(note))
|
|
29
|
+
#
|
|
30
|
+
# The test is not "does this tool touch a file" but "is there anything to
|
|
31
|
+
# read here besides the attached bytes"; a PDF is text (extracted, paged,
|
|
32
|
+
# counted), a PNG is not.
|
|
33
|
+
#
|
|
34
|
+
# An attachment's display line is *derived* rather than authored
|
|
35
|
+
# ({Pikuri::Tool.describe_content} answers +"Returned image/png, 27.1 kB"+),
|
|
36
|
+
# because mime and size are the only structure there is — so pass any
|
|
37
|
+
# +summary+ you like and expect the derived one to win. That falls out of
|
|
38
|
+
# how the value crosses into ruby_llm: {Pikuri::Tool#to_ruby_llm_tool}'s
|
|
39
|
+
# wrapper hands an attachment Result over as a +[content, *attachments]+
|
|
40
|
+
# Array, the one shape ruby_llm sends as a multimodal tool message, and its
|
|
41
|
+
# +after_tool_result+ callback then sees that Array, not this Result. Text
|
|
42
|
+
# takes the other branch: ruby_llm receives this +Result+, stores {#to_s},
|
|
43
|
+
# and the listeners get {#summary} verbatim.
|
|
44
|
+
#
|
|
45
|
+
# == The two rules a summary obeys
|
|
46
|
+
#
|
|
47
|
+
# **Structural, never excerpted** — counts, sizes, exit codes; never the
|
|
48
|
+
# first line of the page that was fetched. The user reads this line as
|
|
49
|
+
# *status*, and those bytes are attacker-authorable.
|
|
50
|
+
#
|
|
51
|
+
# **Summaries are code** — computed by the tool's programmer from what the
|
|
52
|
+
# tool counted, never from model output and never from a substring of
|
|
53
|
+
# +content+. A narrated +Saved successfully+ over a failed write is exactly
|
|
54
|
+
# what a prompt injection aims for.
|
|
55
|
+
#
|
|
56
|
+
# Immutable.
|
|
57
|
+
Result = Data.define(:content, :summary, :attachments) do
|
|
58
|
+
# The observation for a failure the LLM can act on — a bad argument, an
|
|
59
|
+
# HTTP 4xx, a refused path. Bugs in pikuri's own code keep raising.
|
|
60
|
+
#
|
|
61
|
+
# Tool::Result.error('no such task id: 7').content # => "Error: no such task id: 7"
|
|
62
|
+
#
|
|
63
|
+
# The message doubles as the display line: an error *is* its own status,
|
|
64
|
+
# which is the one place echoing the content is right. Only its **first
|
|
65
|
+
# line** does, though — a {Parameters::ValidationError} reprints the whole
|
|
66
|
+
# schema for the model to fix, and none of that belongs on a status row.
|
|
67
|
+
#
|
|
68
|
+
# @param message [String] what went wrong, without the +"Error: "+ prefix
|
|
69
|
+
# (already prefixed is fine — it is not doubled). May be multi-line; the
|
|
70
|
+
# model gets all of it.
|
|
71
|
+
# @return [Result]
|
|
72
|
+
def self.error(message)
|
|
73
|
+
text = message.to_s
|
|
74
|
+
text = "Error: #{text}" unless text.start_with?('Error:')
|
|
75
|
+
new(content: text, summary: Tool.one_line(text.lines.first))
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
# The observation for one {Pikuri::Extractor::Page} window — what every
|
|
79
|
+
# line-paged reader answers, so they all share the trailer the model
|
|
80
|
+
# learns to page by:
|
|
81
|
+
#
|
|
82
|
+
# page = Pikuri::Extractor.extract_paged(StringIO.new(text), offset: 3, limit: 2)
|
|
83
|
+
# Tool::Result.page(page).content
|
|
84
|
+
# # => 3 gamma
|
|
85
|
+
# # 4 delta
|
|
86
|
+
# #
|
|
87
|
+
# # (Showing lines 3-4 of 9. Use offset=5 to continue.)
|
|
88
|
+
#
|
|
89
|
+
# A +:pdf+ page words itself as one (+"Showing PDF lines"+, +"End of
|
|
90
|
+
# PDF"+), and an empty one answers the scanned-image hint over
|
|
91
|
+
# +empty_note+. An +offset+ past the end is an {.error}.
|
|
92
|
+
#
|
|
93
|
+
# @param page [Pikuri::Extractor::Page] the window to render.
|
|
94
|
+
# @param name [String] what the document is called in the end-of-document
|
|
95
|
+
# trailer and the past-the-end error, e.g. +"file"+, +"attachment"+.
|
|
96
|
+
# @param empty_note [String] the whole observation for an empty document.
|
|
97
|
+
# @return [Result] summary +"Read 214 lines"+ / +"Read 3 PDF lines"+ for a
|
|
98
|
+
# rendered window.
|
|
99
|
+
def self.page(page, name: 'file', empty_note: "(Empty #{name})")
|
|
100
|
+
pdf = page.kind == :pdf
|
|
101
|
+
what = pdf ? 'PDF' : name
|
|
102
|
+
if page.lines.empty?
|
|
103
|
+
if page.total_lines.zero?
|
|
104
|
+
note = pdf ? '(PDF has no extractable text; likely scanned image content)' : empty_note
|
|
105
|
+
return new(content: note, summary: Tool.one_line(note))
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
return error("offset #{page.start_line} is beyond end of #{what} (#{page.total_lines} lines total)")
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
lines = pdf ? 'PDF lines' : 'lines'
|
|
112
|
+
last = page.start_line + page.lines.length - 1
|
|
113
|
+
body = page.lines.each_with_index.map { |line, i| format("%6d\t%s", i + page.start_line, line) }.join("\n")
|
|
114
|
+
trailer =
|
|
115
|
+
if page.byte_capped
|
|
116
|
+
"(Output capped at #{Extractor::PAGE_MAX_BYTES / 1024} KB. Showing #{lines} " \
|
|
117
|
+
"#{page.start_line}-#{last}. Use offset=#{last + 1} to continue.)"
|
|
118
|
+
elsif page.more
|
|
119
|
+
total = page.total_lines ? " of #{page.total_lines}" : ''
|
|
120
|
+
"(Showing #{lines} #{page.start_line}-#{last}#{total}. Use offset=#{last + 1} to continue.)"
|
|
121
|
+
else
|
|
122
|
+
"(End of #{what} - total #{page.total_lines} lines)"
|
|
123
|
+
end
|
|
124
|
+
|
|
125
|
+
new(content: "#{body}\n\n#{trailer}",
|
|
126
|
+
summary: "Read #{Tool.pluralize(page.lines.length, pdf ? 'PDF line' : 'line')}")
|
|
127
|
+
end
|
|
128
|
+
|
|
129
|
+
# @param content [String] the text the model reads; for an attachment
|
|
130
|
+
# observation, the note beside the bytes.
|
|
131
|
+
# @param summary [String] the display line; see the two rules above.
|
|
132
|
+
# @param attachments [Array<Pikuri::Attachment>] the bytes the
|
|
133
|
+
# observation *is*; see +== Text or an attachment+ above.
|
|
134
|
+
# @raise [ArgumentError] if +content+ is not a String, an attachment is
|
|
135
|
+
# not a {Pikuri::Attachment}, or +summary+ is not a single-line
|
|
136
|
+
# String — all programmer errors in tool code, so they raise rather
|
|
137
|
+
# than degrade.
|
|
138
|
+
def initialize(content:, summary:, attachments: [])
|
|
139
|
+
raise ArgumentError, "content must be a String, got #{content.class}" unless content.is_a?(String)
|
|
140
|
+
unless attachments.all?(Pikuri::Attachment)
|
|
141
|
+
raise ArgumentError, "attachments must be Pikuri::Attachments, got #{attachments.map(&:class)}"
|
|
142
|
+
end
|
|
143
|
+
raise ArgumentError, "summary must be a String, got #{summary.class}" unless summary.is_a?(String)
|
|
144
|
+
raise ArgumentError, "summary must be one line, got #{summary.inspect}" if summary.include?("\n")
|
|
145
|
+
|
|
146
|
+
super(content: content, summary: summary, attachments: attachments.dup.freeze)
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
# Whether the observation carries attached bytes — what decides which
|
|
150
|
+
# value crosses into ruby_llm.
|
|
151
|
+
#
|
|
152
|
+
# @return [Boolean]
|
|
153
|
+
def attachment? = !attachments.empty?
|
|
154
|
+
|
|
155
|
+
# @return [Boolean] whether this is a recoverable failure, i.e. an
|
|
156
|
+
# observation the LLM should try to correct rather than build on.
|
|
157
|
+
def error? = content.start_with?('Error:')
|
|
158
|
+
|
|
159
|
+
# @return [String] {#content} — what ruby_llm stores for a text tool
|
|
160
|
+
# message.
|
|
161
|
+
def to_s = content
|
|
162
|
+
end
|
|
163
|
+
end
|
|
164
|
+
end
|