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.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +16 -29
  3. data/lib/pikuri/agent/chat_transport.rb +114 -33
  4. data/lib/pikuri/agent/configurator.rb +191 -110
  5. data/lib/pikuri/agent/control/cancellable.rb +25 -16
  6. data/lib/pikuri/agent/control/handoff.rb +75 -0
  7. data/lib/pikuri/agent/control/interloper.rb +87 -120
  8. data/lib/pikuri/agent/control.rb +9 -11
  9. data/lib/pikuri/agent/event.rb +73 -61
  10. data/lib/pikuri/agent/extension.rb +45 -81
  11. data/lib/pikuri/agent/history.rb +91 -497
  12. data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
  13. data/lib/pikuri/agent/listener/terminal.rb +115 -108
  14. data/lib/pikuri/agent/listener/token_log.rb +21 -55
  15. data/lib/pikuri/agent/listener.rb +4 -4
  16. data/lib/pikuri/agent/listener_list.rb +19 -13
  17. data/lib/pikuri/agent/request_instrumenter.rb +102 -0
  18. data/lib/pikuri/agent.rb +624 -448
  19. data/lib/pikuri/attachment.rb +65 -0
  20. data/lib/pikuri/extractor/passthrough.rb +5 -2
  21. data/lib/pikuri/extractor.rb +43 -12
  22. data/lib/pikuri/file_type.rb +4 -4
  23. data/lib/pikuri/finalizers.rb +2 -2
  24. data/lib/pikuri/paths.rb +1 -1
  25. data/lib/pikuri/sanitizer.rb +4 -3
  26. data/lib/pikuri/subprocess.rb +17 -5
  27. data/lib/pikuri/testing.rb +122 -49
  28. data/lib/pikuri/tool/calculator.rb +134 -30
  29. data/lib/pikuri/tool/execute_context.rb +2 -2
  30. data/lib/pikuri/tool/parameters.rb +10 -0
  31. data/lib/pikuri/tool/result.rb +164 -0
  32. data/lib/pikuri/tool/trifecta_legs.rb +52 -21
  33. data/lib/pikuri/tool.rb +298 -24
  34. data/lib/pikuri/trifecta/report.rb +28 -30
  35. data/lib/pikuri/trifecta.rb +1 -2
  36. data/lib/pikuri/version.rb +1 -1
  37. data/lib/pikuri-core.rb +5 -11
  38. metadata +16 -73
  39. data/lib/pikuri/agent/context_window_detector.rb +0 -181
  40. data/lib/pikuri/agent/control/step_limit.rb +0 -95
  41. data/lib/pikuri/agent/extension_context.rb +0 -120
  42. data/lib/pikuri/agent/listener/rate_limited.rb +0 -146
  43. data/lib/pikuri/agent/synthesizer.rb +0 -129
  44. data/lib/pikuri/extractor/html.rb +0 -256
  45. data/lib/pikuri/ruby_llm_patches.rb +0 -106
  46. data/lib/pikuri/tool/fetch.rb +0 -146
  47. data/lib/pikuri/tool/scraper.rb +0 -144
  48. data/lib/pikuri/tool/search/brave.rb +0 -170
  49. data/lib/pikuri/tool/search/duckduckgo.rb +0 -175
  50. data/lib/pikuri/tool/search/engines.rb +0 -319
  51. data/lib/pikuri/tool/search/exa.rb +0 -195
  52. data/lib/pikuri/tool/search/rate_limiter.rb +0 -115
  53. data/lib/pikuri/tool/search/result.rb +0 -24
  54. data/lib/pikuri/tool/web_scrape.rb +0 -105
  55. data/lib/pikuri/tool/web_search.rb +0 -133
  56. 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.
