pikuri-core 0.0.7 → 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 +17 -30
- data/lib/pikuri/agent/chat_transport.rb +168 -107
- data/lib/pikuri/agent/configurator.rb +194 -173
- data/lib/pikuri/agent/control/cancellable.rb +100 -70
- data/lib/pikuri/agent/control/handoff.rb +75 -0
- data/lib/pikuri/agent/control/interloper.rb +107 -118
- data/lib/pikuri/agent/control.rb +13 -35
- data/lib/pikuri/agent/event.rb +144 -197
- data/lib/pikuri/agent/extension.rb +83 -95
- data/lib/pikuri/agent/history.rb +247 -0
- data/lib/pikuri/agent/listener/in_memory_event_list.rb +1 -1
- data/lib/pikuri/agent/listener/terminal.rb +169 -136
- data/lib/pikuri/agent/listener/token_log.rb +84 -157
- data/lib/pikuri/agent/listener.rb +24 -44
- data/lib/pikuri/agent/listener_list.rb +32 -47
- data/lib/pikuri/agent/request_instrumenter.rb +102 -0
- data/lib/pikuri/agent.rb +1095 -577
- data/lib/pikuri/attachment.rb +65 -0
- data/lib/pikuri/bundler_env.rb +68 -0
- data/lib/pikuri/extractor/passthrough.rb +24 -31
- data/lib/pikuri/extractor.rb +125 -155
- data/lib/pikuri/file_type.rb +64 -136
- data/lib/pikuri/finalizers.rb +32 -47
- data/lib/pikuri/paths.rb +104 -13
- data/lib/pikuri/sanitizer.rb +46 -67
- data/lib/pikuri/subprocess.rb +86 -118
- data/lib/pikuri/testing.rb +369 -0
- data/lib/pikuri/tool/calculator.rb +168 -74
- data/lib/pikuri/tool/execute_context.rb +42 -0
- data/lib/pikuri/tool/parameters.rb +31 -29
- data/lib/pikuri/tool/result.rb +164 -0
- data/lib/pikuri/tool/trifecta_legs.rb +248 -0
- data/lib/pikuri/tool.rb +416 -67
- data/lib/pikuri/trifecta/contribution.rb +43 -0
- data/lib/pikuri/trifecta/node.rb +47 -0
- data/lib/pikuri/trifecta/report.rb +228 -0
- data/lib/pikuri/trifecta.rb +126 -0
- data/lib/pikuri/version.rb +1 -1
- data/lib/pikuri-core.rb +70 -92
- data/prompts/agent-loop.txt +5 -0
- data/prompts/pikuri-chat.txt +3 -12
- metadata +26 -72
- data/lib/pikuri/agent/context_window_detector.rb +0 -222
- data/lib/pikuri/agent/control/step_limit.rb +0 -111
- data/lib/pikuri/agent/extension_context.rb +0 -147
- data/lib/pikuri/agent/listener/rate_limited.rb +0 -172
- data/lib/pikuri/agent/synthesizer.rb +0 -171
- data/lib/pikuri/extractor/html.rb +0 -303
- data/lib/pikuri/tool/fetch.rb +0 -172
- data/lib/pikuri/tool/scraper.rb +0 -186
- data/lib/pikuri/tool/search/brave.rb +0 -198
- data/lib/pikuri/tool/search/duckduckgo.rb +0 -207
- data/lib/pikuri/tool/search/engines.rb +0 -186
- data/lib/pikuri/tool/search/exa.rb +0 -229
- data/lib/pikuri/tool/search/rate_limiter.rb +0 -92
- data/lib/pikuri/tool/search/result.rb +0 -29
- data/lib/pikuri/tool/web_scrape.rb +0 -121
- data/lib/pikuri/tool/web_search.rb +0 -57
- data/lib/pikuri/url_cache.rb +0 -112
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: pikuri-core
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.0
|
|
4
|
+
version: 0.2.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Martin Vysny
|
|
@@ -23,20 +23,6 @@ dependencies:
|
|
|
23
23
|
- - "~>"
|
|
24
24
|
- !ruby/object:Gem::Version
|
|
25
25
|
version: '2.9'
|
|
26
|
-
- !ruby/object:Gem::Dependency
|
|
27
|
-
name: nokogiri
|
|
28
|
-
requirement: !ruby/object:Gem::Requirement
|
|
29
|
-
requirements:
|
|
30
|
-
- - "~>"
|
|
31
|
-
- !ruby/object:Gem::Version
|
|
32
|
-
version: '1.19'
|
|
33
|
-
type: :runtime
|
|
34
|
-
prerelease: false
|
|
35
|
-
version_requirements: !ruby/object:Gem::Requirement
|
|
36
|
-
requirements:
|
|
37
|
-
- - "~>"
|
|
38
|
-
- !ruby/object:Gem::Version
|
|
39
|
-
version: '1.19'
|
|
40
26
|
- !ruby/object:Gem::Dependency
|
|
41
27
|
name: rainbow
|
|
42
28
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -51,48 +37,20 @@ dependencies:
|
|
|
51
37
|
- - "~>"
|
|
52
38
|
- !ruby/object:Gem::Version
|
|
53
39
|
version: '3.1'
|
|
54
|
-
- !ruby/object:Gem::Dependency
|
|
55
|
-
name: reverse_markdown
|
|
56
|
-
requirement: !ruby/object:Gem::Requirement
|
|
57
|
-
requirements:
|
|
58
|
-
- - "~>"
|
|
59
|
-
- !ruby/object:Gem::Version
|
|
60
|
-
version: '3.0'
|
|
61
|
-
type: :runtime
|
|
62
|
-
prerelease: false
|
|
63
|
-
version_requirements: !ruby/object:Gem::Requirement
|
|
64
|
-
requirements:
|
|
65
|
-
- - "~>"
|
|
66
|
-
- !ruby/object:Gem::Version
|
|
67
|
-
version: '3.0'
|
|
68
|
-
- !ruby/object:Gem::Dependency
|
|
69
|
-
name: ruby-readability
|
|
70
|
-
requirement: !ruby/object:Gem::Requirement
|
|
71
|
-
requirements:
|
|
72
|
-
- - "~>"
|
|
73
|
-
- !ruby/object:Gem::Version
|
|
74
|
-
version: '0.7'
|
|
75
|
-
type: :runtime
|
|
76
|
-
prerelease: false
|
|
77
|
-
version_requirements: !ruby/object:Gem::Requirement
|
|
78
|
-
requirements:
|
|
79
|
-
- - "~>"
|
|
80
|
-
- !ruby/object:Gem::Version
|
|
81
|
-
version: '0.7'
|
|
82
40
|
- !ruby/object:Gem::Dependency
|
|
83
41
|
name: ruby_llm
|
|
84
42
|
requirement: !ruby/object:Gem::Requirement
|
|
85
43
|
requirements:
|
|
86
44
|
- - "~>"
|
|
87
45
|
- !ruby/object:Gem::Version
|
|
88
|
-
version: '
|
|
46
|
+
version: '2.2'
|
|
89
47
|
type: :runtime
|
|
90
48
|
prerelease: false
|
|
91
49
|
version_requirements: !ruby/object:Gem::Requirement
|
|
92
50
|
requirements:
|
|
93
51
|
- - "~>"
|
|
94
52
|
- !ruby/object:Gem::Version
|
|
95
|
-
version: '
|
|
53
|
+
version: '2.2'
|
|
96
54
|
- !ruby/object:Gem::Dependency
|
|
97
55
|
name: zeitwerk
|
|
98
56
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -111,12 +69,11 @@ description: |
|
|
|
111
69
|
pikuri-core is the lean, audit-friendly foundation of the pikuri family:
|
|
112
70
|
Pikuri::Agent (a thin wrapper around ruby_llm's chat loop) with its
|
|
113
71
|
Configurator + Extension protocol, the strict Pikuri::Tool framework, a
|
|
114
|
-
listener surface for rendering / budgets / sub-agents, and
|
|
115
|
-
|
|
116
|
-
|
|
72
|
+
listener surface for rendering / budgets / sub-agents, and a calculator
|
|
73
|
+
as the one bundled example tool. Extensions (web tools, skills, MCP,
|
|
74
|
+
workspace, coding stack, named-agent personas) live in
|
|
117
75
|
sibling gems so a privacy-conscious user can install just this core and
|
|
118
|
-
audit a minimal dependency tree.
|
|
119
|
-
in everything, see the +pikuri+ metagem.
|
|
76
|
+
audit a minimal dependency tree.
|
|
120
77
|
email:
|
|
121
78
|
- martin@vysny.me
|
|
122
79
|
executables: []
|
|
@@ -128,52 +85,49 @@ files:
|
|
|
128
85
|
- lib/pikuri/agent.rb
|
|
129
86
|
- lib/pikuri/agent/chat_transport.rb
|
|
130
87
|
- lib/pikuri/agent/configurator.rb
|
|
131
|
-
- lib/pikuri/agent/context_window_detector.rb
|
|
132
88
|
- lib/pikuri/agent/control.rb
|
|
133
89
|
- lib/pikuri/agent/control/cancellable.rb
|
|
90
|
+
- lib/pikuri/agent/control/handoff.rb
|
|
134
91
|
- lib/pikuri/agent/control/interloper.rb
|
|
135
|
-
- lib/pikuri/agent/control/step_limit.rb
|
|
136
92
|
- lib/pikuri/agent/event.rb
|
|
137
93
|
- lib/pikuri/agent/extension.rb
|
|
138
|
-
- lib/pikuri/agent/
|
|
94
|
+
- lib/pikuri/agent/history.rb
|
|
139
95
|
- lib/pikuri/agent/listener.rb
|
|
140
96
|
- lib/pikuri/agent/listener/in_memory_event_list.rb
|
|
141
|
-
- lib/pikuri/agent/listener/rate_limited.rb
|
|
142
97
|
- lib/pikuri/agent/listener/terminal.rb
|
|
143
98
|
- lib/pikuri/agent/listener/token_log.rb
|
|
144
99
|
- lib/pikuri/agent/listener_list.rb
|
|
145
|
-
- lib/pikuri/agent/
|
|
100
|
+
- lib/pikuri/agent/request_instrumenter.rb
|
|
101
|
+
- lib/pikuri/attachment.rb
|
|
102
|
+
- lib/pikuri/bundler_env.rb
|
|
146
103
|
- lib/pikuri/extractor.rb
|
|
147
|
-
- lib/pikuri/extractor/html.rb
|
|
148
104
|
- lib/pikuri/extractor/passthrough.rb
|
|
149
105
|
- lib/pikuri/file_type.rb
|
|
150
106
|
- lib/pikuri/finalizers.rb
|
|
151
107
|
- lib/pikuri/paths.rb
|
|
152
108
|
- lib/pikuri/sanitizer.rb
|
|
153
109
|
- lib/pikuri/subprocess.rb
|
|
110
|
+
- lib/pikuri/testing.rb
|
|
154
111
|
- lib/pikuri/tool.rb
|
|
155
112
|
- lib/pikuri/tool/calculator.rb
|
|
156
|
-
- lib/pikuri/tool/
|
|
113
|
+
- lib/pikuri/tool/execute_context.rb
|
|
157
114
|
- lib/pikuri/tool/parameters.rb
|
|
158
|
-
- lib/pikuri/tool/
|
|
159
|
-
- lib/pikuri/tool/
|
|
160
|
-
- lib/pikuri/
|
|
161
|
-
- lib/pikuri/
|
|
162
|
-
- lib/pikuri/
|
|
163
|
-
- lib/pikuri/
|
|
164
|
-
- lib/pikuri/tool/search/result.rb
|
|
165
|
-
- lib/pikuri/tool/web_scrape.rb
|
|
166
|
-
- lib/pikuri/tool/web_search.rb
|
|
167
|
-
- lib/pikuri/url_cache.rb
|
|
115
|
+
- lib/pikuri/tool/result.rb
|
|
116
|
+
- lib/pikuri/tool/trifecta_legs.rb
|
|
117
|
+
- lib/pikuri/trifecta.rb
|
|
118
|
+
- lib/pikuri/trifecta/contribution.rb
|
|
119
|
+
- lib/pikuri/trifecta/node.rb
|
|
120
|
+
- lib/pikuri/trifecta/report.rb
|
|
168
121
|
- lib/pikuri/version.rb
|
|
122
|
+
- prompts/agent-loop.txt
|
|
169
123
|
- prompts/pikuri-chat.txt
|
|
170
|
-
homepage: https://
|
|
124
|
+
homepage: https://github.com/mvysny/pikuri
|
|
171
125
|
licenses:
|
|
172
126
|
- MIT
|
|
173
127
|
metadata:
|
|
174
|
-
source_code_uri: https://
|
|
175
|
-
changelog_uri: https://
|
|
176
|
-
bug_tracker_uri: https://
|
|
128
|
+
source_code_uri: https://github.com/mvysny/pikuri/tree/master
|
|
129
|
+
changelog_uri: https://github.com/mvysny/pikuri/blob/master/CHANGELOG.md
|
|
130
|
+
bug_tracker_uri: https://github.com/mvysny/pikuri/issues
|
|
177
131
|
rubygems_mfa_required: 'true'
|
|
178
132
|
rdoc_options: []
|
|
179
133
|
require_paths:
|
|
@@ -192,5 +146,5 @@ requirements: []
|
|
|
192
146
|
rubygems_version: 3.6.7
|
|
193
147
|
specification_version: 4
|
|
194
148
|
summary: The minimal core of the pikuri AI-assistant toolkit (Agent, Tool framework,
|
|
195
|
-
|
|
149
|
+
bin/pikuri-chat).
|
|
196
150
|
test_files: []
|
|
@@ -1,222 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
require 'ruby_llm'
|
|
4
|
-
require 'faraday'
|
|
5
|
-
require 'json'
|
|
6
|
-
require 'cgi'
|
|
7
|
-
|
|
8
|
-
module Pikuri
|
|
9
|
-
class Agent
|
|
10
|
-
# Resolves the model's context-window cap by asking the server that
|
|
11
|
-
# actually serves it. The only authoritative runtime source pikuri
|
|
12
|
-
# has is llama.cpp's non-standard +/props+ endpoint, which reports
|
|
13
|
-
# the server's *launched* +n_ctx+ (the real window — possibly
|
|
14
|
-
# smaller than the model's theoretical max, e.g. +llama-server -c
|
|
15
|
-
# 8192+ on a 128k model). Returns +nil+ — an honest "we don't
|
|
16
|
-
# know" — for anything else.
|
|
17
|
-
#
|
|
18
|
-
# Used by {Agent#detect_and_emit_context_cap!} at construction and
|
|
19
|
-
# after every model switch to feed {Listener::TokenLog} a cap it can
|
|
20
|
-
# render alongside the running context size (so the +ctx=12.2k/32.0k+
|
|
21
|
-
# line tells the operator how close the conversation is to the limit).
|
|
22
|
-
# The caller prefers an explicit/inherited
|
|
23
|
-
# {ChatTransport#context_window} over this probe; this runs only when
|
|
24
|
-
# the transport carries none.
|
|
25
|
-
#
|
|
26
|
-
# == Why no ruby_llm registry source
|
|
27
|
-
#
|
|
28
|
-
# +RubyLLM::Model::Info#context_window+ is a static lookup in a
|
|
29
|
-
# bundled +models.json+ snapshot: +nil+ for every +assume_exists+
|
|
30
|
-
# local model id, +nil+ for anything newer than the snapshot, and —
|
|
31
|
-
# worst — a *frozen* value for known models, so a window the provider
|
|
32
|
-
# later bumped (256k → 1M) still reports the old number. A cap you
|
|
33
|
-
# have to caveat defeats the cap's only job (a number trustworthy
|
|
34
|
-
# enough to act on before +RubyLLM::ContextLengthExceededError+), so
|
|
35
|
-
# pikuri deliberately does not consult it. The probe (server truth)
|
|
36
|
-
# and an explicit {ChatTransport#context_window} (operator/parent
|
|
37
|
-
# truth) are the only two sources; absent both, the cap is +nil+.
|
|
38
|
-
#
|
|
39
|
-
# == The openai-provider gate + auto-derived URL
|
|
40
|
-
#
|
|
41
|
-
# The probe only makes sense against an OpenAI-compatible local
|
|
42
|
-
# server (llama.cpp), reached through ruby_llm's +:openai+ provider
|
|
43
|
-
# with a custom base. So {.detect} runs only when
|
|
44
|
-
# +transport.provider == :openai+ and derives the probe URL from the
|
|
45
|
-
# *same* +RubyLLM.config.openai_api_base+ the chat itself uses —
|
|
46
|
-
# +/props+ lives at the host root, NOT under +/v1+, so the +/v1+
|
|
47
|
-
# suffix is stripped. Deriving from the live config (rather than a
|
|
48
|
-
# URL passed in) means the probe can't target a different server than
|
|
49
|
-
# the chat. A bare +:openai+ pointed at real +api.openai.com+ gets
|
|
50
|
-
# one fast +/props+ 404 that degrades to +nil+ (the simple gate; not
|
|
51
|
-
# worth narrowing — you're already sending that server the whole
|
|
52
|
-
# conversation).
|
|
53
|
-
#
|
|
54
|
-
# == llama.cpp router mode
|
|
55
|
-
#
|
|
56
|
-
# A llama.cpp *router* (the multi-instance front that proxies to N
|
|
57
|
-
# on-demand model servers) answers a bare +/props+ with
|
|
58
|
-
# +{"role":"router", ..., "n_ctx":0}+ — there is no single loaded
|
|
59
|
-
# model at the router itself, so its top-level +n_ctx+ is +0+. The
|
|
60
|
-
# real per-model cap is one proxied hop away: +GET /props?model=<id>+
|
|
61
|
-
# routes the probe to that model's instance, whose +/props+ carries
|
|
62
|
-
# the launched +n_ctx+. So when the bare probe reports +role: router+
|
|
63
|
-
# and a +model_id+ is known, this re-probes with the model id before
|
|
64
|
-
# giving up. A plain single-model server is untouched: its bare
|
|
65
|
-
# +/props+ already carries a positive +n_ctx+, so the router branch
|
|
66
|
-
# never runs.
|
|
67
|
-
#
|
|
68
|
-
# == Failure handling
|
|
69
|
-
#
|
|
70
|
-
# The probe is best-effort. HTTP error, timeout, non-JSON body, or a
|
|
71
|
-
# missing/invalid +n_ctx+ field all return +nil+ and log one +warn+
|
|
72
|
-
# line via +Pikuri.logger_for('ContextWindowDetector')+. This is the
|
|
73
|
-
# CLAUDE.md "secondary to the loop" carve-out — a wedged or
|
|
74
|
-
# non-llama.cpp server should not abort agent construction over a
|
|
75
|
-
# cosmetic readout.
|
|
76
|
-
class ContextWindowDetector
|
|
77
|
-
# Subsystem logger; set its level with
|
|
78
|
-
# +PIKURI_LOG_CONTEXTWINDOWDETECTOR+ or the global +PIKURI_LOG+.
|
|
79
|
-
#
|
|
80
|
-
# @return [Logger]
|
|
81
|
-
LOGGER = Pikuri.logger_for('ContextWindowDetector')
|
|
82
|
-
|
|
83
|
-
# Connect timeout in seconds for the llama.cpp +/props+ probe.
|
|
84
|
-
# Short on purpose: a server that isn't even listening should fail
|
|
85
|
-
# fast rather than stall +Agent+ construction.
|
|
86
|
-
#
|
|
87
|
-
# @return [Integer]
|
|
88
|
-
OPEN_TIMEOUT = 2
|
|
89
|
-
# Read timeout in seconds for the llama.cpp +/props+ probe.
|
|
90
|
-
# Generous on purpose, and the reason it differs from
|
|
91
|
-
# {OPEN_TIMEOUT}: a llama.cpp router answers +/props?model=<id>+
|
|
92
|
-
# only *after* spinning up that model's instance, and a cold model
|
|
93
|
-
# load can take 10+ seconds — which the next chat turn must wait
|
|
94
|
-
# for anyway. A read timeout shorter than the load would abandon
|
|
95
|
-
# the probe (and lose the cap) precisely when switching to a
|
|
96
|
-
# cold model. A server that accepts the connection but then hangs
|
|
97
|
-
# would stall the actual chat identically, so tolerating the wait
|
|
98
|
-
# here costs nothing extra.
|
|
99
|
-
#
|
|
100
|
-
# @return [Integer]
|
|
101
|
-
READ_TIMEOUT = 30
|
|
102
|
-
|
|
103
|
-
# Resolve the context-window cap for +transport+ by probing the
|
|
104
|
-
# server that serves it.
|
|
105
|
-
#
|
|
106
|
-
# @param transport [Agent::ChatTransport] the model-resolution
|
|
107
|
-
# triple; +provider+ gates the probe and +model+ drives the
|
|
108
|
-
# router +?model=+ hop
|
|
109
|
-
# @param openai_base [String, nil] the configured OpenAI-compatible
|
|
110
|
-
# base URL the probe URL is derived from; defaults to the live
|
|
111
|
-
# +RubyLLM.config.openai_api_base+. Passed explicitly only by
|
|
112
|
-
# tests, which don't want to mutate global config.
|
|
113
|
-
# @return [Integer, nil] the launched +n_ctx+, or +nil+ for a
|
|
114
|
-
# non-+:openai+ transport, an unconfigured base, or any probe
|
|
115
|
-
# failure
|
|
116
|
-
def self.detect(transport, openai_base: RubyLLM.config.openai_api_base)
|
|
117
|
-
return nil unless transport.provider == :openai
|
|
118
|
-
|
|
119
|
-
url = props_url(openai_base)
|
|
120
|
-
return nil if url.nil?
|
|
121
|
-
|
|
122
|
-
new(probe_url: url, model_id: transport.model).probe
|
|
123
|
-
end
|
|
124
|
-
|
|
125
|
-
# Derive the llama.cpp +/props+ URL from the OpenAI-compatible
|
|
126
|
-
# base. +/props+ sits at the host root, so a trailing +/v1+ is
|
|
127
|
-
# stripped before appending.
|
|
128
|
-
#
|
|
129
|
-
# @param openai_base [String, nil]
|
|
130
|
-
# @return [String, nil] the +/props+ URL, or +nil+ when the base
|
|
131
|
-
# is blank
|
|
132
|
-
def self.props_url(openai_base)
|
|
133
|
-
base = openai_base.to_s.strip.chomp('/')
|
|
134
|
-
return nil if base.empty?
|
|
135
|
-
|
|
136
|
-
"#{base.delete_suffix('/v1')}/props"
|
|
137
|
-
end
|
|
138
|
-
|
|
139
|
-
# @param probe_url [String] full URL to llama.cpp +/props+
|
|
140
|
-
# @param model_id [String, nil] the chat model id, used to follow a
|
|
141
|
-
# llama.cpp router via +/props?model=<id>+ when the bare probe
|
|
142
|
-
# reports +role: router+. +nil+ or empty disables that second hop.
|
|
143
|
-
def initialize(probe_url:, model_id:)
|
|
144
|
-
@probe_url = probe_url
|
|
145
|
-
@model_id = model_id
|
|
146
|
-
end
|
|
147
|
-
|
|
148
|
-
# @return [Integer, nil] resolved cap, or +nil+ if the probe
|
|
149
|
-
# produced none
|
|
150
|
-
def probe
|
|
151
|
-
probe_llama_cpp
|
|
152
|
-
end
|
|
153
|
-
|
|
154
|
-
private
|
|
155
|
-
|
|
156
|
-
def probe_llama_cpp
|
|
157
|
-
data = fetch_props(@probe_url)
|
|
158
|
-
return nil if data.nil?
|
|
159
|
-
|
|
160
|
-
n_ctx = positive_n_ctx(data)
|
|
161
|
-
return n_ctx if n_ctx
|
|
162
|
-
|
|
163
|
-
# llama.cpp router: the bare /props carries no model, so its
|
|
164
|
-
# n_ctx is 0. Follow the router to the model's own instance.
|
|
165
|
-
return probe_router_model if data['role'] == 'router' && model_id_present?
|
|
166
|
-
|
|
167
|
-
warn_and_nil(
|
|
168
|
-
"no positive integer at default_generation_settings.n_ctx in #{@probe_url} response"
|
|
169
|
-
)
|
|
170
|
-
end
|
|
171
|
-
|
|
172
|
-
def probe_router_model
|
|
173
|
-
url = "#{@probe_url}?model=#{CGI.escape(@model_id)}"
|
|
174
|
-
data = fetch_props(url)
|
|
175
|
-
return nil if data.nil?
|
|
176
|
-
|
|
177
|
-
n_ctx = positive_n_ctx(data)
|
|
178
|
-
return n_ctx if n_ctx
|
|
179
|
-
|
|
180
|
-
warn_and_nil(
|
|
181
|
-
"no positive integer at default_generation_settings.n_ctx in router probe #{url}"
|
|
182
|
-
)
|
|
183
|
-
end
|
|
184
|
-
|
|
185
|
-
# GETs +url+ and parses its JSON body.
|
|
186
|
-
#
|
|
187
|
-
# @param url [String] a llama.cpp +/props+ URL
|
|
188
|
-
# @return [Hash, nil] the parsed body, or +nil+ (after one +warn+
|
|
189
|
-
# line) on non-200, timeout, transport error, or non-JSON body
|
|
190
|
-
def fetch_props(url)
|
|
191
|
-
response = Faraday.new(
|
|
192
|
-
request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }
|
|
193
|
-
).get(url) do |req|
|
|
194
|
-
req.headers['Accept'] = 'application/json'
|
|
195
|
-
end
|
|
196
|
-
|
|
197
|
-
return warn_and_nil("HTTP #{response.status} from #{url}") unless response.status == 200
|
|
198
|
-
|
|
199
|
-
JSON.parse(response.body)
|
|
200
|
-
rescue Faraday::Error, JSON::ParserError => e
|
|
201
|
-
warn_and_nil("#{e.class.name.split('::').last}: #{e.message}")
|
|
202
|
-
end
|
|
203
|
-
|
|
204
|
-
# @param data [Hash] a parsed +/props+ body
|
|
205
|
-
# @return [Integer, nil] the launched +n_ctx+ when present and
|
|
206
|
-
# positive, else +nil+
|
|
207
|
-
def positive_n_ctx(data)
|
|
208
|
-
n_ctx = data.dig('default_generation_settings', 'n_ctx')
|
|
209
|
-
n_ctx if n_ctx.is_a?(Integer) && n_ctx.positive?
|
|
210
|
-
end
|
|
211
|
-
|
|
212
|
-
def model_id_present?
|
|
213
|
-
!@model_id.nil? && !@model_id.empty?
|
|
214
|
-
end
|
|
215
|
-
|
|
216
|
-
def warn_and_nil(reason)
|
|
217
|
-
LOGGER.warn("llama.cpp /props probe failed: #{reason}")
|
|
218
|
-
nil
|
|
219
|
-
end
|
|
220
|
-
end
|
|
221
|
-
end
|
|
222
|
-
end
|
|
@@ -1,111 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
module Pikuri
|
|
4
|
-
class Agent
|
|
5
|
-
module Control
|
|
6
|
-
# Caps the number of tool calls per {Agent#run_loop}
|
|
7
|
-
# invocation. ruby_llm has no built-in step budget; the
|
|
8
|
-
# +Agent+ pokes {#tick!} on every +before_tool_call+
|
|
9
|
-
# callback and {#reset!} at the start of each turn. Once the
|
|
10
|
-
# counter exceeds the configured cap, {#tick!} raises
|
|
11
|
-
# {Exceeded} and the +Agent+ applies the {#on_exhausted}
|
|
12
|
-
# policy: re-raise to the host (the default), or run the
|
|
13
|
-
# step-exhaustion synthesizer to salvage a partial answer.
|
|
14
|
-
#
|
|
15
|
-
# == Why the policy lives here, not on +Agent+
|
|
16
|
-
#
|
|
17
|
-
# Synthesis can only ever fire off a tripped step limit, so
|
|
18
|
-
# an +Agent.new(synthesize: ...)+ kwarg would be meaningless
|
|
19
|
-
# whenever +step_limit:+ is +nil+ — an invalid combination
|
|
20
|
-
# the API would have to document away. Attaching the policy
|
|
21
|
-
# to the budget makes "what happens when the budget runs
|
|
22
|
-
# out" travel with the budget, and the nonsense state is
|
|
23
|
-
# unrepresentable. The host picks per wiring: a Q&A REPL
|
|
24
|
-
# wants +:synthesize+ (salvage an answer from the evidence
|
|
25
|
-
# gathered so far); a coding agent wants the default
|
|
26
|
-
# +:raise+ (a tools-free pass can't finish writing code —
|
|
27
|
-
# stop, let the user say "continue"; {#reset!} at the next
|
|
28
|
-
# turn boundary refreshes the budget).
|
|
29
|
-
class StepLimit
|
|
30
|
-
# Valid {#on_exhausted} policies.
|
|
31
|
-
ON_EXHAUSTED = %i[raise synthesize].freeze
|
|
32
|
-
# Raised by {#tick!} once tool-call count exceeds +max+.
|
|
33
|
-
# Carries the budget that was tripped so rescue clauses
|
|
34
|
-
# can include it in user-facing messages.
|
|
35
|
-
class Exceeded < StandardError
|
|
36
|
-
# @return [Integer]
|
|
37
|
-
attr_reader :max_steps
|
|
38
|
-
|
|
39
|
-
# @param max_steps [Integer]
|
|
40
|
-
def initialize(max_steps)
|
|
41
|
-
@max_steps = max_steps
|
|
42
|
-
super("Agent loop exceeded #{max_steps} steps")
|
|
43
|
-
end
|
|
44
|
-
end
|
|
45
|
-
|
|
46
|
-
# @return [Integer] the configured cap
|
|
47
|
-
attr_reader :max
|
|
48
|
-
|
|
49
|
-
# @return [Symbol] what {Agent#run_loop} does when this
|
|
50
|
-
# budget trips: +:raise+ lets {Exceeded} propagate to the
|
|
51
|
-
# host; +:synthesize+ runs the tools-free synthesizer
|
|
52
|
-
# rescue. See the class header for how to pick.
|
|
53
|
-
attr_reader :on_exhausted
|
|
54
|
-
|
|
55
|
-
# @param max [Integer] hard cap on tool-call rounds; must
|
|
56
|
-
# be positive
|
|
57
|
-
# @param on_exhausted [Symbol] +:raise+ (default) or
|
|
58
|
-
# +:synthesize+ — see {#on_exhausted}
|
|
59
|
-
# @raise [ArgumentError] if +max+ is zero or negative, or
|
|
60
|
-
# +on_exhausted+ is not one of {ON_EXHAUSTED}
|
|
61
|
-
def initialize(max:, on_exhausted: :raise)
|
|
62
|
-
raise ArgumentError, "max must be positive, got #{max}" if max <= 0
|
|
63
|
-
raise ArgumentError, "on_exhausted must be one of #{ON_EXHAUSTED.inspect}, got #{on_exhausted.inspect}" \
|
|
64
|
-
unless ON_EXHAUSTED.include?(on_exhausted)
|
|
65
|
-
|
|
66
|
-
@max = max
|
|
67
|
-
@on_exhausted = on_exhausted
|
|
68
|
-
@step = 0
|
|
69
|
-
end
|
|
70
|
-
|
|
71
|
-
# Increment the tool-call counter; raise {Exceeded} once
|
|
72
|
-
# it crosses {#max}. Called by {Agent} from its
|
|
73
|
-
# +before_tool_call+ wiring.
|
|
74
|
-
#
|
|
75
|
-
# @return [void]
|
|
76
|
-
# @raise [Exceeded] when the counter has now exceeded
|
|
77
|
-
# {#max}
|
|
78
|
-
def tick!
|
|
79
|
-
@step += 1
|
|
80
|
-
raise Exceeded, @max if @step > @max
|
|
81
|
-
end
|
|
82
|
-
|
|
83
|
-
# Reset the counter back to zero. Called by {Agent} at the
|
|
84
|
-
# start of each turn (in {Agent#run_loop} before forwarding
|
|
85
|
-
# the user message to the chat) so the same instance can
|
|
86
|
-
# govern many turns across a long-running REPL. Mid-loop
|
|
87
|
-
# {Control::Interloper} injections deliberately do *not*
|
|
88
|
-
# trigger a reset — those are additional context for the
|
|
89
|
-
# same turn, not a fresh one, and a chatty user could
|
|
90
|
-
# otherwise refresh the budget forever by injecting.
|
|
91
|
-
#
|
|
92
|
-
# @return [void]
|
|
93
|
-
def reset!
|
|
94
|
-
@step = 0
|
|
95
|
-
end
|
|
96
|
-
|
|
97
|
-
# @return [Integer] current step count; exposed so callers
|
|
98
|
-
# can introspect it (and so tests can assert it)
|
|
99
|
-
attr_reader :step
|
|
100
|
-
|
|
101
|
-
# @return [String] short config dump for {Agent#to_s}.
|
|
102
|
-
# The policy only renders when it's the non-default
|
|
103
|
-
# +:synthesize+, so existing banner output is unchanged.
|
|
104
|
-
def to_s
|
|
105
|
-
policy = @on_exhausted == :raise ? '' : ", on_exhausted=#{@on_exhausted}"
|
|
106
|
-
"StepLimit(max=#{@max}#{policy})"
|
|
107
|
-
end
|
|
108
|
-
end
|
|
109
|
-
end
|
|
110
|
-
end
|
|
111
|
-
end
|
|
@@ -1,147 +0,0 @@
|
|
|
1
|
-
# frozen_string_literal: true
|
|
2
|
-
|
|
3
|
-
module Pikuri
|
|
4
|
-
class Agent
|
|
5
|
-
# Capability facade handed to {Extension#bind} and
|
|
6
|
-
# {Extension#on_user_message} — the runtime counterpart of
|
|
7
|
-
# {Configurator}. Where the Configurator collects *build-time*
|
|
8
|
-
# declarations (tools, listeners, prompt snippets), this object
|
|
9
|
-
# grants the *runtime* capabilities an extension needs once the
|
|
10
|
-
# agent is fully wired: emitting domain events onto the listener
|
|
11
|
-
# stream, registering raw per-agent tools, and deriving sub-agent
|
|
12
|
-
# listener lists.
|
|
13
|
-
#
|
|
14
|
-
# == Why a handed object, not a getter on Agent
|
|
15
|
-
#
|
|
16
|
-
# The {Agent} deliberately exposes NO public path to these
|
|
17
|
-
# capabilities — no +listeners+ reader, no +chat+ reader, no
|
|
18
|
-
# emit method. Holding an agent reference grants read access to
|
|
19
|
-
# its configuration ({Agent#tools}, {Agent#transport}, ...) and
|
|
20
|
-
# nothing more; the write capabilities live here, and the only
|
|
21
|
-
# way to obtain this object is to be an {Extension} receiving a
|
|
22
|
-
# +bind+ / +on_user_message+ call (or to be handed it onward by
|
|
23
|
-
# one, e.g. {Pikuri::SubAgent::SubAgentTool} and
|
|
24
|
-
# {Pikuri::Mcp::Servers::Connect} both capture the context their
|
|
25
|
-
# extension's +bind+ received). Capabilities flow by explicit
|
|
26
|
-
# handoff, never by fetching from a globally reachable object.
|
|
27
|
-
#
|
|
28
|
-
# The usual Ruby caveat applies: nothing here is mechanically
|
|
29
|
-
# sealed (+instance_variable_get+ exists). The boundary is the
|
|
30
|
-
# API contract — same as every seam in CLAUDE.md.
|
|
31
|
-
#
|
|
32
|
-
# == Boundary rule
|
|
33
|
-
#
|
|
34
|
-
# Operations that *act on* the live agent's wiring live here.
|
|
35
|
-
# Passive readers of constructor-given config (+transport+,
|
|
36
|
-
# +id+, +streaming+, +tools+, +cancellable+, ...) stay on
|
|
37
|
-
# {Agent}, reachable via {#agent}. Don't move readers in; don't
|
|
38
|
-
# add capabilities to Agent.
|
|
39
|
-
#
|
|
40
|
-
# == Audit
|
|
41
|
-
#
|
|
42
|
-
# One context per agent, constructed by {Agent#initialize} right
|
|
43
|
-
# before the extension +bind+ sweep. {ListenerList#emit} has
|
|
44
|
-
# exactly two callers: {Agent} (loop narration) and this class
|
|
45
|
-
# (extension domain events). The roster of capability users is
|
|
46
|
-
# +grep -rn 'emit_event\|add_raw_tool\|sub_agent_listeners'
|
|
47
|
-
# pikuri-*/lib/+.
|
|
48
|
-
class ExtensionContext
|
|
49
|
-
# @param agent [Agent] the live, fully wired agent.
|
|
50
|
-
# @param chat [RubyLLM::Chat] the agent's underlying chat —
|
|
51
|
-
# target of {#add_raw_tool}.
|
|
52
|
-
# @param listeners [ListenerList] the agent's listener list —
|
|
53
|
-
# target of {#emit_event} / {#sub_agent_listeners}.
|
|
54
|
-
# @param on_close_sink [Array<Proc>] the agent's live
|
|
55
|
-
# +@on_close_handlers+ array, which {#on_close} appends to —
|
|
56
|
-
# same live-sink shape as {Configurator}'s +on_close_sink:+.
|
|
57
|
-
def initialize(agent:, chat:, listeners:, on_close_sink:)
|
|
58
|
-
@agent = agent
|
|
59
|
-
@chat = chat
|
|
60
|
-
@listeners = listeners
|
|
61
|
-
@on_close_handlers = on_close_sink
|
|
62
|
-
end
|
|
63
|
-
|
|
64
|
-
# @return [Agent] the live agent, for read access to its
|
|
65
|
-
# configuration (tools, transport, id, streaming, ...).
|
|
66
|
-
attr_reader :agent
|
|
67
|
-
|
|
68
|
-
# Emit a domain event onto the agent's listener stream.
|
|
69
|
-
#
|
|
70
|
-
# Core {Event} variants narrate the chat loop and are emitted
|
|
71
|
-
# by {Agent} alone; gems define their own variants (e.g.
|
|
72
|
-
# +Pikuri::Tasks::ListChanged+) in their own namespace and
|
|
73
|
-
# emit them here. Listeners must no-op on variants they don't
|
|
74
|
-
# recognize — {Listener::Base#on_event}'s default and
|
|
75
|
-
# +case+-fallthrough give that for free.
|
|
76
|
-
#
|
|
77
|
-
# Called on the agent's thread (typically from inside a tool's
|
|
78
|
-
# +execute+, where the event lands between {Event::ToolCall}
|
|
79
|
-
# and {Event::ToolResult} in the stream). Listeners doing
|
|
80
|
-
# cross-thread handoff snapshot/serialize inside +on_event+.
|
|
81
|
-
#
|
|
82
|
-
# @param event [Object] an immutable event value (by
|
|
83
|
-
# convention a +Data+ instance).
|
|
84
|
-
# @return [void]
|
|
85
|
-
def emit_event(event)
|
|
86
|
-
@listeners.emit(event)
|
|
87
|
-
nil
|
|
88
|
-
end
|
|
89
|
-
|
|
90
|
-
# Register a raw +RubyLLM::Tool+ subclass on the agent's
|
|
91
|
-
# underlying chat, bypassing the {Pikuri::Tool}
|
|
92
|
-
# strict-validation seam — hence "raw": native pikuri tools
|
|
93
|
-
# should go through {Pikuri::Tool} (registered at build time
|
|
94
|
-
# via {Configurator#add_tool}) so they get {Tool::Parameters}
|
|
95
|
-
# validation and the LLM-actionable +"Error: ..."+ contract.
|
|
96
|
-
# Intended callers: {Pikuri::Mcp::Servers} (MCP tools
|
|
97
|
-
# deliberately bypass — see IDEAS.md §"MCP tools bypass
|
|
98
|
-
# +Pikuri::Tool+ entirely") and
|
|
99
|
-
# {Pikuri::SubAgent::Extension} (the +agent+ tool must
|
|
100
|
-
# register after the parent's tool list is final).
|
|
101
|
-
#
|
|
102
|
-
# The added tool does NOT enter {Agent#tools}, only the chat's
|
|
103
|
-
# tool list. Sub-agents therefore cannot snapshot it — which
|
|
104
|
-
# is the whole point: activation is strictly per-agent, see
|
|
105
|
-
# IDEAS.md §"Per-agent activation, no propagation".
|
|
106
|
-
#
|
|
107
|
-
# @param ruby_llm_tool [Class] subclass of +RubyLLM::Tool+
|
|
108
|
-
# @return [void]
|
|
109
|
-
def add_raw_tool(ruby_llm_tool)
|
|
110
|
-
@chat.with_tool(ruby_llm_tool)
|
|
111
|
-
nil
|
|
112
|
-
end
|
|
113
|
-
|
|
114
|
-
# Derive a listener list for a spawned sub-agent via
|
|
115
|
-
# {ListenerList#for_sub_agent}. Sole intended caller:
|
|
116
|
-
# {Pikuri::SubAgent::SubAgentTool}, once per spawn.
|
|
117
|
-
#
|
|
118
|
-
# The derived list deliberately aliases the parent's listener
|
|
119
|
-
# *instances* where a listener opts to share by reference
|
|
120
|
-
# (stateful sinks like {Listener::InMemoryEventList}) — see
|
|
121
|
-
# {ListenerList#for_sub_agent} for the per-listener semantics.
|
|
122
|
-
#
|
|
123
|
-
# @param params [Hash{Symbol => Object}] forwarded to each
|
|
124
|
-
# listener's +for_sub_agent+ hook (currently +id:+).
|
|
125
|
-
# @return [ListenerList]
|
|
126
|
-
def sub_agent_listeners(**params)
|
|
127
|
-
@listeners.for_sub_agent(**params)
|
|
128
|
-
end
|
|
129
|
-
|
|
130
|
-
# Register a handler called by {Agent#close}. Symmetric to
|
|
131
|
-
# {Configurator#on_close} — same LIFO + per-handler-rescue +
|
|
132
|
-
# idempotent semantics — but available post-construction, so
|
|
133
|
-
# an {Extension}'s +bind+ can install per-agent cleanup keyed
|
|
134
|
-
# to this specific agent (e.g. +Pikuri::Memory::Extension+
|
|
135
|
-
# arms its recorder's bounded flush here).
|
|
136
|
-
#
|
|
137
|
-
# @yield called with no arguments at close time
|
|
138
|
-
# @return [void]
|
|
139
|
-
def on_close(&blk)
|
|
140
|
-
raise ArgumentError, 'on_close requires a block' unless block_given?
|
|
141
|
-
|
|
142
|
-
@on_close_handlers << blk
|
|
143
|
-
nil
|
|
144
|
-
end
|
|
145
|
-
end
|
|
146
|
-
end
|
|
147
|
-
end
|