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
@@ -2,38 +2,70 @@
2
2
 
3
3
  module Pikuri
4
4
  class Tool
5
- # Evaluates a basic arithmetic expression with Python operator
6
- # syntax and semantics, via the hand-rolled recursive-descent
7
- # {Parser} below.
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
- # Why hand-rolled rather than a gem: the previous backend, dentaku,
10
- # pulled in concurrent-ruby (~16k lines of Ruby — the single
11
- # heaviest audit item in pikuri's whole dependency closure) plus
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
- # unary minus, parentheses, and integer / decimal / e-notation
20
- # literals. No variables, functions, or booleans — those would mean
21
- # teaching the model a dialect, which we specifically want to avoid
22
- # for this tool.
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 hand back to
25
- # the model as an +"Error: ..."+ observation rather than crash
26
- # the agent loop: parse failures, division by zero, complex or
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
- # Evaluate +expression+ and return the result formatted as a
32
- # String. Parse and arithmetic failures (division by zero,
33
- # overflow to infinity, complex results) are caught and returned
34
- # as +"Error: ..."+ strings so the model can read the failure as
35
- # the next observation and self-correct rather than crashing the
36
- # agent loop.
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 produced by division — +/+ is Python-3-style
52
- # true division) pass through exact. Floats are rounded to 3
53
- # places so the model sees a short readable number, and
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+ → +unary+ recursion on the right operand is what
74
- # makes +**+ right-associative (+2**3**2+ is 512) and lets a sign
75
- # follow it (+2**-3+); +unary+ sitting *above* +power+ on the
76
- # left is what makes +-2**2+ evaluate to -4 — both exactly as
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
- # true (float) division, +//+ floors, +2**-1+ is the Float 0.5
81
- # (Ruby would return a Rational), and a negative base under a
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. +**+ / +//+ listed before their
85
- # single-character prefixes so the two-character operators win;
86
- # number literals cover +42+, +4.2+, +5.+, +.5+, and e-notation
87
- # on any of them. +\G+ anchors each match at the scan position
88
- # so nothing between tokens goes unnoticed.
89
- TOKEN_RE = %r{\G\s*(\*\*|//|\d+(?:\.\d*)?(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?|[-+*/%()])}
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
- unless token&.match?(/\A[.\d]/)
163
- raise Error, token ? "unexpected #{token.inspect}" : 'unexpected end of expression'
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
- # (kept exact in Ruby's arbitrary-precision Integer division
195
- # when both operands are Integers — Ruby's +Integer#/+ already
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-compatibility shims over Ruby's +**+: an Integer
210
- # raised to a negative Integer yields a Float (Ruby would
211
- # return a Rational), and a Complex result — negative base
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
- # Accepts Python expression syntax (+, -, *, /, //, %, ** for
231
- # exponentiation, unary minus, parentheses, decimals) so the model
232
- # can emit the syntax it already knows.
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 to evaluate, e.g. ' \
249
- '"155 / (58 * 1000.0 / 3600)" or "2**10".'
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
- execute: ->(expression:) { Calculator.calculate(expression) }
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 — JSON-Schema
72
- # +{type: 'array', items: {type: 'string'}}+. The LLM sends a
73
- # native JSON array in the tool-call arguments (the shape its
74
- # training data overwhelmingly uses for list-valued parameters),
75
- # so there is no in-band encoding for it to get wrong.
76
- # The value must arrive as an Array — no
77
- # JSON-encoded-array-in-a-string fallback. Element coercion
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 to_h
195
+ def to_openai
202
196
  { type: 'object', properties: @properties, required: @required }
203
197
  end
204
198
 
205
- # Validate a tool-call argument hash against the declared schema. Returns
206
- # a symbol-keyed hash safe to splat as kwargs into a tool's +execute+
207
- # Proc; raises {ValidationError} with an LLM-actionable message listing
208
- # every missing/unknown/mistyped field and reprinting the schema.
209
- #
210
- # Strict: unknown keys are rejected (with DidYouMean suggestions), wrong
211
- # types are rejected. All issues are collected and reported together so
212
- # the LLM can fix them in one round trip.
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 as decoded from the tool-call JSON; keys
215
- # may be Strings or Symbols
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+ is not a Hash, contains unknown
218
- # keys, omits a required key, or has a value of the wrong type
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