@@ -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 (HTML + plain text in core;
6
- # PDF / office formats via the pikuri-pdf / pikuri-extractors gems) into
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
- # +Tool::Scraper+ (dispatching on the HTTP +Content-Type+) and {FileType}
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. {.extract_paged} prefers it and stops
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 ({HTML}, any subprocess-based one) omit it, and
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+ — 1-indexed line number of +lines.first+ (the requested
91
- # +offset+).
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 {HTML} (content-type) then the terminal {Passthrough} plain-text
108
- # arm. A gem picks its insertion point by claim strength: a magic-byte
109
- # sniff that never misfires on text goes at the *front* to beat {HTML}
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-extractors).
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 ||= [HTML, Passthrough]
147
+ @registry ||= [Passthrough]
117
148
  end
118
149
 
119
150
  # Extract the whole document behind +io+ as one Markdown-flavoured UTF-8
@@ -170,9 +170,8 @@ module Pikuri
170
170
  end
171
171
  private_class_method :guard_extractable
172
172
 
173
- # Coerce +input+ into a bytes String for the sniffs: a +String+ is
174
- # returned as-is, a +Pathname+ is opened binary and up to {SAMPLE_BYTES}
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
- input
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
@@ -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
- # {VectorDb::Server::Chroma}, background workers) registering here instead of
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 indexer writing into {VectorDb::Server::Chroma}) registers later
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 / Chroma
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.
@@ -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 or rewrites a tab, because the user must see exactly what they
23
- # approve (a Makefile's leading tab stays a tab). A web chrome adds
24
- # +html_escape+ on top; the HTML layer is the caller's.
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
  #
@@ -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 (plus the MCP-exception comment in
20
- # +pikuri-mcp/lib/pikuri/mcp/servers.rb+).
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 the stdin→markdown converters (pikuri-extractors),
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 *daemon* child (one the caller never {#wait}s on, e.g.
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
  #
@@ -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 / the synthesizer works (they derive their transport via
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
- # Tool-call *streaming* (fragmented +tool_calls+ deltas) is not modelled;
48
- # {Script#stream} streams text only.
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 so
63
- # {Agent#detect_and_emit_context_cap!} skips the real +/props+ HTTP probe
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
- # An api_base forces the connection-override path (Context#chat), the
83
- # only branch that honours faraday_adapter; the host is never dialed.
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
- faraday_adapter: build_adapter(script.responses, gate)
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<Hash>] entries shaped +{json: Hash}+ (non-stream)
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
- entry = queue.shift or raise "Pikuri::Testing: no scripted response left for #{env.url}"
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
- entry.fetch(:sse).each do |chunk|
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(entry.fetch(:json)),
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 appends one OpenAI-wire
133
- # response body to {#responses}, in call order. You don't build these
134
- # directly — {Testing.fake_transport} yields one to your block.
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.') # a streamed answer
168
+ # llm.stream('The ', 'answer ', 'is ', '4.') # an answer in chosen deltas
140
169
  # end
141
170
  class Script
142
- # @return [Array<Hash>] queued response entries in call order
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
- @responses << { json: assistant_body(content: text) }
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
- wire = calls.map do |name, arguments|
217
+ tool_calls = calls.map do |name, arguments|
190
218
  @tool_call_seq += 1
191
- { 'id' => "call_#{@tool_call_seq}", 'type' => 'function',
192
- 'function' => { 'name' => name, 'arguments' => JSON.generate(arguments || {}) } }
219
+ Completion::ToolCall.new(id: "call_#{@tool_call_seq}", name: name,
220
+ arguments: JSON.generate(arguments || {}))
193
221
  end
194
- @responses << { json: assistant_body(content: nil, tool_calls: wire) }
222
+ @responses << Completion.new(deltas: [], tool_calls: tool_calls)
195
223
  self
196
224
  end
197
225
 
198
- # Queue a *streamed* assistant-text turn: each +delta+ becomes one SSE
199
- # chunk, so a +streaming: true+ agent emits a matching sequence of
200
- # {Agent::Event::AssistantDelta}s and a final assembled
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
- chunks = deltas.map do |d|
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
- private
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
- # One OpenAI chat-completion body: an assistant message, optionally with
223
- # +tool_calls+.
224
- #
225
- # @param content [String, nil]
226
- # @param tool_calls [Array<Hash>, nil]
227
- # @return [Hash]
228
- def assistant_body(content:, tool_calls: nil)
229
- message = { 'role' => 'assistant', 'content' => content }
230
- message['tool_calls'] = tool_calls if tool_calls
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