pikuri-core 0.1.0 → 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 +16 -29
- data/lib/pikuri/agent/chat_transport.rb +114 -33
- data/lib/pikuri/agent/configurator.rb +191 -110
- data/lib/pikuri/agent/control/cancellable.rb +25 -16
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +87 -120
- data/lib/pikuri/agent/control.rb +9 -11
- data/lib/pikuri/agent/event.rb +73 -61
- data/lib/pikuri/agent/extension.rb +45 -81
- data/lib/pikuri/agent/history.rb +91 -497
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +115 -108
- data/lib/pikuri/agent/listener/token_log.rb +21 -55
- data/lib/pikuri/agent/listener.rb +4 -4
- data/lib/pikuri/agent/listener_list.rb +19 -13
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +624 -448
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/extractor/passthrough.rb +5 -2
- data/lib/pikuri/extractor.rb +43 -12
- data/lib/pikuri/file_type.rb +4 -4
- data/lib/pikuri/finalizers.rb +2 -2
- data/lib/pikuri/paths.rb +1 -1
- data/lib/pikuri/sanitizer.rb +4 -3
- data/lib/pikuri/subprocess.rb +17 -5
- data/lib/pikuri/testing.rb +122 -49
- data/lib/pikuri/tool/calculator.rb +134 -30
- data/lib/pikuri/tool/execute_context.rb +2 -2
- data/lib/pikuri/tool/parameters.rb +10 -0
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +52 -21
- data/lib/pikuri/tool.rb +298 -24
- data/lib/pikuri/trifecta/report.rb +28 -30
- data/lib/pikuri/trifecta.rb +1 -2
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +5 -11
- metadata +16 -73
- data/lib/pikuri/agent/context_window_detector.rb +0 -181
- data/lib/pikuri/agent/control/step_limit.rb +0 -95
- data/lib/pikuri/agent/extension_context.rb +0 -120
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
- data/lib/pikuri/agent/synthesizer.rb +0 -129
- data/lib/pikuri/extractor/html.rb +0 -256
- data/lib/pikuri/ruby_llm_patches.rb +0 -106
- data/lib/pikuri/tool/fetch.rb +0 -146
- data/lib/pikuri/tool/scraper.rb +0 -144
- data/lib/pikuri/tool/search/brave.rb +0 -170
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
- data/lib/pikuri/tool/search/engines.rb +0 -319
- data/lib/pikuri/tool/search/exa.rb +0 -195
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
- data/lib/pikuri/tool/search/result.rb +0 -24
- data/lib/pikuri/tool/web_scrape.rb +0 -105
- data/lib/pikuri/tool/web_search.rb +0 -133
- data/lib/pikuri/url_cache.rb +0 -96
|
@@ -3,27 +3,69 @@
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
class Tool
|
|
5
5
|
# Evaluates a basic arithmetic expression with Python operator syntax and
|
|
6
|
-
# semantics, via the hand-rolled recursive-descent {Parser} below.
|
|
6
|
+
# semantics, via the hand-rolled recursive-descent {Parser} below. A
|
|
7
|
+
# great-circle distance, the call that motivated {FUNCTIONS}:
|
|
8
|
+
#
|
|
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"
|
|
12
|
+
#
|
|
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+.
|
|
7
19
|
#
|
|
8
20
|
# Hand-rolled rather than a gem: the previous backend (dentaku) pulled in
|
|
9
21
|
# concurrent-ruby (~16k lines — pikuri's single heaviest audit item) plus
|
|
10
|
-
# bigdecimal and tsort just for four-function arithmetic. The
|
|
11
|
-
#
|
|
22
|
+
# bigdecimal and tsort just for four-function arithmetic. The parser here
|
|
23
|
+
# implements Python's grammar directly, which also retires the old
|
|
12
24
|
# +**+→+^+ preprocessing (the model's native syntax is now the grammar).
|
|
13
|
-
#
|
|
14
|
-
# Scope is intentionally narrow: operators (+, -, *, /, //, %, **), unary
|
|
15
|
-
# minus, parentheses, and integer/decimal/e-notation literals. No variables,
|
|
16
|
-
# functions, or booleans — those would teach the model a dialect.
|
|
17
25
|
module Calculator
|
|
18
26
|
# Raised internally for anything {.calculate} should return as an
|
|
19
|
-
# +"Error: ..."+ observation rather than crash the loop
|
|
20
|
-
#
|
|
21
|
-
# token/operands.
|
|
27
|
+
# +"Error: ..."+ observation rather than crash the loop. Names the
|
|
28
|
+
# offending token, operands or call.
|
|
22
29
|
class Error < StandardError; end
|
|
23
30
|
|
|
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
|
+
|
|
24
65
|
# Evaluate +expression+ and return the result as a String. Parse and
|
|
25
66
|
# arithmetic failures (division by zero, overflow to infinity, complex
|
|
26
|
-
# results) come back as +"Error: ..."+ so
|
|
67
|
+
# results, a function outside its domain) come back as +"Error: ..."+ so
|
|
68
|
+
# the model self-corrects.
|
|
27
69
|
#
|
|
28
70
|
# @param expression [String] Python-syntax arithmetic expression
|
|
29
71
|
# @return [String] numeric result, or +"Error: ..."+ on failure
|
|
@@ -55,7 +97,8 @@ module Pikuri
|
|
|
55
97
|
# multiplicative := unary (('*' | '/' | '//' | '%') unary)*
|
|
56
98
|
# unary := ('+' | '-') unary | power
|
|
57
99
|
# power := atom ('**' unary)?
|
|
58
|
-
# atom := NUMBER | '(' additive ')'
|
|
100
|
+
# atom := NUMBER | NAME '(' additive (',' additive)* ')'
|
|
101
|
+
# | NAME | '(' additive ')'
|
|
59
102
|
#
|
|
60
103
|
# The +power+→+unary+ recursion on the right operand makes +**+
|
|
61
104
|
# right-associative (+2**3**2+ is 512) and lets a sign follow it
|
|
@@ -66,11 +109,19 @@ module Pikuri
|
|
|
66
109
|
# division, +//+ floors, +2**-1+ is Float 0.5 (not a Rational), and a
|
|
67
110
|
# negative base under a fractional exponent is rejected (not a Complex).
|
|
68
111
|
class Parser
|
|
69
|
-
# One number or operator. +**+/+//+ listed before their
|
|
70
|
-
# prefixes so the two-char operators win; number literals
|
|
71
|
-
# +4.2+, +5.+, +.5+, and e-notation
|
|
72
|
-
#
|
|
73
|
-
|
|
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(', ')}"
|
|
74
125
|
|
|
75
126
|
# @param expression [String] raw expression as the model wrote it
|
|
76
127
|
# @raise [Error] when +expression+ contains a character no token matches
|
|
@@ -142,13 +193,16 @@ module Pikuri
|
|
|
142
193
|
def atom
|
|
143
194
|
return parenthesized if accept('(')
|
|
144
195
|
|
|
145
|
-
token = peek
|
|
146
|
-
|
|
147
|
-
|
|
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}"
|
|
148
205
|
end
|
|
149
|
-
|
|
150
|
-
@pos += 1
|
|
151
|
-
token.match?(/[.eE]/) ? token.to_f : token.to_i
|
|
152
206
|
end
|
|
153
207
|
|
|
154
208
|
def parenthesized
|
|
@@ -158,6 +212,42 @@ module Pikuri
|
|
|
158
212
|
value
|
|
159
213
|
end
|
|
160
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
|
+
|
|
161
251
|
# @return [String, nil] the next token without consuming it
|
|
162
252
|
def peek
|
|
163
253
|
@tokens[@pos]
|
|
@@ -209,12 +299,13 @@ module Pikuri
|
|
|
209
299
|
|
|
210
300
|
# Arithmetic-evaluation tool backed by {Tool::Calculator.calculate}. Accepts
|
|
211
301
|
# Python expression syntax (+, -, *, /, //, %, **, unary minus, parentheses,
|
|
212
|
-
# decimals)
|
|
302
|
+
# decimals) plus {Tool::Calculator::FUNCTIONS} / {Tool::Calculator::CONSTANTS},
|
|
303
|
+
# so the model emits syntax it already knows.
|
|
213
304
|
#
|
|
214
|
-
# Stays wired even
|
|
215
|
-
# float arithmetic there, since a shell's own +$((…))+ is
|
|
216
|
-
# every interpreter that isn't must stay off the passive
|
|
217
|
-
# +
|
|
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+.
|
|
218
309
|
#
|
|
219
310
|
# Sharing: +P_stateless+ — arithmetic over the argument, no I/O, no state.
|
|
220
311
|
# Hand this one constant to every agent in the VM.
|
|
@@ -234,9 +325,22 @@ module Pikuri
|
|
|
234
325
|
'Arithmetic expression in Python syntax: + - * ' \
|
|
235
326
|
'/ (true division), // (floor division), % (modulo), ' \
|
|
236
327
|
'** (exponentiation), unary minus, parentheses, ' \
|
|
237
|
-
'decimals.
|
|
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)
|
|
238
343
|
},
|
|
239
|
-
execute: ->(expression:) { Calculator.calculate(expression) },
|
|
240
344
|
# No legs: pure arithmetic over the argument, no I/O of any kind.
|
|
241
345
|
trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
|
|
242
346
|
)
|
|
@@ -22,8 +22,8 @@ module Pikuri
|
|
|
22
22
|
# The obvious shape is +context.args[:query]+, with one object carrying
|
|
23
23
|
# everything. It loses to a plain fact about {Parameters#validate}: it
|
|
24
24
|
# returns only the keys the model actually sent and applies no defaults, so
|
|
25
|
-
#
|
|
26
|
-
#
|
|
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
27
|
# defaults has to be re-expressed. Arguments therefore stay kwargs, and this
|
|
28
28
|
# object carries only what has no other home.
|
|
29
29
|
#
|
|
@@ -196,6 +196,16 @@ module Pikuri
|
|
|
196
196
|
{ type: 'object', properties: @properties, required: @required }
|
|
197
197
|
end
|
|
198
198
|
|
|
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
|
+
|
|
199
209
|
# Validate a tool-call argument hash against the schema. Returns a
|
|
200
210
|
# symbol-keyed hash safe to splat as kwargs into a tool's +execute+;
|
|
201
211
|
# raises {ValidationError} with an LLM-actionable message listing every
|
|
@@ -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
|
|
@@ -30,6 +30,13 @@ module Pikuri
|
|
|
30
30
|
# +:no_egress+ at the bottom and the constructor keeps them coherent, so the
|
|
31
31
|
# leg is present on both or on neither ({#egress?} is the canonical read).
|
|
32
32
|
#
|
|
33
|
+
# Unioned, the two axes are each a +max+, which can describe a tool nobody
|
|
34
|
+
# wired: that vouched query beside that reviewed send max out to unreviewed
|
|
35
|
+
# *and* attacker-reachable. Egress is a sink, so bytes leave through one tool
|
|
36
|
+
# and only that tool's own pair decides whether an unreviewed leak reaches a
|
|
37
|
+
# reader. {#egress_open} carries that per-source fact through the union;
|
|
38
|
+
# with the two maxes it pins down exactly which egress shapes a node holds.
|
|
39
|
+
#
|
|
33
40
|
# Immutable.
|
|
34
41
|
#
|
|
35
42
|
# @!attribute [r] private
|
|
@@ -58,7 +65,15 @@ module Pikuri
|
|
|
58
65
|
# choose the destination, that destination does not republish, and the
|
|
59
66
|
# request is not attacker-readable in flight or at rest. Unverifiable by
|
|
60
67
|
# the framework: like +private+, it is a declaration it inherits.
|
|
61
|
-
|
|
68
|
+
# @!attribute [r] egress_open
|
|
69
|
+
# Answers: does one single source send unreviewed bytes to a destination
|
|
70
|
+
# the attacker can reach? The full-strength egress the loud verdict needs.
|
|
71
|
+
#
|
|
72
|
+
# @return [Boolean] derived for a declaration; after a {#|} it can be
|
|
73
|
+
# +false+ while the two axes read +:unreviewed+ / +:attacker_reachable+,
|
|
74
|
+
# because different tools hold the two.
|
|
75
|
+
class TrifectaLegs < Data.define(:private, :untrusted, :egress_payload_review, :egress_destination,
|
|
76
|
+
:egress_open)
|
|
62
77
|
# Danger order, least to most: +max+ is union at a node, +min+ is the cap
|
|
63
78
|
# through a delegation channel.
|
|
64
79
|
#
|
|
@@ -77,11 +92,14 @@ module Pikuri
|
|
|
77
92
|
# @param egress_destination [Symbol, nil] one of {EGRESS_DESTINATION_ORDER};
|
|
78
93
|
# omit to derive — +:no_egress+ without a leg, else the pessimistic
|
|
79
94
|
# +:attacker_reachable+, so silence never buys the softer grade.
|
|
80
|
-
# @
|
|
81
|
-
#
|
|
82
|
-
#
|
|
83
|
-
#
|
|
84
|
-
|
|
95
|
+
# @param egress_open [Boolean, nil] omit to derive from the two axes; only
|
|
96
|
+
# {#|} and +with+ pass it.
|
|
97
|
+
# @raise [ArgumentError] on a level outside its lattice, on the two egress
|
|
98
|
+
# axes disagreeing about whether the leg exists at all — a typo'd level
|
|
99
|
+
# would otherwise read as a missing leg, the one failure mode this
|
|
100
|
+
# detector exists to refuse — or on +egress_open+ claimed where the axes
|
|
101
|
+
# say no source could be.
|
|
102
|
+
def initialize(private:, untrusted:, egress_payload_review:, egress_destination: nil, egress_open: nil)
|
|
85
103
|
egress_destination ||= egress_payload_review == :no_egress ? :no_egress : :attacker_reachable
|
|
86
104
|
check!(untrusted, UNTRUSTED_ORDER, 'untrusted')
|
|
87
105
|
check!(egress_payload_review, EGRESS_REVIEW_ORDER, 'egress review')
|
|
@@ -90,29 +108,35 @@ module Pikuri
|
|
|
90
108
|
raise ArgumentError, 'egress axes disagree on whether the leg exists: ' \
|
|
91
109
|
"#{egress_payload_review.inspect} / #{egress_destination.inspect}"
|
|
92
110
|
end
|
|
111
|
+
could_be_open = egress_payload_review == :unreviewed && egress_destination == :attacker_reachable
|
|
112
|
+
egress_open = could_be_open if egress_open.nil?
|
|
113
|
+
raise ArgumentError, 'egress_open needs an unreviewed, attacker-reachable leg' if egress_open && !could_be_open
|
|
93
114
|
|
|
94
115
|
super(private: private, untrusted: untrusted, egress_payload_review: egress_payload_review,
|
|
95
|
-
egress_destination: egress_destination)
|
|
116
|
+
egress_destination: egress_destination, egress_open: egress_open)
|
|
96
117
|
end
|
|
97
118
|
|
|
98
|
-
# Union: the strongest value on each axis wins
|
|
119
|
+
# Union: the strongest value on each axis wins, and the node is open if
|
|
120
|
+
# either side is.
|
|
99
121
|
#
|
|
100
122
|
# read_legs | bash_legs # what an agent holding both ends up with
|
|
101
123
|
#
|
|
124
|
+
# search = new(private: false, untrusted: :hard,
|
|
125
|
+
# egress_payload_review: :unreviewed, egress_destination: :tool_vouched)
|
|
126
|
+
# compose = new(private: false, untrusted: :none, egress_payload_review: :human_reviewed)
|
|
127
|
+
# (search | compose).egress_open # => false: neither tool leaks unreviewed to a reader
|
|
128
|
+
#
|
|
102
129
|
# @param other [TrifectaLegs]
|
|
103
130
|
# @return [TrifectaLegs]
|
|
104
131
|
def |(other)
|
|
105
|
-
# Per-axis, so web_search (unreviewed, vouched) beside a compose tool
|
|
106
|
-
# (reviewed, attacker-reachable) scores a cell neither occupies. Pairing
|
|
107
|
-
# them up instead would be data flow, which this detector refuses to
|
|
108
|
-
# model; over-warning is the declared bias.
|
|
109
132
|
TrifectaLegs.new(
|
|
110
133
|
private: private || other.private,
|
|
111
134
|
untrusted: [untrusted, other.untrusted].max_by { UNTRUSTED_ORDER.index(_1) },
|
|
112
135
|
egress_payload_review: [egress_payload_review, other.egress_payload_review]
|
|
113
136
|
.max_by { EGRESS_REVIEW_ORDER.index(_1) },
|
|
114
137
|
egress_destination: [egress_destination, other.egress_destination]
|
|
115
|
-
.max_by { EGRESS_DESTINATION_ORDER.index(_1) }
|
|
138
|
+
.max_by { EGRESS_DESTINATION_ORDER.index(_1) },
|
|
139
|
+
egress_open: egress_open || other.egress_open
|
|
116
140
|
)
|
|
117
141
|
end
|
|
118
142
|
|
|
@@ -150,7 +174,8 @@ module Pikuri
|
|
|
150
174
|
# precondition and this method is the mechanical +min+.
|
|
151
175
|
#
|
|
152
176
|
# {#egress_destination} is deliberately untouched: a gate bounds *what*
|
|
153
|
-
# leaves and *who saw it*, never who can read it back.
|
|
177
|
+
# leaves and *who saw it*, never who can read it back. {#egress_open}
|
|
178
|
+
# closes below +:unreviewed+, since every source is then reviewed.
|
|
154
179
|
#
|
|
155
180
|
# @param channel_level [Symbol] one of {EGRESS_REVIEW_ORDER}
|
|
156
181
|
# @return [TrifectaLegs] with the leg gone entirely when the channel
|
|
@@ -159,9 +184,10 @@ module Pikuri
|
|
|
159
184
|
def cap_payload_review(channel_level)
|
|
160
185
|
check!(channel_level, EGRESS_REVIEW_ORDER, 'egress review')
|
|
161
186
|
capped = [egress_payload_review, channel_level].min_by { EGRESS_REVIEW_ORDER.index(_1) }
|
|
162
|
-
return with(egress_payload_review:
|
|
187
|
+
return with(egress_payload_review: :no_egress, egress_destination: :no_egress, egress_open: false) if
|
|
188
|
+
capped == :no_egress
|
|
163
189
|
|
|
164
|
-
with(egress_payload_review:
|
|
190
|
+
with(egress_payload_review: capped, egress_open: egress_open && capped == :unreviewed)
|
|
165
191
|
end
|
|
166
192
|
|
|
167
193
|
# Symbols naming the legs actually present, in the vocabulary the docs and
|
|
@@ -177,20 +203,25 @@ module Pikuri
|
|
|
177
203
|
tags = []
|
|
178
204
|
tags << :private if private
|
|
179
205
|
tags << :"untrusted_#{untrusted}" unless untrusted == :none
|
|
180
|
-
tags
|
|
206
|
+
tags.concat(egress_tags) if egress?
|
|
181
207
|
tags
|
|
182
208
|
end
|
|
183
209
|
|
|
184
210
|
private
|
|
185
211
|
|
|
186
|
-
# @return [Symbol] +:egress+ at full strength, with +_reviewed+ /
|
|
212
|
+
# @return [Array<Symbol>] +:egress+ at full strength, with +_reviewed+ /
|
|
187
213
|
# +_vouched+ appended per attenuated axis, so the four cells name
|
|
188
|
-
# themselves without a lookup table
|
|
189
|
-
|
|
214
|
+
# themselves without a lookup table; two tags when the axes max out
|
|
215
|
+
# from different tools, since no single tag describes that node
|
|
216
|
+
def egress_tags
|
|
217
|
+
if !egress_open && egress_payload_review == :unreviewed && egress_destination == :attacker_reachable
|
|
218
|
+
return %i[egress_reviewed egress_vouched]
|
|
219
|
+
end
|
|
220
|
+
|
|
190
221
|
parts = ['egress']
|
|
191
222
|
parts << 'reviewed' if egress_payload_review == :human_reviewed
|
|
192
223
|
parts << 'vouched' if egress_destination == :tool_vouched
|
|
193
|
-
parts.join('_').to_sym
|
|
224
|
+
[parts.join('_').to_sym]
|
|
194
225
|
end
|
|
195
226
|
|
|
196
227
|
# @raise [ArgumentError] unless +value+ is a level of the +order+ lattice
|