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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: f2703004f3ce0c935f4ee932493db6231109f4ecde7bcfe0ec1481dfecc21001
4
- data.tar.gz: adf19fd1af6df3aad4ef58d10d5845ce38932566ba5c9d33a7f45791c34287a3
3
+ metadata.gz: 7a738319823ef2f5208a2a016af54ecb161082d378f44f5a745ad4fd9fc7044b
4
+ data.tar.gz: 2b2d0bd51009176acd6405b7a4c7e2b7e3127db618269b95f0cb80d597745c29
5
5
  SHA512:
6
- metadata.gz: e7475e59d9dc941226a77c875a7236c6649f678e933938bc7d9bbe18a76cbb1b8b492c3d471d94db1e68dc242f2030e25a48c236b3690cb8191a77d403467bae
7
- data.tar.gz: 28345b25378c2ae0dabe37d58b8cc592d2f45c4a634d57f134ecd0c15bad7b157c912aa09f9f93dab46a8e78e035400faf69f0e6a2e4222874ffe88e1c73503f
6
+ metadata.gz: cf9adcef0e8c7d148abe59e8f1b010ec75671802eede2fda6eed16d5dacb327af34d4402bedc1042df7c025d64814a5bb37cec9df55f70afceaa434119f4ce67
7
+ data.tar.gz: 23cbdbe94df3a7a74d9d06944718ec77604afe54c130b621e52a2f3fe218aacc8ab14cbf847bc5868c256460a6e51516b68024bb01318eb1b7e3775730d561bd
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # pikuri-core
2
2
 
