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
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'stringio'
|
|
4
|
+
|
|
5
|
+
module Pikuri
|
|
6
|
+
# A file shown to the model beside text — the image +read+ answers, a
|
|
7
|
+
# screenshot the user attaches — held as its bytes:
|
|
8
|
+
#
|
|
9
|
+
# png = File.binread(path)
|
|
10
|
+
# Pikuri::Attachment.new(mime: Pikuri::FileType.detect_mime(png), filename: 'shot.png', bytes: png)
|
|
11
|
+
#
|
|
12
|
+
# It is the only attachment type pikuri's API carries ({Tool::Result#attachments},
|
|
13
|
+
# {Agent::History::Message#attachments}); {#to_ruby_llm} builds ruby_llm's own
|
|
14
|
+
# at the wire. Bytes rather than a path is the point: ruby_llm reads a path
|
|
15
|
+
# String at construction, fetches a URL one, and may read a path again at send
|
|
16
|
+
# time, so a file edited in between reaches the model unchecked. An
|
|
17
|
+
# +Attachment+ is what the model saw, and compares by content.
|
|
18
|
+
class Attachment < Data.define(:mime, :filename, :bytes)
|
|
19
|
+
# @return [Integer] the largest image a tool or host attaches: Anthropic's
|
|
20
|
+
# per-image limit, the same order on OpenAI and Gemini. Refuse a bigger
|
|
21
|
+
# one with an error the model can react to, rather than send a payload
|
|
22
|
+
# the provider rejects.
|
|
23
|
+
MAX_IMAGE_BYTES = 5 * 1024 * 1024
|
|
24
|
+
|
|
25
|
+
# Rebuild one from ruby_llm's type — the way back from a live chat.
|
|
26
|
+
#
|
|
27
|
+
# @param attachment [RubyLLM::Attachment] path- or IO-backed; a URL-backed
|
|
28
|
+
# one is fetched, which pikuri never builds.
|
|
29
|
+
# @return [Attachment]
|
|
30
|
+
def self.from_ruby_llm(attachment)
|
|
31
|
+
new(mime: attachment.mime_type, filename: attachment.filename.to_s, bytes: attachment.content)
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
# @param mime [String] e.g. +"image/png"+
|
|
35
|
+
# @param filename [String] the name the model is shown
|
|
36
|
+
# @param bytes [String] the file's contents; re-tagged binary, since the
|
|
37
|
+
# same image arrives as UTF-8 from a source file and as ASCII-8BIT from
|
|
38
|
+
# base64, and two differently-tagged copies of one PNG are not +==+.
|
|
39
|
+
def initialize(mime:, filename:, bytes:)
|
|
40
|
+
super(mime: mime, filename: filename, bytes: bytes.b.freeze)
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
# ruby_llm's attachment over these bytes, for the wire. {#mime} crosses as
|
|
44
|
+
# stated, so ruby_llm detects nothing: the provider is told the type pikuri
|
|
45
|
+
# checked, never one guessed from a sender-chosen {#filename}.
|
|
46
|
+
#
|
|
47
|
+
# @return [RubyLLM::Attachment]
|
|
48
|
+
def to_ruby_llm
|
|
49
|
+
RubyLLM::Attachment.new(StringIO.new(bytes), filename: filename, mime_type: mime)
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
# The line that stands in for this attachment when the model can't take
|
|
53
|
+
# it ({Agent::ChatTransport#modalities}), so the model learns why it sees
|
|
54
|
+
# nothing:
|
|
55
|
+
#
|
|
56
|
+
# png.withheld_note('model m takes no vision input')
|
|
57
|
+
# # => "[shot.png not shown: model m takes no vision input]"
|
|
58
|
+
#
|
|
59
|
+
# @param reason [String]
|
|
60
|
+
# @return [String]
|
|
61
|
+
def withheld_note(reason)
|
|
62
|
+
"[#{filename} not shown: #{reason}]"
|
|
63
|
+
end
|
|
64
|
+
end
|
|
65
|
+
end
|
|
@@ -13,7 +13,10 @@ module Pikuri
|
|
|
13
13
|
# (+application/octet-stream+ gets the {Unsupported} refusal).
|
|
14
14
|
# * Without one (the local-file path, {FileType.detect_mime} → +nil+): claim
|
|
15
15
|
# anything passing {FileType.binary?} on the sample; opaque binaries stay
|
|
16
|
-
# unclaimed and surface as {Unsupported}.
|
|
16
|
+
# unclaimed and surface as {Unsupported}. A format {FileType.detect_mime}
|
|
17
|
+
# recognises is never text, however ASCII its head: a PDF's first 4 KB of
|
|
18
|
+
# dictionaries passes {FileType.binary?}, and would reach the model raw on
|
|
19
|
+
# a host without a PDF extractor.
|
|
17
20
|
module Passthrough
|
|
18
21
|
# @return [Symbol] {Page#kind} tag.
|
|
19
22
|
def self.kind
|
|
@@ -27,7 +30,7 @@ module Pikuri
|
|
|
27
30
|
def self.matches?(sample:, content_type:)
|
|
28
31
|
return content_type.start_with?('text/') unless content_type.nil?
|
|
29
32
|
|
|
30
|
-
!FileType.binary?(sample)
|
|
33
|
+
FileType.detect_mime(sample).nil? && !FileType.binary?(sample)
|
|
31
34
|
end
|
|
32
35
|
|
|
33
36
|
# @param io [IO, StringIO] IO over the text content.
|
data/lib/pikuri/extractor.rb
CHANGED
|
@@ -2,15 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
# The format→text extraction seam: one ordered registry of extractors
|
|
5
|
-
# turning an +IO+ of a recognised format (
|
|
6
|
-
# PDF
|
|
5
|
+
# turning an +IO+ of a recognised format (plain text in core; HTML via
|
|
6
|
+
# pikuri-html, PDF via pikuri-pdf, office formats via pikuri-workshop's
|
|
7
|
+
# pikuri-extractors) into
|
|
7
8
|
# Markdown-flavoured UTF-8, behind two front doors:
|
|
8
9
|
#
|
|
9
10
|
# * {.extract} — the whole document as one String (no windowing).
|
|
10
11
|
# * {.extract_paged} — the same, windowed to a line range with a byte
|
|
11
12
|
# cap, as a {Page} the caller renders.
|
|
12
13
|
#
|
|
13
|
-
#
|
|
14
|
+
# pikuri-web's scraper (dispatching on the HTTP +Content-Type+) and {FileType}
|
|
14
15
|
# (resolving local paths) both route through this registry, so "support a
|
|
15
16
|
# new format" is a registry entry, not a new dispatcher arm.
|
|
16
17
|
#
|
|
@@ -31,17 +32,46 @@ module Pikuri
|
|
|
31
32
|
# plus one *optional* method:
|
|
32
33
|
#
|
|
33
34
|
# * +extract_lines(io)+ → +Enumerator<String>+ — the same content as a
|
|
34
|
-
# lazy stream of +chomp+ed lines
|
|
35
|
+
# lazy stream of +chomp+ed lines, numbered exactly as +extract+'s (see
|
|
36
|
+
# == Lines). {.extract_paged} prefers it and stops
|
|
35
37
|
# the moment the window fills, so the document's tail is never parsed
|
|
36
38
|
# (pikuri-pdf parses pages on access). Must be consumed while +io+ is
|
|
37
39
|
# open; may raise {Error} mid-iteration. Extractors needing the whole
|
|
38
|
-
# document (
|
|
40
|
+
# document (pikuri-web's HTML, any subprocess-based one) omit it, and
|
|
39
41
|
# {.extract_paged} extracts in full then windows.
|
|
40
42
|
#
|
|
41
43
|
# Windowing (offset / limit / byte cap / truncation) is presentation and
|
|
42
44
|
# lives once in {.extract_paged}, never per extractor — +extract_lines+ is
|
|
43
45
|
# line *production*, the only format-specific half of paging.
|
|
44
46
|
#
|
|
47
|
+
# == Lines
|
|
48
|
+
#
|
|
49
|
+
# The one definition of "line N" for everything that pages, cites or
|
|
50
|
+
# indexes extracted text — a reader's +offset:+, a search hit's line range,
|
|
51
|
+
# a host program counting lines itself:
|
|
52
|
+
#
|
|
53
|
+
# "a\r\nb\rc\n\nd\n" # 4 lines: "a", "b\rc", "", "d"
|
|
54
|
+
#
|
|
55
|
+
# * 1-based; a range is inclusive at both ends.
|
|
56
|
+
# * LF is the only terminator: CRLF numbers like LF, a lone CR is *not* a
|
|
57
|
+
# break, a final LF opens no extra line. Line N is the text after the
|
|
58
|
+
# (N-1)th +"\n"+.
|
|
59
|
+
# * Lines of the *extracted* text. For {Passthrough} formats (plain text,
|
|
60
|
+
# Markdown, source) they are the file's own lines; for PDF / office /
|
|
61
|
+
# HTML they number the extractor's output, +"--- Page N ---"+ markers
|
|
62
|
+
# included — reproducible only by running the same extractor.
|
|
63
|
+
#
|
|
64
|
+
# Every reader paging through {.extract_paged} numbers lines this way, so
|
|
65
|
+
# a line number one of them reports (a search hit's +lines a-b+, say) is a
|
|
66
|
+
# valid +offset:+ for any other over the same file, the workspace +read+
|
|
67
|
+
# included.
|
|
68
|
+
#
|
|
69
|
+
# A host counting a file's lines must split on LF alone. +grep -n+, +sed+,
|
|
70
|
+
# +awk+ and Ruby's +each_line+ agree; Python's +str.splitlines()+ and
|
|
71
|
+
# text-mode +open()+ and Java's +BufferedReader.readLine()+ /
|
|
72
|
+
# +Files.readAllLines()+ also break on a lone CR (+splitlines+ on +\v+,
|
|
73
|
+
# +\f+, U+2028 and more too), and every number after one is silently off.
|
|
74
|
+
#
|
|
45
75
|
# == Errors
|
|
46
76
|
#
|
|
47
77
|
# Both modes are failures the caller's LLM can react to, under one
|
|
@@ -87,8 +117,8 @@ module Pikuri
|
|
|
87
117
|
# truncated (with {PAGE_LINE_TRUNCATION_MARKER}), *not* line-numbered
|
|
88
118
|
# (numbering is the caller's presentation). Includes any +"--- Page N
|
|
89
119
|
# ---"+ marker lines, which count toward +limit+/the byte cap.
|
|
90
|
-
# * +start_line+ —
|
|
91
|
-
#
|
|
120
|
+
# * +start_line+ — line number of +lines.first+ (the requested +offset+),
|
|
121
|
+
# per {Extractor}'s == Lines.
|
|
92
122
|
# * +total_lines+ — +Integer+ document line count when known, else +nil+.
|
|
93
123
|
# Known at EOF, when extracted in full (HTML), or on a cheap-to-count
|
|
94
124
|
# stream (text); +nil+ when a lazy stream stopped early (byte cap, or a
|
|
@@ -104,16 +134,17 @@ module Pikuri
|
|
|
104
134
|
Page = Data.define(:lines, :start_line, :total_lines, :more, :byte_capped, :kind)
|
|
105
135
|
|
|
106
136
|
# The extractor registry, consulted in order — first match wins. Core
|
|
107
|
-
# ships
|
|
108
|
-
#
|
|
109
|
-
#
|
|
137
|
+
# ships only the terminal {Passthrough} plain-text arm. A gem picks its
|
|
138
|
+
# insertion point by claim strength: a magic-byte sniff that never
|
|
139
|
+
# misfires on text goes at the *front* to beat a content-type claimer
|
|
110
140
|
# under a lying header (+registry.unshift(X)+ — pikuri-pdf); a
|
|
111
141
|
# content-type/weaker claimer inserts before the terminal entry
|
|
112
|
-
# (+registry.insert(-2, X)+ — pikuri-
|
|
142
|
+
# (+registry.insert(-2, X)+ — pikuri-web's HTML, pikuri-workshop's office
|
|
143
|
+
# extractors).
|
|
113
144
|
#
|
|
114
145
|
# @return [Array<#matches?>] mutable, deliberately — the plug-in seam.
|
|
115
146
|
def registry
|
|
116
|
-
@registry ||= [
|
|
147
|
+
@registry ||= [Passthrough]
|
|
117
148
|
end
|
|
118
149
|
|
|
119
150
|
# Extract the whole document behind +io+ as one Markdown-flavoured UTF-8
|
data/lib/pikuri/file_type.rb
CHANGED
|
@@ -170,9 +170,8 @@ module Pikuri
|
|
|
170
170
|
end
|
|
171
171
|
private_class_method :guard_extractable
|
|
172
172
|
|
|
173
|
-
# Coerce +input+ into
|
|
174
|
-
#
|
|
175
|
-
# read. Empty files → empty String (not-binary, +nil+ mime).
|
|
173
|
+
# Coerce +input+ into up to {SAMPLE_BYTES} binary bytes for the sniffs: a
|
|
174
|
+
# +String+ is sliced, a +Pathname+ opened binary and read. Empty files → empty String (not-binary, +nil+ mime).
|
|
176
175
|
#
|
|
177
176
|
# @param input [String, Pathname]
|
|
178
177
|
# @return [String] raw bytes.
|
|
@@ -181,7 +180,8 @@ module Pikuri
|
|
|
181
180
|
def sample_of(input)
|
|
182
181
|
case input
|
|
183
182
|
when String
|
|
184
|
-
|
|
183
|
+
# Binary: a UTF-8 String holding non-ASCII raises against the magic prefixes.
|
|
184
|
+
input.byteslice(0, SAMPLE_BYTES).b
|
|
185
185
|
when Pathname
|
|
186
186
|
input.open('rb') { |io| io.read(SAMPLE_BYTES) || +'' }
|
|
187
187
|
else
|
data/lib/pikuri/finalizers.rb
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
module Pikuri
|
|
4
4
|
# Process-global teardown registry: one +at_exit+ for the whole process,
|
|
5
5
|
# with everything owning a resource that needs orderly shutdown (agents,
|
|
6
|
-
#
|
|
6
|
+
# a container a gem supervises, background workers) registering here instead of
|
|
7
7
|
# growing its own +at_exit+. {Agent#on_close} promoted per-agent → per-process
|
|
8
8
|
# — the same LIFO + per-handler-rescue + idempotent shape.
|
|
9
9
|
#
|
|
@@ -26,7 +26,7 @@ module Pikuri
|
|
|
26
26
|
# == Order: LIFO
|
|
27
27
|
#
|
|
28
28
|
# Last registered, first closed. A registrant depending on an earlier one (a
|
|
29
|
-
# background
|
|
29
|
+
# background indexing daemon writing into a database container) registers later
|
|
30
30
|
# and tears down first — registration order is dependency order.
|
|
31
31
|
#
|
|
32
32
|
# == Errors are contained
|
data/lib/pikuri/paths.rb
CHANGED
|
@@ -22,7 +22,7 @@ module Pikuri
|
|
|
22
22
|
# Pikuri's cache root: +$XDG_CACHE_HOME/pikuri+ or +~/.cache/pikuri+.
|
|
23
23
|
#
|
|
24
24
|
# Shared across ALL pikuri processes and PERSISTENT (survives exit) — the
|
|
25
|
-
# home for state meant to be reused: the URL cache, mem0 / Qdrant
|
|
25
|
+
# home for state meant to be reused: the URL cache, mem0 / Qdrant
|
|
26
26
|
# server data. For scratch private to *this* process that should vanish when
|
|
27
27
|
# it exits, use {.new_temp}; reaching for +cache+ + a fixed subdir is how two
|
|
28
28
|
# concurrent processes end up overwriting each other's files.
|
data/lib/pikuri/sanitizer.rb
CHANGED
|
@@ -19,9 +19,10 @@ module Pikuri
|
|
|
19
19
|
# 1. *Neutralize* — make dangerous bytes visible without changing structure:
|
|
20
20
|
# control bytes → +\xNN+, bidi/zero-width → +\u{NNNN}+, tab → +\t+;
|
|
21
21
|
# newlines preserved. *Faithful, not beautifying* — it never collapses
|
|
22
|
-
# whitespace
|
|
23
|
-
#
|
|
24
|
-
# +html_escape+ on top; the HTML
|
|
22
|
+
# whitespace, and a tab shows as +\t+, never as spaces, because the user
|
|
23
|
+
# must see exactly what they approve (a Makefile recipe whose leading tab
|
|
24
|
+
# is spaces breaks). A web chrome adds +html_escape+ on top; the HTML
|
|
25
|
+
# layer is the caller's.
|
|
25
26
|
# 2. *Warn* — one {Warning} per category detected (kind + offending tokens +
|
|
26
27
|
# plain-English explanation). Presentation is the chrome's.
|
|
27
28
|
#
|
data/lib/pikuri/subprocess.rb
CHANGED
|
@@ -16,8 +16,8 @@ module Pikuri
|
|
|
16
16
|
# All subprocess spawning in +lib/+ goes through {.spawn}/{.run}; direct
|
|
17
17
|
# +Process.spawn+ / +Open3.*+ / +system+ / backticks are bugs.
|
|
18
18
|
# Grep-enforceable: +grep -rnE 'Process\.spawn|Open3\.|\bsystem\(' lib/+
|
|
19
|
-
# should hit only this file
|
|
20
|
-
#
|
|
19
|
+
# should hit only this file. The one exception lives downstream:
|
|
20
|
+
# pikuri-workshop's MCP client, which owns a long-lived stdio pipe.
|
|
21
21
|
#
|
|
22
22
|
# == Timeouts are the caller's job
|
|
23
23
|
#
|
|
@@ -40,6 +40,18 @@ module Pikuri
|
|
|
40
40
|
# SIGTERMs every tracked group at exit. The model opts out with +nohup+ /
|
|
41
41
|
# +setsid+ (both detach from our group).
|
|
42
42
|
#
|
|
43
|
+
# == Daemon children
|
|
44
|
+
#
|
|
45
|
+
# A long-lived child — a relay, a sidecar — is a {.spawn} nobody {#wait}s on:
|
|
46
|
+
#
|
|
47
|
+
# relay = Pikuri::Subprocess.spawn('socat', listen, connect, chdir: '/')
|
|
48
|
+
# Thread.new { relay.io.each_line { |l| LOGGER.warn(l) } } # drain, or it blocks on a full pipe
|
|
49
|
+
# relay.terminate # when its owner closes
|
|
50
|
+
#
|
|
51
|
+
# The shape lives here rather than with its caller because the exit-sweep
|
|
52
|
+
# set is private to this class: a daemon spawned anywhere else escapes the
|
|
53
|
+
# sweep, and opening +register+ would be the wider seam.
|
|
54
|
+
#
|
|
43
55
|
# == State is process-global
|
|
44
56
|
#
|
|
45
57
|
# One +@active+ Set for the process, swept once at exit via
|
|
@@ -70,7 +82,8 @@ module Pikuri
|
|
|
70
82
|
|
|
71
83
|
# Run +argv+ as a one-shot *filter*: feed it +stdin_data+, redirect stdout
|
|
72
84
|
# to +stdout+ (an open +File+), capture stderr through a pipe, block until
|
|
73
|
-
# it exits. Built for
|
|
85
|
+
# it exits. Built for stdin→markdown converters (pikuri-workshop's
|
|
86
|
+
# pikuri-extractors runs them in a container),
|
|
74
87
|
# where {.spawn}'s shape is wrong twice: it closes stdin immediately and
|
|
75
88
|
# merges stderr onto stdout — fatal when stdout *is* the payload.
|
|
76
89
|
#
|
|
@@ -159,8 +172,7 @@ module Pikuri
|
|
|
159
172
|
end
|
|
160
173
|
|
|
161
174
|
# SIGTERM the whole process group without blocking for output — the stop
|
|
162
|
-
# button for a
|
|
163
|
-
# {Pikuri::Memory::Mem0Server}'s socat relay). Best-effort and idempotent;
|
|
175
|
+
# button for a daemon child (see the class doc). Best-effort and idempotent;
|
|
164
176
|
# the group stays in the exit-sweep set until it dies, so a child ignoring
|
|
165
177
|
# SIGTERM is re-signalled by {.cleanup!} at exit.
|
|
166
178
|
#
|
data/lib/pikuri/testing.rb
CHANGED
|
@@ -39,13 +39,22 @@ module Pikuri
|
|
|
39
39
|
# == Limitations
|
|
40
40
|
#
|
|
41
41
|
# A fake transport feeds **one ordered response list**. Propagation to
|
|
42
|
-
# sub-agents
|
|
42
|
+
# sub-agents works (they derive their transport via
|
|
43
43
|
# +parent.transport.with(...)+, and +Data#with+ preserves the adapter), but
|
|
44
44
|
# they *share* that one list — fine for a single linear script, not for
|
|
45
45
|
# targeting a specific sub-agent's replies. Per-sub-agent scripting is a
|
|
46
46
|
# future upgrade (dispatch by model id / distinct fake +api_base+).
|
|
47
|
-
#
|
|
48
|
-
#
|
|
47
|
+
# Only the LLM is faked: a tool's own backend is not, so an agent wiring a
|
|
48
|
+
# tool that spawns a server or reaches the network does so for real in a
|
|
49
|
+
# fake-backed spec too.
|
|
50
|
+
#
|
|
51
|
+
# == Streaming
|
|
52
|
+
#
|
|
53
|
+
# One script drives a plain agent and a +streaming: true+ one alike: each
|
|
54
|
+
# verb queues a {Completion}, rendered only when served — a JSON body to a
|
|
55
|
+
# plain request, SSE chunks to a streamed one (a tool call's arguments in
|
|
56
|
+
# fragments, as a server sends them). {Script#stream} only adds the choice of
|
|
57
|
+
# where the text splits.
|
|
49
58
|
module Testing
|
|
50
59
|
# Build a fake transport from a scripted conversation. Pass a block that
|
|
51
60
|
# calls {Script} verbs in the order the model should "reply"; each verb
|
|
@@ -59,8 +68,10 @@ module Pikuri
|
|
|
59
68
|
#
|
|
60
69
|
# @param model [String] model id the fake reports (any string; the fake
|
|
61
70
|
# server "knows" it)
|
|
62
|
-
# @param context_window [Integer] baked onto the transport
|
|
63
|
-
#
|
|
71
|
+
# @param context_window [Integer, nil] baked onto the transport as its
|
|
72
|
+
# stated cap
|
|
73
|
+
# @param modalities [Hash{Symbol => Boolean}, nil] baked onto the transport
|
|
74
|
+
# as stated, like +context_window+; the default +{}+ refuses nothing
|
|
64
75
|
# @param api_base [String] the transport's base URL. Never dialed (the
|
|
65
76
|
# adapter answers), but a host may key display/config off it — pass the
|
|
66
77
|
# base of the connection this fake impersonates so a UI resolves its name.
|
|
@@ -68,33 +79,51 @@ module Pikuri
|
|
|
68
79
|
# engaged ({Gate#block!}), the adapter parks before serving each response
|
|
69
80
|
# until {Gate#release!} — so a test can observe spinner / queued-injection
|
|
70
81
|
# / Ctrl+C paths through the real turn lifecycle. Default +nil+ (no gating).
|
|
82
|
+
# @param params [Hash{String, Symbol => Object}] extra payload keys this
|
|
83
|
+
# fake connection carries; they reach the request body the scripted
|
|
84
|
+
# adapter is handed
|
|
71
85
|
# @yieldparam script [Script] the conversation builder
|
|
72
86
|
# @return [Agent::ChatTransport] carrying the scripted adapter; pass it as
|
|
73
87
|
# +Agent.new(transport:)+
|
|
74
|
-
def self.fake_transport(model: 'fake-model', context_window: 8192,
|
|
75
|
-
api_base: 'http://fake.invalid/v1', gate: nil)
|
|
88
|
+
def self.fake_transport(model: 'fake-model', context_window: 8192, modalities: {},
|
|
89
|
+
api_base: 'http://fake.invalid/v1', gate: nil, params: {})
|
|
76
90
|
script = Script.new
|
|
77
91
|
yield script if block_given?
|
|
78
92
|
Agent::ChatTransport.new(
|
|
79
93
|
model: model,
|
|
80
94
|
provider: :openai,
|
|
81
95
|
assume_model_exists: true,
|
|
82
|
-
#
|
|
83
|
-
#
|
|
96
|
+
# Never dialed (the adapter answers); it is the transport's identity to
|
|
97
|
+
# a host, and the +api_base+ an +around_request+ hook is handed.
|
|
84
98
|
api_base: api_base,
|
|
85
99
|
api_key: 'not-needed',
|
|
86
100
|
context_window: context_window,
|
|
87
|
-
|
|
101
|
+
modalities: modalities,
|
|
102
|
+
faraday_adapter: build_adapter(script.responses, gate),
|
|
103
|
+
params: params
|
|
88
104
|
)
|
|
89
105
|
end
|
|
90
106
|
|
|
107
|
+
# The {Agent::Configurator} of a throwaway agent, for a spec that drives an
|
|
108
|
+
# extension's +configure+ by hand and reads back what it registered:
|
|
109
|
+
#
|
|
110
|
+
# c = Pikuri::Testing.configurator
|
|
111
|
+
# Pikuri::Workspace::Extension.new(filesystem: fs, confirmer: confirmer).configure(c)
|
|
112
|
+
# c.tools.map(&:name) # => ["read", "write", ...]
|
|
113
|
+
#
|
|
114
|
+
# @return [Agent::Configurator]
|
|
115
|
+
def self.configurator
|
|
116
|
+
captured = nil
|
|
117
|
+
Agent.new(transport: fake_transport, system_prompt: '') { |c| captured = c }
|
|
118
|
+
captured
|
|
119
|
+
end
|
|
120
|
+
|
|
91
121
|
# An anonymous +Faraday::Adapter+ subclass that serves +responses+ in order,
|
|
92
122
|
# one per HTTP request. Closes over the (mutable) list, so the queue drains
|
|
93
123
|
# across the several requests of one conversation regardless of how Faraday
|
|
94
124
|
# reuses adapter instances.
|
|
95
125
|
#
|
|
96
|
-
# @param responses [Array<
|
|
97
|
-
# or +{sse: Array<String>}+ (stream), as {Script} produces
|
|
126
|
+
# @param responses [Array<Completion>] as {Script} queues them
|
|
98
127
|
# @param gate [Gate, nil] awaited before each response when non-nil
|
|
99
128
|
# @return [Class] a +Faraday::Adapter+ subclass
|
|
100
129
|
def self.build_adapter(responses, gate = nil)
|
|
@@ -106,7 +135,7 @@ module Pikuri
|
|
|
106
135
|
define_method(:call) do |env|
|
|
107
136
|
super(env) # base builds env.response; skipping it → "finish for nil"
|
|
108
137
|
gate&.await # park here while the test holds the turn open
|
|
109
|
-
|
|
138
|
+
completion = queue.shift or raise "Pikuri::Testing: no scripted response left for #{env.url}"
|
|
110
139
|
|
|
111
140
|
if env.request.stream_response? # ruby_llm set req.options.on_data
|
|
112
141
|
# v2 on_data routes to the chunk handler only at status 200; set it
|
|
@@ -115,13 +144,13 @@ module Pikuri
|
|
|
115
144
|
env.status = 200
|
|
116
145
|
on_data = env.request.on_data
|
|
117
146
|
size = 0
|
|
118
|
-
|
|
147
|
+
completion.to_sse.each do |chunk|
|
|
119
148
|
size += chunk.bytesize
|
|
120
149
|
on_data.call(chunk, size, env)
|
|
121
150
|
end
|
|
122
151
|
save_response(env, 200, '', { 'Content-Type' => 'text/event-stream' }, nil)
|
|
123
152
|
else
|
|
124
|
-
save_response(env, 200, JSON.generate(
|
|
153
|
+
save_response(env, 200, JSON.generate(completion.to_json_body),
|
|
125
154
|
{ 'Content-Type' => 'application/json' }, nil)
|
|
126
155
|
end
|
|
127
156
|
@app.call(env)
|
|
@@ -129,17 +158,17 @@ module Pikuri
|
|
|
129
158
|
end
|
|
130
159
|
end
|
|
131
160
|
|
|
132
|
-
# Collects the scripted conversation: each verb
|
|
133
|
-
#
|
|
134
|
-
#
|
|
161
|
+
# Collects the scripted conversation: each verb queues one {Completion} on
|
|
162
|
+
# {#responses}, in call order. You don't build these directly —
|
|
163
|
+
# {Testing.fake_transport} yields one to your block.
|
|
135
164
|
#
|
|
136
165
|
# fake_transport do |llm|
|
|
137
166
|
# llm.reply('hi') # plain answer
|
|
138
167
|
# llm.tool_call('calculator', expression: '2+2') # a tool turn
|
|
139
|
-
# llm.stream('The ', 'answer ', 'is ', '4.') #
|
|
168
|
+
# llm.stream('The ', 'answer ', 'is ', '4.') # an answer in chosen deltas
|
|
140
169
|
# end
|
|
141
170
|
class Script
|
|
142
|
-
# @return [Array<
|
|
171
|
+
# @return [Array<Completion>] queued completions in call order
|
|
143
172
|
attr_reader :responses
|
|
144
173
|
|
|
145
174
|
def initialize
|
|
@@ -148,13 +177,12 @@ module Pikuri
|
|
|
148
177
|
end
|
|
149
178
|
|
|
150
179
|
# Queue a plain assistant-text turn (the model's final answer for that
|
|
151
|
-
# step).
|
|
180
|
+
# step). A streaming agent gets it as a single delta.
|
|
152
181
|
#
|
|
153
182
|
# @param text [String] the assistant message content
|
|
154
183
|
# @return [self]
|
|
155
184
|
def reply(text)
|
|
156
|
-
|
|
157
|
-
self
|
|
185
|
+
stream(text)
|
|
158
186
|
end
|
|
159
187
|
|
|
160
188
|
# Queue an assistant turn that calls one tool. The real ruby_llm loop
|
|
@@ -186,20 +214,18 @@ module Pikuri
|
|
|
186
214
|
# the order the model asked for them
|
|
187
215
|
# @return [self]
|
|
188
216
|
def tool_batch(*calls)
|
|
189
|
-
|
|
217
|
+
tool_calls = calls.map do |name, arguments|
|
|
190
218
|
@tool_call_seq += 1
|
|
191
|
-
|
|
192
|
-
|
|
219
|
+
Completion::ToolCall.new(id: "call_#{@tool_call_seq}", name: name,
|
|
220
|
+
arguments: JSON.generate(arguments || {}))
|
|
193
221
|
end
|
|
194
|
-
@responses <<
|
|
222
|
+
@responses << Completion.new(deltas: [], tool_calls: tool_calls)
|
|
195
223
|
self
|
|
196
224
|
end
|
|
197
225
|
|
|
198
|
-
#
|
|
199
|
-
#
|
|
200
|
-
# {Agent::Event::
|
|
201
|
-
# {Agent::Event::Assistant}. Text only — tool-call streaming is not
|
|
202
|
-
# modelled.
|
|
226
|
+
# {#reply} with the text split where you choose: a +streaming: true+
|
|
227
|
+
# agent emits one {Agent::Event::AssistantDelta} per +delta+, then the
|
|
228
|
+
# assembled {Agent::Event::Assistant}. A plain agent gets them joined.
|
|
203
229
|
#
|
|
204
230
|
# @example
|
|
205
231
|
# llm.stream('The ', 'answer ', 'is ', '4.')
|
|
@@ -207,30 +233,67 @@ module Pikuri
|
|
|
207
233
|
# @param deltas [Array<String>] content fragments, streamed in order
|
|
208
234
|
# @return [self]
|
|
209
235
|
def stream(*deltas)
|
|
210
|
-
|
|
211
|
-
"data: #{JSON.generate('model' => 'fake', 'choices' => [{ 'delta' => { 'content' => d } }])}\n\n"
|
|
212
|
-
end
|
|
213
|
-
chunks << "data: #{JSON.generate('model' => 'fake', 'choices' => [{ 'delta' => {} }],
|
|
214
|
-
'usage' => usage)}\n\n"
|
|
215
|
-
chunks << "data: [DONE]\n\n"
|
|
216
|
-
@responses << { sse: chunks }
|
|
236
|
+
@responses << Completion.new(deltas: deltas, tool_calls: [])
|
|
217
237
|
self
|
|
218
238
|
end
|
|
239
|
+
end
|
|
219
240
|
|
|
220
|
-
|
|
241
|
+
# One scripted assistant turn, rendered to the wire as whichever shape the
|
|
242
|
+
# request asked for.
|
|
243
|
+
#
|
|
244
|
+
# c = Completion.new(deltas: ['The ', 'answer.'], tool_calls: [])
|
|
245
|
+
# c.to_json_body # => {"choices" => [{"message" => {"content" => "The answer.", ...}}], ...}
|
|
246
|
+
# c.to_sse # => ["data: {...\"content\":\"The \"...}\n\n", ..., "data: [DONE]\n\n"]
|
|
247
|
+
#
|
|
248
|
+
# Immutable.
|
|
249
|
+
Completion = Data.define(:deltas, :tool_calls) do
|
|
250
|
+
# @!attribute [r] deltas
|
|
251
|
+
# @return [Array<String>] the text, in the fragments it streams as;
|
|
252
|
+
# empty for a tool-only turn
|
|
253
|
+
# @!attribute [r] tool_calls
|
|
254
|
+
# @return [Array<Completion::ToolCall>] in the order the model asked
|
|
221
255
|
|
|
222
|
-
#
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
256
|
+
# @return [Hash{String => Object}] the OpenAI chat-completion body
|
|
257
|
+
def to_json_body
|
|
258
|
+
message = { 'role' => 'assistant', 'content' => deltas.empty? ? nil : deltas.join }
|
|
259
|
+
unless tool_calls.empty?
|
|
260
|
+
message['tool_calls'] = tool_calls.map do |call|
|
|
261
|
+
{ 'id' => call.id, 'type' => 'function',
|
|
262
|
+
'function' => { 'name' => call.name, 'arguments' => call.arguments } }
|
|
263
|
+
end
|
|
264
|
+
end
|
|
231
265
|
{ 'model' => 'fake', 'choices' => [{ 'message' => message }], 'usage' => usage }
|
|
232
266
|
end
|
|
233
267
|
|
|
268
|
+
# The SSE events a server streams. Each tool call goes out the way a
|
|
269
|
+
# server sends it: +id+ and +name+ first, then its JSON arguments in two
|
|
270
|
+
# fragments keyed only by +index+, which ruby_llm's own accumulator
|
|
271
|
+
# joins back together.
|
|
272
|
+
#
|
|
273
|
+
# @return [Array<String>] one +data:+ event per element, +[DONE]+ last
|
|
274
|
+
def to_sse
|
|
275
|
+
text = deltas.map { |d| { 'content' => d } }
|
|
276
|
+
calls = tool_calls.each_with_index.flat_map do |call, index|
|
|
277
|
+
half = call.arguments.length / 2
|
|
278
|
+
[{ 'index' => index, 'id' => call.id, 'type' => 'function',
|
|
279
|
+
'function' => { 'name' => call.name, 'arguments' => '' } },
|
|
280
|
+
{ 'index' => index, 'function' => { 'arguments' => call.arguments[0...half] } },
|
|
281
|
+
{ 'index' => index, 'function' => { 'arguments' => call.arguments[half..] } }]
|
|
282
|
+
end.map { |fragment| { 'tool_calls' => [fragment] } }
|
|
283
|
+
last = { 'delta' => {} }
|
|
284
|
+
last['finish_reason'] = 'tool_calls' unless tool_calls.empty?
|
|
285
|
+
(text + calls).map { |delta| sse_data('choices' => [{ 'delta' => delta }]) } +
|
|
286
|
+
[sse_data('choices' => [last], 'usage' => usage), "data: [DONE]\n\n"]
|
|
287
|
+
end
|
|
288
|
+
|
|
289
|
+
private
|
|
290
|
+
|
|
291
|
+
# @param body [Hash{String => Object}] one streamed chunk, less its +model+
|
|
292
|
+
# @return [String] its SSE event
|
|
293
|
+
def sse_data(body)
|
|
294
|
+
"data: #{JSON.generate({ 'model' => 'fake' }.merge(body))}\n\n"
|
|
295
|
+
end
|
|
296
|
+
|
|
234
297
|
# Nominal token counts so a {Agent::Event::Tokens} still fires.
|
|
235
298
|
#
|
|
236
299
|
# @return [Hash{String => Integer}]
|
|
@@ -239,6 +302,16 @@ module Pikuri
|
|
|
239
302
|
end
|
|
240
303
|
end
|
|
241
304
|
|
|
305
|
+
# One tool call of a {Completion}.
|
|
306
|
+
#
|
|
307
|
+
# @!attribute [r] id
|
|
308
|
+
# @return [String] e.g. +"call_1"+, numbered across the whole script
|
|
309
|
+
# @!attribute [r] name
|
|
310
|
+
# @return [String] the registered tool name
|
|
311
|
+
# @!attribute [r] arguments
|
|
312
|
+
# @return [String] the arguments, already JSON-encoded
|
|
313
|
+
Completion::ToolCall = Data.define(:id, :name, :arguments)
|
|
314
|
+
|
|
242
315
|
# A latch that holds a fake turn open mid-flight. Pass one to
|
|
243
316
|
# {Testing.fake_transport}; the adapter parks (inside the HTTP call, on the
|
|
244
317
|
# agent's worker thread) at every response while the gate is engaged, so a
|