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
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 7a738319823ef2f5208a2a016af54ecb161082d378f44f5a745ad4fd9fc7044b
|
|
4
|
+
data.tar.gz: 2b2d0bd51009176acd6405b7a4c7e2b7e3127db618269b95f0cb80d597745c29
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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://
|
|
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 (`
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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,
|
|
22
|
-
personas) live in sibling gems and opt in à la carte — see
|
|
23
|
-
[`pikuri-
|
|
24
|
-
[`pikuri-
|
|
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`](
|
|
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.
|
|
54
|
-
|
|
55
|
-
|
|
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
|
|
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
|
-
#
|
|
24
|
-
#
|
|
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]
|
|
47
|
-
#
|
|
48
|
-
# with the model because the cap *is* per-model-per-server.
|
|
49
|
-
#
|
|
50
|
-
#
|
|
51
|
-
# a
|
|
52
|
-
#
|
|
53
|
-
#
|
|
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.
|
|
62
|
-
#
|
|
63
|
-
#
|
|
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]
|
|
82
|
-
#
|
|
83
|
-
#
|
|
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
|
-
|
|
108
|
-
|
|
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
|