3
- The lean, audit-friendly foundation of the [pikuri](https://codeberg.org/mvysny/pikuri)
3
+ The lean, audit-friendly foundation of the [pikuri](https://github.com/mvysny/pikuri)
4
4
  AI-assistant toolkit:
5
5
 
6
6
  - `Pikuri::Agent` — a thin wrapper around ruby_llm's chat loop with
@@ -10,23 +10,19 @@ AI-assistant toolkit:
10
10
  (`Pikuri::Tool::Parameters`) and LLM-actionable error messages.
11
11
  - Listener stream (`Pikuri::Agent::Listener::*`) for rendering,
12
12
  token accounting, and structured capture.
13
- - Controls (`StepLimit`, `Cancellable`, `Interloper`) for budget
14
- enforcement + cancellation.
15
- - Three stateless bundled tools (`CALCULATOR`, `WEB_SCRAPE`,
16
- `FETCH`) plus a host-configured web-search tool built via
17
- `Pikuri::Tool::WebSearch.build` (provider keys passed in, never
18
- read from the environment).
13
+ - Controls (`Cancellable`, `Interloper`) for cancellation and
14
+ mid-loop injection. The loop itself is unbounded — see
15
+ `design/decisions.md` `D_no_step_limit`.
16
+ - One bundled example tool, `Pikuri::Tool::CALCULATOR`.
19
17
  - A demo binary, `bin/pikuri-chat`.
20
18
 
21
- Extensions (skills, MCP, workspace, coding stack, named-agent
22
- personas) live in sibling gems and opt in à la carte — see
23
- [`pikuri-skills`](../pikuri-skills/README.md),
24
- [`pikuri-mcp`](../pikuri-mcp/README.md),
19
+ Extensions (web tools, skills, MCP, workspace, coding stack,
20
+ named-agent personas) live in sibling gems and opt in à la carte — see
21
+ [`pikuri-web`](../pikuri-web/README.md),
22
+ [`pikuri-skills`](https://github.com/mvysny/pikuri-workshop/blob/master/pikuri-skills/README.md),
23
+ [`pikuri-mcp`](https://github.com/mvysny/pikuri-workshop/blob/master/pikuri-mcp/README.md),
25
24
  [`pikuri-workspace`](../pikuri-workspace/README.md),
26
- [`pikuri-code`](../pikuri-code/README.md),
27
- [`pikuri-assistant`](../pikuri-assistant/README.md). For the
28
- convenience bundle that pulls in everything, see the
29
- [`pikuri`](../pikuri/README.md) metagem.
25
+ [`pikuri-code`](https://github.com/mvysny/pikuri-workshop/blob/master/pikuri-code/README.md).
30
26
 
31
27
  ## Install
32
28
 
@@ -44,22 +40,14 @@ gem install pikuri-core
44
40
  ```ruby
45
41
  require 'pikuri-core'
46
42
 
47
- RubyLLM.configure do |c|
48
- c.openai_api_base = 'http://localhost:8080/v1'
49
- c.openai_api_key = 'not-needed'
50
- end
51
-
52
43
  agent = Pikuri::Agent.new(
53
- transport: Pikuri::Agent::ChatTransport.new(
54
- model: 'unsloth/Qwen3.6-35B-A3B-GGUF',
55
- provider: :openai,
56
- assume_model_exists: true
44
+ transport: Pikuri::Agent::ChatTransport.from_openai_server(
45
+ server: 'http://localhost:8080',
46
+ model: 'ornith-ai/Ornith-1.5-35B-A3B-GGUF'
57
47
  ),
58
- system_prompt: Pikuri.prompt(:'pikuri-chat'),
59
- step_limit: Pikuri::Agent::Control::StepLimit.new(max: 20)
48
+ system_prompt: Pikuri.prompt(:'pikuri-chat')
60
49
  ) do |c|
61
50
  c.add_tool Pikuri::Tool::CALCULATOR
62
- c.add_tool Pikuri::Tool::WebSearch.build
63
51
  c.add_listener Pikuri::Agent::Listener::Terminal.new
64
52
  end
65
53
  agent.run_loop(user_message: 'What is 17 * 23?')
@@ -72,8 +60,7 @@ handling, and cancellation.
72
60
 
73
61
  - **Narrative walkthrough:** [the first-conversation chapter of the pikuri guide](../book/chat.md)
74
62
  — install llama.cpp, start the server, run `pikuri-chat`, the
75
- agentic loop, the four bundled tools, and search-provider
76
- privacy postures.
63
+ agentic loop, and the tools `pikuri-chat` wires.
77
64
  - **API reference:** browse the YARD docs at
78
65
  <https://rubydoc.info/gems/pikuri-core> (once published), or run
79
66
  `bundle exec yard` in this directory for a local copy.
@@ -20,8 +20,31 @@ module Pikuri
20
20
  # +#{provider}_api_key+) via a per-chat +RubyLLM::Context+; both +nil+ for a
21
21
  # transport riding the global config.
22
22
  #
23
- # Pure data carrier — no +RubyLLM+ references here, so the seam stays in
24
- # {Agent}, +bin/pikuri-chat+, and {Tool}.
23
+ # No +RubyLLM+ references here, so the seam stays in {Agent},
24
+ # +bin/pikuri-chat+, and {Tool}.
25
+ #
26
+ # == Extra request parameters
27
+ #
28
+ # +params+ is an opaque passthrough for a request key pikuri names no field
29
+ # for. It is deep-merged into the chat-completion payload as written:
30
+ #
31
+ # transport.with(params: { chat_template_kwargs: { enable_thinking: false } })
32
+ # # on the wire: {"model":…,"messages":[…],
33
+ # # "chat_template_kwargs":{"enable_thinking":false}}
34
+ #
35
+ # It rides the transport rather than a call because the spelling is
36
+ # per-model-per-server, exactly like +context_window+; pikuri translates
37
+ # none of it — a parameter is sent as written or not at all. Why there is no
38
+ # typed +thinking:+ flag instead: +design/decisions.md+
39
+ # +D_opaque_request_params+.
40
+ #
41
+ # Two edges worth knowing. Keys are deep-symbolized on the way in (naming
42
+ # one key in both spellings raises), without which a table read from TOML
43
+ # would land a second +"temperature"+ beside the payload's +:temperature+
44
+ # instead of overriding it. And the merge is unguarded: a table naming
45
+ # +messages+, +tools+ or +stream+ breaks the loop rather than configuring
46
+ # it, and one naming +model+ sends a model this transport does not think it
47
+ # is using.
25
48
  #
26
49
  # @!attribute [r] model
27
50
  # @return [String, nil] LLM id; +nil+ defers to
@@ -43,14 +66,20 @@ module Pikuri
43
66
  # config. Mapped to +#{provider}_api_key+ by {Agent}. Redacted in
44
67
  # {#inspect}.
45
68
  # @!attribute [r] context_window
46
- # @return [Integer, nil] explicit context-window cap for this
47
- # model-on-server, or +nil+ to defer to {ContextWindowDetector}. Travels
48
- # with the model because the cap *is* per-model-per-server. Never sent to
49
- # ruby_llm — pure pikuri metadata read by
50
- # {Agent#detect_and_emit_context_cap!}, and the cap-inheritance channel:
51
- # a spawned agent gets +parent.transport.with(context_window:
52
- # parent.context_window_cap)+ so the resolved cap rides along without a
53
- # re-probe.
69
+ # @return [Integer, nil] this model-on-server's context-window cap, or
70
+ # +nil+ when unknown. Travels
71
+ # with the model because the cap *is* per-model-per-server. pikuri
72
+ # never looks it up: the host states it, or a probe the host runs fills
73
+ # it in. Never sent to ruby_llm, and read by nothing in pikuri-core: it
74
+ # is for the host's own display, and a sub-agent inherits it with the
75
+ # transport.
76
+ # @!attribute [r] modalities
77
+ # @return [Hash{Symbol => Boolean}, nil] which input kinds this
78
+ # model-on-server accepts, in llama.cpp's +/props+ vocabulary
79
+ # (+{vision: false, audio: false}+), or +nil+ when unknown. Only a
80
+ # +false+ entry refuses an attachment ({Agent::UnsupportedAttachmentError});
81
+ # a missing key, like +nil+, lets it go out and leaves any error to the
82
+ # server. Stated and inherited like +context_window+.
54
83
  # @!attribute [r] faraday_adapter
55
84
  # @return [Class, Symbol, nil] a custom Faraday adapter to install on this
56
85
  # agent's per-chat +RubyLLM::Context+ (via +config.faraday_adapter=+),
@@ -58,11 +87,15 @@ module Pikuri
58
87
  # inject a VCR / logging / *scripted-fake* adapter without touching the
59
88
  # global +RubyLLM.config+. Its worked use is
60
89
  # {Pikuri::Testing.fake_transport}, which bakes an anonymous scripted
61
- # adapter here so the real ruby_llm loop runs against canned HTTP. Only
62
- # honoured on the connection-override path ({#connection_overrides?}),
63
- # which any adapter-carrying transport is on (it also sets +api_base+).
90
+ # adapter here so the real ruby_llm loop runs against canned HTTP.
91
+ # @!attribute [r] params
92
+ # @return [Hash{Symbol => Object}] extra chat-completion payload keys,
93
+ # merged in verbatim; +{}+ for none. Keys symbolized, and every hash /
94
+ # array node frozen (a value object is *not* deep-frozen: a +String+
95
+ # value the caller still holds stays mutable).
96
+ # See +== Extra request parameters+.
64
97
  class ChatTransport < Data.define(:model, :provider, :assume_model_exists, :api_base, :api_key,
65
- :context_window, :faraday_adapter)
98
+ :context_window, :modalities, :faraday_adapter, :params)
66
99
  # Build an +:openai+-provider transport for an OpenAI-compatible server
67
100
  # (local llama.cpp, cloud endpoint, ...), carrying its connection so the
68
101
  # agent rides a per-chat +RubyLLM::Context+ instead of the global config.
@@ -78,11 +111,14 @@ module Pikuri
78
111
  # @param model [String] model id served there, trusted verbatim
79
112
  # @param api_key [String] API key; the +"not-needed"+ placeholder for a
80
113
  # keyless local server
81
- # @param context_window [Integer, nil] explicit cap, or +nil+ to defer to
82
- # {ContextWindowDetector}'s +/props+ probe (right for local llama.cpp;
83
- # an override for a cloud server the probe can't reach)
114
+ # @param context_window [Integer, nil] the model's cap, or +nil+ for
115
+ # unknown
116
+ # @param params [Hash{String, Symbol => Object}] extra payload keys for
117
+ # this connection, e.g.
118
+ # +{'chat_template_kwargs' => {'enable_thinking' => false}}+
84
119
  # @return [ChatTransport]
85
- def self.from_openai_server(server:, model:, api_key: 'not-needed', context_window: nil)
120
+ def self.from_openai_server(server:, model:, api_key: 'not-needed', context_window: nil,
121
+ params: {})
86
122
  base = server.to_s.strip.chomp('/').delete_suffix('/v1')
87
123
  new(
88
124
  model: model,
@@ -90,7 +126,8 @@ module Pikuri
90
126
  assume_model_exists: true,
91
127
  api_base: "#{base}/v1",
92
128
  api_key: api_key,
93
- context_window: context_window
129
+ context_window: context_window,
130
+ params: params
94
131
  )
95
132
  end
96
133
 
@@ -100,47 +137,91 @@ module Pikuri
100
137
  # @param api_base [String, nil]
101
138
  # @param api_key [String, nil]
102
139
  # @param context_window [Integer, nil]
140
+ # @param modalities [Hash{Symbol => Boolean}, nil]
103
141
  # @param faraday_adapter [Class, Symbol, nil]
142
+ # @param params [Hash{String, Symbol => Object}]
104
143
  # @raise [ArgumentError] if +api_base+ or +api_key+ is set without
105
144
  # a +provider+ (the provider names the config slots the
106
- # connection overrides map onto)
107
- def initialize(model:, provider: nil, assume_model_exists: false,
108
- api_base: nil, api_key: nil, context_window: nil, faraday_adapter: nil)
145
+ # connection overrides map onto), or if +params+ is not a Hash, or
146
+ # names one key in both the +String+ and +Symbol+ spelling
147
+ def initialize(model:, provider: nil, assume_model_exists: false, api_base: nil,
148
+ api_key: nil, context_window: nil, modalities: nil, faraday_adapter: nil,
149
+ params: {})
109
150
  if (api_base || api_key) && provider.nil?
110
151
  raise ArgumentError, "api_base/api_key require a provider, got #{provider.inspect}"
111
152
  end
153
+ raise ArgumentError, "params must be a Hash, got #{params.class}" unless params.is_a?(Hash)
112
154
 
113
- super
155
+ super(model: model, provider: provider, assume_model_exists: assume_model_exists,
156
+ api_base: api_base, api_key: api_key, context_window: context_window,
157
+ modalities: modalities&.transform_keys(&:to_sym)&.freeze,
158
+ faraday_adapter: faraday_adapter, params: deep_symbolize(params))
114
159
  end
115
160
 
116
161
  # Model-resolution kwargs to spread into +RubyLLM.chat+ /
117
162
  # +RubyLLM::Context#chat+. Excludes the connection fields (those configure
118
- # the +Context+, not the +chat+ call).
163
+ # the +Context+, not the +chat+ call) and +params+ (a
164
+ # +with_provider_options+ call on the built chat).
119
165
  #
120
166
  # @return [Hash{Symbol => String, Symbol, Boolean, nil}]
121
167
  def chat_kwargs
122
168
  { model: model, provider: provider, assume_model_exists: assume_model_exists }
123
169
  end
124
170
 
125
- # Whether this transport overrides the process-global connection
126
- # (and so needs a dedicated +RubyLLM::Context+).
127
- #
128
- # @return [Boolean]
129
- def connection_overrides?
130
- !api_base.nil? || !api_key.nil?
131
- end
132
-
133
171
  # Default +Data#inspect+ would print +api_key+ verbatim into any log line
134
172
  # or backtrace. Redact it.
135
173
  #
174
+ # +params+ is configuration rather than a credential channel, so it prints
175
+ # verbatim — anything sensitive a host puts there lands in every log line
176
+ # and backtrace that inspects a transport.
177
+ #
136
178
  # @return [String]
137
179
  def inspect
138
180
  "#<#{self.class} model=#{model.inspect} provider=#{provider.inspect} " \
139
181
  "assume_model_exists=#{assume_model_exists} api_base=#{api_base.inspect} " \
140
182
  "api_key=#{api_key.nil? ? 'nil' : '[REDACTED]'} context_window=#{context_window.inspect} " \
141
- "faraday_adapter=#{faraday_adapter.inspect}>"
183
+ "modalities=#{modalities.inspect} faraday_adapter=#{faraday_adapter.inspect} params=#{params.inspect}>"
142
184
  end
143
185
  alias to_s inspect
186
+
187
+ private
188
+
189
+ # Recursively symbolize +value+'s hash keys, freezing what it builds.
190
+ # Scalars pass through as they are — only the containers are rebuilt.
191
+ #
192
+ # @param value [Hash, Array, Object] any +params+ subtree.
193
+ # @return [Hash, Array, Object] the same shape, symbol-keyed, with every
194
+ # hash / array node frozen.
195
+ # @raise [ArgumentError] if a hash names one key in both spellings —
196
+ # the merge can send only one of them, and picking silently is the
197
+ # failure mode this whole channel exists to avoid.
198
+ def deep_symbolize(value)
199
+ case value
200
+ when Hash
201
+ symbolized = value.to_h { |k, v| [symbolize_key(k), deep_symbolize(v)] }
202
+ reject_collisions(value) if symbolized.size < value.size
203
+ symbolized.freeze
204
+ when Array
205
+ value.map { |item| deep_symbolize(item) }.freeze
206
+ else
207
+ value
208
+ end
209
+ end
210
+
211
+ # @param key [Object] a +params+ hash key.
212
+ # @return [Object] +key+ as a +Symbol+, or unchanged if it has no
213
+ # symbol form (an +Integer+ key in a provider's own table).
214
+ def symbolize_key(key)
215
+ key.respond_to?(:to_sym) ? key.to_sym : key
216
+ end
217
+
218
+ # @param table [Hash] the pre-symbolize hash whose keys collided.
219
+ # @return [void]
220
+ # @raise [ArgumentError] always, naming the colliding spellings.
221
+ def reject_collisions(table)
222
+ collided = table.keys.group_by { |k| symbolize_key(k) }.select { |_, ks| ks.size > 1 }
223
+ raise ArgumentError, "params names a key twice: #{collided.values.flatten.inspect}"
224
+ end
144
225
  end
145
226
  end
146
227
  end