praxo-core 0.8.2 → 0.9.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2511d9120f9fdcf0969637cbd95a035fa4cba3c975ddd4241228072c0947c810
4
- data.tar.gz: 71654456f560e5a7e8f9634fffa0a564ecc60c1d31ceb400769acaa74964e382
3
+ metadata.gz: d7c1a76fc89240c8c0c1f0cc941de493594d39e9c76fc6258db5f79d81ebd4fe
4
+ data.tar.gz: 48cc44eff38c98873c610c172291144f6d97b69fd781475feddfba28affae1bf
5
5
  SHA512:
6
- metadata.gz: e7f654ee7aa6ff2c8f982b5320b53d831e5d0f5178c61c68418b173edc2254a7e1425c5e80e7d8865f91f922b2ccbd02492a4516a9da8c5ec5bbe8acb6ba2d90
7
- data.tar.gz: 79019fffde0873e05e655a99dc8dfbfea16cb671591fe1b03300c1afe0ffd51dfd8bf1c1e37c2094c51b66eb624e98539b7d46d3b622a6dfda5a1eff7aea0c87
6
+ metadata.gz: e2fdc217fe0a677c92253016bbb50e7f34a25fa1f5e131584aaac5f5554c602e6a6a9855cedf71259d3be04cbbee3df8ec533fbf01ea9bade17bb0619333438c
7
+ data.tar.gz: 5f21f6f8ffdcaccfa6e82c033c23dc2ee81b6f22d6cbb02b3be3eba533f00a9c4b89146c4573b964948325d2b13f2a22405ca91454f8247af30276b9576af70f
data/README.md CHANGED
@@ -26,7 +26,7 @@ reference implementation.
26
26
  - Machine-readable entry: [llms.txt](https://github.com/axisvela/praxo-core/blob/main/language/ruby/llms.txt) and [llms.md](https://github.com/axisvela/praxo-core/blob/main/language/ruby/llms.md)
27
27
  - [Examples](https://github.com/axisvela/praxo-core/tree/main/language/ruby/examples): runnable language-specific examples.
28
28
  - Coding-agent contract: [docs/getting-started/coding-agents.md](https://github.com/axisvela/praxo-core/blob/main/docs/getting-started/coding-agents.md)
29
- - Registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.8.1)
29
+ - Registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.8.2)
30
30
  - Community: [X](https://x.com/axisvela) · [Weibo](https://weibo.com/u/1936025761)
31
31
 
32
32
  ## Get started
@@ -130,12 +130,16 @@ execution, and run-scoped call limits:
130
130
 
131
131
  `Praxo::SSE.parse` parses OpenAI-compatible server-sent-event text and raises
132
132
  `MODEL_STREAM` for truncated streams or malformed half packets.
133
+ `Praxo::SSE.parse_response` additionally reassembles fragmented tool calls,
134
+ usage, and `finish_reason`; `OpenAICompatible#generate_stream` uses it with an
135
+ injected `stream_transport` or the built-in HTTP path. Set `on_delta` on the
136
+ agent options to use streaming.
133
137
 
134
138
  ## Model Adapters
135
139
 
136
140
  - `Praxo::Adapters::OpenAICompatible` for OpenAI, DeepSeek, Kimi/Moonshot, and
137
141
  other OpenAI-compatible endpoints.
138
- - `Praxo::Adapters::Anthropic` for the Anthropic Messages API.
142
+ - `Praxo::Adapters::Anthropic` for the Anthropic Messages API, including `generate_stream` SSE reassembly.
139
143
  - `Praxo::Adapters::Gemini` for the Gemini generateContent API.
140
144
 
141
145
  Each adapter accepts a `transport` lambda for deterministic tests.
@@ -166,6 +170,11 @@ status and a bounded body. The sink adds no authentication, retries, buffering,
166
170
  ordering, or exactly-once delivery. Use HTTPS and filter sensitive event data
167
171
  before emitting.
168
172
 
173
+ ## Process plugin host
174
+
175
+ `Praxo::PluginProcessHost` speaks the framework JSON-Lines process plugin
176
+ protocol with token authentication, health handshake, invocation timeout,
177
+ cooperative cancel, and typed call errors.
169
178
  ## Layout
170
179
 
171
180
  - `lib/praxo/` package source.
@@ -175,5 +184,5 @@ before emitting.
175
184
 
176
185
  ## Release
177
186
 
178
- Tag shape: `ruby/v0.8.2`. The tag targets `SPEC_VERSION` `0.2.0`. See
187
+ Tag shape: `ruby/v0.9.0`. The tag targets `SPEC_VERSION` `0.2.0`. See
179
188
  [CHANGELOG.md](CHANGELOG.md) for per-release changes and compatibility notes.
data/REGISTRY.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # PRAXO-CORE Ruby Registry Introduction
2
2
 
3
- **Status:** published; split source repository. Source version `0.8.2`, source
4
- tag `ruby/v0.8.2`. Published registry version: `0.8.1`. Registry
3
+ **Status:** published; split source repository. Source version `0.9.0`, source
4
+ tag `ruby/v0.9.0`. Published registry version: `0.8.2`. Registry
5
5
  pages are release snapshots; verify the published version before relying on a
6
6
  feature.
7
7
 
@@ -9,19 +9,17 @@ feature.
9
9
 
10
10
  PRAXO-CORE is an embeddable, MIT-licensed agent framework. This gem is its native Ruby Core: an agent loop with tool registration and dispatch, policy hooks, typed events, memory, checkpoints, context budgets, middleware, JSON Schema validation, and plugin manifest parsing.
11
11
 
12
- Use it when an existing Ruby application needs a governed model/tool loop without adding a sidecar in another language. It is not an HTTP user agent, crawler, hosted agent service, or model provider.
13
-
14
12
  ## Package
15
13
 
16
14
  | Field | Value |
17
15
  | --- | --- |
18
16
  | Package | `praxo-core` |
19
- | Registry | [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.8.1) |
20
- | Source version | `0.8.2` |
21
- | Published registry version | `0.8.1` |
17
+ | Registry | [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.8.2) |
18
+ | Source version | `0.9.0` |
19
+ | Published registry version | `0.8.2` |
22
20
  | Install (published) | `gem install praxo-core` |
23
21
  | Install (source/release prepared) | `gem install praxo-core` |
24
- | Source tag | `ruby/v0.8.2` |
22
+ | Source tag | `ruby/v0.9.0` |
25
23
  | Tier | Core |
26
24
  | Contract | `SPEC_VERSION` `0.2.0` |
27
25
  | Documentation | https://axisvela.github.io/praxo-core/languages/ruby/ |
@@ -30,9 +28,9 @@ Use it when an existing Ruby application needs a governed model/tool loop withou
30
28
 
31
29
  | Adapter | Status | Detail |
32
30
  | --- | --- | --- |
33
- | OpenAI-compatible model | native | `Praxo::Adapters::OpenAICompatible` |
34
- | Anthropic model | native | `Praxo::Adapters::Anthropic`; injectable transport |
35
- | Gemini model | native | `Praxo::Adapters::Gemini`; injectable transport |
31
+ | OpenAI-compatible model | native | `Praxo::Adapters::OpenAICompatible`; `generate_stream` reassembles SSE content, tool calls, usage, and finish reason |
32
+ | Anthropic model | native | `Praxo::Adapters::Anthropic`; injectable transport; `generate_stream` reassembles Anthropic SSE |
33
+ | Gemini model | native | `Praxo::Adapters::Gemini`; injectable transport; `generate_stream` reassembles Gemini SSE |
36
34
  | MCP client | native | `Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26 |
37
35
  | Harmovela sink | native | `Praxo::Adapters::HarmovelaSink` |
38
36
  | OpenTelemetry sink | native (transport seam) | `OtelSink`; caller supplies OTLP/HTTP transport |
data/api/0.8.2.txt CHANGED
@@ -13,6 +13,9 @@ class MemoryStore
13
13
  class MultiSink
14
14
  class PathChecker
15
15
  class PiiRedactor
16
+ class PluginCallError
17
+ class PluginProcessConfig
18
+ class PluginProcessHost
16
19
  class Runner
17
20
  class StaticModel
18
21
  class StructuredOutput
@@ -20,6 +23,7 @@ class SubagentManager
20
23
  class ToolRegistry
21
24
  class ToolSelection
22
25
  def action
26
+ def active?
23
27
  def after_run
24
28
  def allowed?
25
29
  def allows?
@@ -34,6 +38,7 @@ def before_model
34
38
  def before_run
35
39
  def before_tool
36
40
  def bool
41
+ def call
37
42
  def cancel
38
43
  def check
39
44
  def check_cancelled
@@ -78,6 +83,7 @@ def parse_input_json
78
83
  def parse_json_call
79
84
  def parse_manifest
80
85
  def parse_plain
86
+ def parse_response
81
87
  def parse_tag
82
88
  def parse_toolcall
83
89
  def parse_xml
@@ -96,14 +102,19 @@ def run
96
102
  def run_agent
97
103
  def run_result
98
104
  def search
105
+ def send_cancel
99
106
  def session
100
107
  def set
101
108
  def specs
109
+ def start
110
+ def stderr_text
111
+ def stop
102
112
  def stream_part
103
113
  def string
104
114
  def stringify
105
115
  def strip_markup
106
116
  def structured_apply
117
+ def terminate
107
118
  def text_present
108
119
  def timestamp
109
120
  def to_wire
data/api/0.9.0.txt ADDED
@@ -0,0 +1,146 @@
1
+ # PRAXO-CORE Ruby API 0.9.0
2
+ # SPEC_VERSION 0.2.0
3
+
4
+ class AgentOptions
5
+ class CallLimit
6
+ class CheckpointAllowlist
7
+ class ContextBudget
8
+ class Error
9
+ class FilterSink
10
+ class FuncRetriever
11
+ class FuncTool
12
+ class MemoryStore
13
+ class MultiSink
14
+ class PathChecker
15
+ class PiiRedactor
16
+ class PluginCallError
17
+ class PluginProcessConfig
18
+ class PluginProcessHost
19
+ class Runner
20
+ class StaticModel
21
+ class StructuredOutput
22
+ class SubagentManager
23
+ class ToolRegistry
24
+ class ToolSelection
25
+ def action
26
+ def active?
27
+ def after_run
28
+ def allowed?
29
+ def allows?
30
+ def apply
31
+ def apply_interrupt
32
+ def array
33
+ def as_int
34
+ def as_object
35
+ def as_string
36
+ def authorize
37
+ def before_model
38
+ def before_run
39
+ def before_tool
40
+ def bool
41
+ def call
42
+ def cancel
43
+ def check
44
+ def check_cancelled
45
+ def check_enum
46
+ def check_keys
47
+ def compact
48
+ def content_block
49
+ def copy
50
+ def decision
51
+ def emit
52
+ def emit_stream
53
+ def equals
54
+ def error
55
+ def error_code
56
+ def estimate_tokens
57
+ def event
58
+ def execute
59
+ def execute_tool
60
+ def extract_json
61
+ def fallback_model
62
+ def filter
63
+ def generate
64
+ def get
65
+ def has?
66
+ def initialize
67
+ def int
68
+ def interrupt
69
+ def interrupt_decision
70
+ def invoke
71
+ def invoke_tool
72
+ def invoke_tools
73
+ def launch
74
+ def marshal
75
+ def memory_record
76
+ def message
77
+ def message_assistant
78
+ def message_text
79
+ def message_tool
80
+ def message_wire
81
+ def parse
82
+ def parse_input_json
83
+ def parse_json_call
84
+ def parse_manifest
85
+ def parse_plain
86
+ def parse_response
87
+ def parse_tag
88
+ def parse_toolcall
89
+ def parse_xml
90
+ def plus
91
+ def prepare_tool
92
+ def put
93
+ def redact
94
+ def redact_value
95
+ def register
96
+ def reject
97
+ def request
98
+ def resolve_path
99
+ def response
100
+ def retrieve
101
+ def run
102
+ def run_agent
103
+ def run_result
104
+ def search
105
+ def send_cancel
106
+ def session
107
+ def set
108
+ def specs
109
+ def start
110
+ def stderr_text
111
+ def stop
112
+ def stream_part
113
+ def string
114
+ def stringify
115
+ def strip_markup
116
+ def structured_apply
117
+ def terminate
118
+ def text_present
119
+ def timestamp
120
+ def to_wire
121
+ def tool_call
122
+ def tool_spec
123
+ def truncate_to_tokens
124
+ def unmarshal
125
+ def update
126
+ def usage
127
+ def validate
128
+ def visit
129
+ def visit_array
130
+ def visit_boolean
131
+ def visit_number
132
+ def visit_object
133
+ def visit_string
134
+ def wait
135
+ def within?
136
+ module Agent
137
+ module Delegation
138
+ module Json
139
+ module JsonSchema
140
+ module Middleware
141
+ module Models
142
+ module Plugin
143
+ module Praxo
144
+ module Runtime
145
+ module SSE
146
+ module Toolcall
@@ -12,16 +12,26 @@ module Praxo
12
12
  DEFAULT_VERSION = '2023-06-01'
13
13
 
14
14
  def initialize(base_url: DEFAULT_BASE_URL, model:, api_key: nil, version: DEFAULT_VERSION,
15
- max_tokens: 1024, transport: nil, timeout: 60)
15
+ max_tokens: 1024, transport: nil, stream_transport: nil, timeout: 60)
16
16
  @base_url = base_url.to_s.sub(%r{/$}, '')
17
17
  @model = model
18
18
  @api_key = api_key
19
19
  @version = version
20
20
  @max_tokens = max_tokens
21
21
  @transport = transport
22
+ @stream_transport = stream_transport
22
23
  @timeout = timeout
23
24
  end
24
25
 
26
+ def generate_stream(request, on_delta)
27
+ Praxo.error('MODEL_CONFIG', 'anthropic: API key is required') unless @api_key && !@api_key.empty?
28
+ Praxo.error('MODEL_CONFIG', 'anthropic: model is required') unless @model && !@model.empty?
29
+
30
+ payload = build_payload(request, true)
31
+ text = @stream_transport ? @stream_transport.call('/v1/messages', payload) : post_stream(payload)
32
+ parse_stream(text, on_delta)
33
+ end
34
+
25
35
  def generate(request)
26
36
  Praxo.error('MODEL_CONFIG', 'anthropic: API key is required') unless @api_key && !@api_key.empty?
27
37
  Praxo.error('MODEL_CONFIG', 'anthropic: model is required') unless @model && !@model.empty?
@@ -33,7 +43,7 @@ module Praxo
33
43
 
34
44
  private
35
45
 
36
- def build_payload(request)
46
+ def build_payload(request, stream = false)
37
47
  system, messages = build_messages(request.messages)
38
48
  payload = {
39
49
  model: @model,
@@ -54,6 +64,7 @@ module Praxo
54
64
  payload[:tool_choice] = choice if choice
55
65
  end
56
66
  payload[:temperature] = request.temperature if request.temperature
67
+ payload[:stream] = true if stream
57
68
  payload
58
69
  end
59
70
 
@@ -115,6 +126,89 @@ module Praxo
115
126
  end
116
127
  end
117
128
 
129
+ def parse_stream(text, on_delta)
130
+ content = +''
131
+ calls = {}
132
+ input_tokens = 0
133
+ output_tokens = 0
134
+ cached_tokens = 0
135
+ stop_reason = nil
136
+ stopped = false
137
+ text.to_s.each_line do |raw|
138
+ line = raw.strip
139
+ next unless line.start_with?('data:')
140
+ chunk = line[5..].to_s.strip
141
+ next if chunk.empty?
142
+ event = begin
143
+ Json.parse(chunk)
144
+ rescue StandardError
145
+ Praxo.error('MODEL_STREAM', 'anthropic: invalid stream chunk')
146
+ end
147
+ next unless event.is_a?(Hash)
148
+
149
+ case event['type']
150
+ when 'message_start'
151
+ usage = (event['message'] || {})['usage'] || {}
152
+ input_tokens = usage['input_tokens'].to_i
153
+ cached_tokens = usage['cache_read_input_tokens'].to_i
154
+ when 'content_block_start'
155
+ index = event['index'].to_i
156
+ block = event['content_block'] || {}
157
+ if block['type'] == 'tool_use'
158
+ calls[index] = { id: block['id'].to_s, name: block['name'].to_s, arguments: +'' }
159
+ end
160
+ when 'content_block_delta'
161
+ index = event['index'].to_i
162
+ delta = event['delta'] || {}
163
+ case delta['type']
164
+ when 'text_delta'
165
+ piece = delta['text'].to_s
166
+ unless piece.empty?
167
+ content << piece
168
+ on_delta.call(piece)
169
+ end
170
+ when 'input_json_delta'
171
+ if calls[index]
172
+ calls[index][:arguments] << delta['partial_json'].to_s
173
+ end
174
+ end
175
+ when 'message_delta'
176
+ stop_reason = (event['delta'] || {})['stop_reason'] || stop_reason
177
+ output_tokens = (event['usage'] || {})['output_tokens'] || output_tokens
178
+ when 'message_stop'
179
+ stopped = true
180
+ when 'error'
181
+ Praxo.error('MODEL_STREAM', 'anthropic: stream error')
182
+ end
183
+ end
184
+ Praxo.error('MODEL_STREAM', 'anthropic: stream ended before completion') unless stopped || stop_reason
185
+ tool_calls = calls.keys.sort.filter_map do |index|
186
+ call = calls[index]
187
+ next if call[:name].empty?
188
+
189
+ arguments = {}
190
+ unless call[:arguments].empty?
191
+ begin
192
+ arguments = Json.parse(call[:arguments])
193
+ rescue StandardError
194
+ Praxo.error('PROVIDER_JSON', 'anthropic: invalid tool arguments')
195
+ end
196
+ unless arguments.is_a?(Hash)
197
+ Praxo.error('PROVIDER_JSON', 'anthropic: invalid tool arguments')
198
+ end
199
+ end
200
+ Models.tool_call(id: call[:id], name: call[:name], arguments: arguments)
201
+ end
202
+ result = Models.response(
203
+ message: Models.message(role: Models::ASSISTANT, content: content,
204
+ tool_calls: tool_calls),
205
+ usage: Models.usage(input_tokens: input_tokens, output_tokens: output_tokens)
206
+ )
207
+ result.usage.cached_tokens = cached_tokens if result.usage.respond_to?(:cached_tokens=)
208
+ result.finish_reason = stop_reason if result.respond_to?(:finish_reason=)
209
+ result
210
+ end
211
+
118
212
  def parse_response(data)
119
213
  Praxo.error('MODEL_HTTP', "anthropic: #{data['error']['message']}") if data['error']
120
214
 
@@ -148,6 +242,27 @@ module Praxo
148
242
  )
149
243
  end
150
244
 
245
+ def post_stream(payload)
246
+ uri = URI.join(@base_url + '/', 'v1/messages')
247
+ request = Net::HTTP::Post.new(uri)
248
+ request['Content-Type'] = 'application/json'
249
+ request['Accept'] = 'text/event-stream'
250
+ request['x-api-key'] = @api_key if @api_key
251
+ request['anthropic-version'] = @version
252
+ request.body = Json.stringify(payload)
253
+ response = Net::HTTP.start(
254
+ uri.host,
255
+ uri.port,
256
+ use_ssl: uri.scheme == 'https',
257
+ read_timeout: @timeout
258
+ ) { |http| http.request(request) }
259
+ body = response.body.to_s
260
+ unless response.is_a?(Net::HTTPSuccess)
261
+ Praxo.error('PROVIDER_HTTP', "provider returned HTTP #{response.code}: #{body}")
262
+ end
263
+ body
264
+ end
265
+
151
266
  def post(payload)
152
267
  uri = URI.join(@base_url + '/', 'v1/messages')
153
268
  request = Net::HTTP::Post.new(uri)
@@ -10,12 +10,14 @@ module Praxo
10
10
  DEFAULT_BASE_URL = 'https://generativelanguage.googleapis.com'
11
11
 
12
12
  def initialize(base_url: DEFAULT_BASE_URL, model:, api_key: nil,
13
- max_output_tokens: 0, transport: nil, timeout: 60)
13
+ max_output_tokens: 0, transport: nil, stream_transport: nil,
14
+ timeout: 60)
14
15
  @base_url = base_url.to_s.sub(%r{/$}, '')
15
16
  @model = model
16
17
  @api_key = api_key
17
18
  @max_output_tokens = max_output_tokens
18
19
  @transport = transport
20
+ @stream_transport = stream_transport
19
21
  @timeout = timeout
20
22
  end
21
23
 
@@ -29,6 +31,20 @@ module Praxo
29
31
  parse_response(data)
30
32
  end
31
33
 
34
+ def generate_stream(request, on_delta)
35
+ Praxo.error('MODEL_CONFIG', 'gemini: API key is required') unless @api_key && !@api_key.empty?
36
+ Praxo.error('MODEL_CONFIG', 'gemini: model is required') unless @model && !@model.empty?
37
+
38
+ payload = build_payload(request)
39
+ path = "/v1beta/models/#{URI.encode_www_form_component(@model)}:streamGenerateContent?alt=sse"
40
+ text = if @stream_transport
41
+ @stream_transport.call(path, payload)
42
+ else
43
+ post_stream(path, payload)
44
+ end
45
+ parse_stream(text, on_delta)
46
+ end
47
+
32
48
  private
33
49
 
34
50
  def build_payload(request)
@@ -156,6 +172,83 @@ module Praxo
156
172
  )
157
173
  end
158
174
 
175
+ def parse_stream(text, on_delta)
176
+ content = +''
177
+ calls = []
178
+ input_tokens = 0
179
+ output_tokens = 0
180
+ cached_tokens = 0
181
+ finish_reason = nil
182
+ text.to_s.each_line do |raw|
183
+ line = raw.strip
184
+ next unless line.start_with?('data:')
185
+
186
+ chunk_text = line[5..].to_s.strip
187
+ next if chunk_text.empty? || chunk_text == '[DONE]'
188
+
189
+ chunk = Json.parse(chunk_text)
190
+ Praxo.error('MODEL_STREAM', "gemini: #{chunk.dig('error', 'message') || 'stream error'}") if chunk['error']
191
+
192
+ usage = chunk['usageMetadata'] || {}
193
+ input_tokens = usage['promptTokenCount'] if usage['promptTokenCount']
194
+ output_tokens = usage['candidatesTokenCount'] if usage['candidatesTokenCount']
195
+ cached_tokens = usage['cachedContentTokenCount'] if usage['cachedContentTokenCount']
196
+
197
+ candidate = Array(chunk['candidates']).first
198
+ next unless candidate
199
+
200
+ finish_reason = candidate['finishReason'] if candidate['finishReason']
201
+ Array((candidate['content'] || {})['parts']).each do |part|
202
+ piece = part['text'].to_s
203
+ if !piece.empty?
204
+ content << piece
205
+ on_delta.call(piece)
206
+ end
207
+ call = part['functionCall']
208
+ next unless call
209
+
210
+ calls << Models.tool_call(
211
+ id: "call-#{calls.length + 1}",
212
+ name: call['name'] || '',
213
+ arguments: call['args'] || {}
214
+ )
215
+ end
216
+ end
217
+ Models.response(
218
+ message: Models.message(
219
+ role: Models::ASSISTANT,
220
+ content: content,
221
+ tool_calls: calls
222
+ ),
223
+ usage: Models.usage(
224
+ input_tokens: input_tokens.to_i,
225
+ output_tokens: output_tokens.to_i,
226
+ cached_tokens: cached_tokens.to_i
227
+ ),
228
+ finish_reason: finish_reason
229
+ )
230
+ end
231
+
232
+ def post_stream(path, payload)
233
+ uri = URI.join(@base_url + '/', path.sub(%r{^/}, ''))
234
+ request = Net::HTTP::Post.new(uri)
235
+ request['Content-Type'] = 'application/json'
236
+ request['Accept'] = 'text/event-stream'
237
+ request['x-goog-api-key'] = @api_key
238
+ request.body = Json.stringify(payload)
239
+ response = Net::HTTP.start(
240
+ uri.host,
241
+ uri.port,
242
+ use_ssl: uri.scheme == 'https',
243
+ read_timeout: @timeout
244
+ ) { |http| http.request(request) }
245
+ body = response.body.to_s
246
+ unless response.is_a?(Net::HTTPSuccess)
247
+ Praxo.error('PROVIDER_HTTP', "provider returned HTTP #{response.code}: #{body}")
248
+ end
249
+ body
250
+ end
251
+
159
252
  def post(path, payload)
160
253
  uri = URI.join(@base_url + '/', path.sub(%r{^/}, ''))
161
254
  request = Net::HTTP::Post.new(uri)
@@ -3,6 +3,7 @@ require 'uri'
3
3
  require_relative '../models'
4
4
  require_relative '../json'
5
5
  require_relative '../errors'
6
+ require_relative '../sse'
6
7
 
7
8
  module Praxo
8
9
  module Adapters
@@ -11,11 +12,13 @@ module Praxo
11
12
  # transport is injectable for deterministic tests:
12
13
  # ->(path, payload) { parsed_response_hash }
13
14
  class OpenAICompatible
14
- def initialize(base_url:, model:, api_key: nil, transport: nil, timeout: 60)
15
+ def initialize(base_url:, model:, api_key: nil, transport: nil,
16
+ stream_transport: nil, timeout: 60)
15
17
  @base_url = base_url.to_s.sub(%r{/$}, '')
16
18
  @model = model
17
19
  @api_key = api_key
18
20
  @transport = transport
21
+ @stream_transport = stream_transport
19
22
  @timeout = timeout
20
23
  end
21
24
 
@@ -25,6 +28,12 @@ module Praxo
25
28
  parse_response(data)
26
29
  end
27
30
 
31
+ def generate_stream(request, on_delta)
32
+ payload = build_payload(request).merge(stream: true)
33
+ text = @stream_transport ? @stream_transport.call('/chat/completions', payload) : post_stream('/chat/completions', payload)
34
+ SSE.parse_response(text, on_delta)
35
+ end
36
+
28
37
  private
29
38
 
30
39
  def build_payload(request)
@@ -116,6 +125,26 @@ module Praxo
116
125
  end
117
126
  Json.parse(body)
118
127
  end
128
+
129
+ def post_stream(path, payload)
130
+ uri = URI.join(@base_url + '/', path.sub(%r{^/}, ''))
131
+ request = Net::HTTP::Post.new(uri)
132
+ request['Content-Type'] = 'application/json'
133
+ request['Accept'] = 'text/event-stream'
134
+ request['Authorization'] = "Bearer #{@api_key}" if @api_key
135
+ request.body = Json.stringify(payload)
136
+ response = Net::HTTP.start(
137
+ uri.host,
138
+ uri.port,
139
+ use_ssl: uri.scheme == 'https',
140
+ read_timeout: @timeout
141
+ ) { |http| http.request(request) }
142
+ body = response.body.to_s
143
+ unless response.is_a?(Net::HTTPSuccess)
144
+ Praxo.error('PROVIDER_HTTP', "provider returned HTTP #{response.code}: #{body}")
145
+ end
146
+ body
147
+ end
119
148
  end
120
149
  end
121
150
  end
data/lib/praxo/agent.rb CHANGED
@@ -74,7 +74,7 @@ module Praxo
74
74
  class AgentOptions
75
75
  attr_accessor :model, :tools, :events, :policy, :system_prompt, :context,
76
76
  :max_steps, :max_tokens, :tool_choice, :middleware,
77
- :allowed_tools, :cancellation, :on_stream,
77
+ :allowed_tools, :cancellation, :on_delta, :on_stream,
78
78
  :max_parallel_tools, :interrupt_on, :on_interrupt_decision,
79
79
  :on_interrupt, :require_policy, :require_tool_scope
80
80
 
@@ -91,6 +91,7 @@ module Praxo
91
91
  @middleware = []
92
92
  @allowed_tools = []
93
93
  @cancellation = nil
94
+ @on_delta = nil
94
95
  @on_stream = nil
95
96
  @max_parallel_tools = 1
96
97
  @interrupt_on = []
@@ -151,7 +152,11 @@ module Praxo
151
152
  tools: options.tools ? options.tools.specs : [],
152
153
  tool_choice: options.tool_choice
153
154
  )
154
- response = options.model.generate(request)
155
+ response = if options.on_delta && options.model.respond_to?(:generate_stream)
156
+ options.model.generate_stream(request, options.on_delta)
157
+ else
158
+ options.model.generate(request)
159
+ end
155
160
  check_cancelled(options)
156
161
  usage = usage.plus(response.usage || Models.usage)
157
162
  total = usage.input_tokens.to_i + usage.output_tokens.to_i
@@ -0,0 +1,220 @@
1
+ require 'base64'
2
+ require 'json'
3
+ require 'open3'
4
+ require 'securerandom'
5
+ require 'timeout'
6
+
7
+ require_relative 'errors'
8
+
9
+ module Praxo
10
+ class PluginCallError < StandardError
11
+ CODES = %w[
12
+ CAPABILITY_DENIED NOT_ACTIVE NOT_FOUND INVALID_REQUEST TIMEOUT INTERNAL CANCELED
13
+ ].freeze
14
+
15
+ attr_reader :code
16
+
17
+ def initialize(code, message = '')
18
+ @code = CODES.include?(code) ? code : 'INTERNAL'
19
+ super(message.empty? ? code : message)
20
+ end
21
+ end
22
+
23
+ class PluginProcessConfig
24
+ attr_accessor :plugin_id, :path, :args, :dir, :env, :token, :token_env_var,
25
+ :start_timeout, :invoke_timeout, :grace_period, :max_frame
26
+
27
+ def initialize(plugin_id:, path:, args: [], dir: nil, env: nil, token: '',
28
+ token_env_var: 'PRAXOVELA_PLUGIN_TOKEN',
29
+ start_timeout: 10.0, invoke_timeout: 30.0, grace_period: 5.0,
30
+ max_frame: 8 << 20)
31
+ @plugin_id = plugin_id
32
+ @path = path
33
+ @args = args
34
+ @dir = dir
35
+ @env = env
36
+ @token = token
37
+ @token_env_var = token_env_var
38
+ @start_timeout = start_timeout
39
+ @invoke_timeout = invoke_timeout
40
+ @grace_period = grace_period
41
+ @max_frame = max_frame
42
+ end
43
+ end
44
+
45
+ class PluginProcessHost
46
+ PROTOCOL_VERSION = 1
47
+ CONTROL_SERVICE = 'host.control'
48
+ HEALTH_METHOD = 'health'
49
+ SHUTDOWN_METHOD = 'shutdown'
50
+ CANCEL_METHOD = 'cancel'
51
+
52
+ attr_reader :config, :plugin_id
53
+
54
+ def initialize(config)
55
+ raise ArgumentError, 'plugin: PluginID is required' if config.plugin_id.to_s.empty?
56
+ raise ArgumentError, 'plugin: path is required' if config.path.to_s.empty?
57
+
58
+ @config = config
59
+ @plugin_id = config.plugin_id
60
+ @token = config.token.to_s.empty? ? SecureRandom.hex(32) : config.token
61
+ @seq = 0
62
+ @active = false
63
+ @stderr = +''
64
+ @responses = Queue.new
65
+ end
66
+
67
+ def active?
68
+ @active
69
+ end
70
+
71
+ def stderr_text
72
+ @stderr.dup
73
+ end
74
+
75
+ def start
76
+ raise 'plugin: host already started' if @process
77
+
78
+ environment = (config.env || ENV.to_h).merge(config.token_env_var => @token)
79
+ options = {}
80
+ options[:chdir] = config.dir if config.dir
81
+ @stdin, @stdout, @stderr_io, @wait = Open3.popen3(
82
+ environment, config.path, *config.args, **options
83
+ )
84
+ @process = @wait
85
+ @reader = Thread.new do
86
+ begin
87
+ @stdout.each_line do |line|
88
+ @responses << line.strip
89
+ end
90
+ rescue IOError
91
+ nil
92
+ ensure
93
+ @responses << nil
94
+ end
95
+ end
96
+ @stderr_reader = Thread.new do
97
+ begin
98
+ @stderr_io.each_line do |line|
99
+ @stderr << line if @stderr.length < (16 << 10)
100
+ end
101
+ rescue IOError
102
+ nil
103
+ end
104
+ end
105
+ call(CONTROL_SERVICE, HEALTH_METHOD, '', config.start_timeout)
106
+ @active = true
107
+ rescue StandardError
108
+ terminate
109
+ raise
110
+ end
111
+
112
+ def invoke(service, method, payload = '', timeout = nil)
113
+ raise PluginCallError.new('NOT_ACTIVE', 'plugin: host is not active') unless @active
114
+
115
+ call(service, method, payload, timeout || config.invoke_timeout)
116
+ end
117
+
118
+ def stop
119
+ return unless @process
120
+
121
+ begin
122
+ call(CONTROL_SERVICE, SHUTDOWN_METHOD, '', config.grace_period) if @active
123
+ rescue StandardError
124
+ nil
125
+ end
126
+ @active = false
127
+ begin
128
+ Timeout.timeout(config.grace_period) { @wait.value }
129
+ rescue Timeout::Error
130
+ terminate
131
+ end
132
+ @process = nil
133
+ @stdin = @stdout = @stderr_io = @wait = nil
134
+ @reader&.kill
135
+ @stderr_reader&.kill
136
+ end
137
+
138
+ private
139
+
140
+ def call(service, method, payload, timeout)
141
+ @seq += 1
142
+ id = "req-#{@seq}"
143
+ frame = {
144
+ 'id' => id,
145
+ 'version' => PROTOCOL_VERSION,
146
+ 'plugin_id' => config.plugin_id,
147
+ 'service' => service,
148
+ 'method' => method,
149
+ 'token' => @token,
150
+ 'payload' => Base64.strict_encode64(payload.to_s)
151
+ }
152
+ encoded = "#{JSON.generate(frame)}\n"
153
+ raise PluginCallError.new('INVALID_REQUEST', 'plugin: request frame too large') if encoded.bytesize > config.max_frame
154
+
155
+ @stdin.write(encoded)
156
+ @stdin.flush
157
+ deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
158
+ loop do
159
+ remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
160
+ if remaining <= 0
161
+ send_cancel(id)
162
+ terminate
163
+ raise PluginCallError.new('TIMEOUT', 'plugin: invocation timed out')
164
+ end
165
+ begin
166
+ line = Timeout.timeout(remaining) { @responses.pop }
167
+ rescue Timeout::Error
168
+ send_cancel(id)
169
+ terminate
170
+ raise PluginCallError.new('TIMEOUT', 'plugin: invocation timed out')
171
+ end
172
+ if line.nil?
173
+ detail = stderr_text
174
+ terminate
175
+ raise PluginCallError.new('INTERNAL', detail.empty? ? 'plugin: process exited' : detail[0, 512])
176
+ end
177
+ response = begin
178
+ JSON.parse(line)
179
+ rescue JSON::ParserError
180
+ next
181
+ end
182
+ next unless response['id'] == id
183
+
184
+ unless response['ok'] == true
185
+ raise PluginCallError.new(response['code'] || 'INTERNAL', response['message'] || '')
186
+ end
187
+ begin
188
+ return Base64.strict_decode64(response['payload'] || '')
189
+ rescue ArgumentError
190
+ raise PluginCallError.new('INTERNAL', 'plugin: invalid payload')
191
+ end
192
+ end
193
+ end
194
+
195
+ def send_cancel(id)
196
+ frame = {
197
+ 'id' => id,
198
+ 'version' => PROTOCOL_VERSION,
199
+ 'plugin_id' => config.plugin_id,
200
+ 'service' => CONTROL_SERVICE,
201
+ 'method' => CANCEL_METHOD,
202
+ 'token' => @token
203
+ }
204
+ @stdin&.write("#{JSON.generate(frame)}\n")
205
+ @stdin&.flush
206
+ rescue StandardError
207
+ nil
208
+ end
209
+
210
+ def terminate
211
+ @active = false
212
+ begin
213
+ Process.kill('KILL', @wait.pid) if @wait
214
+ rescue StandardError
215
+ nil
216
+ end
217
+ [@stdin, @stdout, @stderr_io].each { |io| io&.close rescue nil }
218
+ end
219
+ end
220
+ end
data/lib/praxo/sse.rb CHANGED
@@ -5,6 +5,81 @@ module Praxo
5
5
  module SSE
6
6
  module_function
7
7
 
8
+ def parse_response(text, on_delta)
9
+ content = +''
10
+ done = false
11
+ finish = nil
12
+ input_tokens = 0
13
+ output_tokens = 0
14
+ calls = {}
15
+ text.to_s.each_line do |raw|
16
+ line = raw.strip
17
+ next unless line.start_with?('data:')
18
+ chunk = line[5..].to_s.strip
19
+ next if chunk.empty?
20
+ if chunk == '[DONE]'
21
+ done = true
22
+ break
23
+ end
24
+ begin
25
+ event = Json.parse(chunk)
26
+ rescue StandardError
27
+ Praxo.error('MODEL_STREAM', 'invalid SSE packet')
28
+ end
29
+ next unless event.is_a?(Hash)
30
+ usage = event['usage']
31
+ if usage.is_a?(Hash)
32
+ input_tokens = usage['prompt_tokens'].to_i
33
+ output_tokens = usage['completion_tokens'].to_i
34
+ end
35
+ (event['choices'] || []).each do |choice|
36
+ finish = choice['finish_reason'] if choice.key?('finish_reason') && !choice['finish_reason'].nil?
37
+ delta = choice['delta'] || {}
38
+ piece = delta['content']
39
+ if piece && !piece.empty?
40
+ content << piece
41
+ on_delta.call(piece)
42
+ end
43
+ Array(delta['tool_calls']).each do |item|
44
+ index = item['index'] || calls.size
45
+ slot = calls[index] ||= { id: +'', name: +'', arguments: +'' }
46
+ slot[:id] << item['id'].to_s if item['id']
47
+ function = item['function'] || {}
48
+ slot[:name] << function['name'].to_s if function['name']
49
+ slot[:arguments] << function['arguments'].to_s if function['arguments']
50
+ end
51
+ end
52
+ done = true if finish
53
+ end
54
+ Praxo.error('MODEL_STREAM', 'stream ended before completion') unless done
55
+ tool_calls = calls.keys.sort.filter_map do |key|
56
+ call = calls[key]
57
+ next if call[:name].empty?
58
+
59
+ arguments = {}
60
+ unless call[:arguments].empty?
61
+ begin
62
+ arguments = Json.parse(call[:arguments])
63
+ rescue StandardError
64
+ Praxo.error('PROVIDER_JSON', 'provider returned invalid tool arguments')
65
+ end
66
+ unless arguments.is_a?(Hash)
67
+ Praxo.error('PROVIDER_JSON', 'provider returned invalid tool arguments')
68
+ end
69
+ end
70
+ Models.tool_call(id: call[:id], name: call[:name], arguments: arguments)
71
+ end
72
+ Models.response(
73
+ message: Models.message(
74
+ role: Models::ASSISTANT,
75
+ content: content,
76
+ tool_calls: tool_calls
77
+ ),
78
+ usage: Models.usage(input_tokens: input_tokens, output_tokens: output_tokens),
79
+ finish_reason: finish
80
+ )
81
+ end
82
+
8
83
  def parse(text)
9
84
  content = +''
10
85
  done = false
data/lib/praxo.rb CHANGED
@@ -4,6 +4,7 @@ require_relative 'praxo/models'
4
4
  require_relative 'praxo/toolcall'
5
5
  require_relative 'praxo/jsonschema'
6
6
  require_relative 'praxo/plugin'
7
+ require_relative 'praxo/plugin_process'
7
8
  require_relative 'praxo/runtime'
8
9
  require_relative 'praxo/sse'
9
10
  require_relative 'praxo/middleware'
data/llms.md CHANGED
@@ -7,21 +7,21 @@
7
7
  ## Package
8
8
 
9
9
  - package: `praxo-core`
10
- - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.8.1)
11
- - source_version: `0.8.2`
12
- - published_version: `0.8.1`
10
+ - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.8.2)
11
+ - source_version: `0.9.0`
12
+ - published_version: `0.8.2`
13
13
  - install_published: `gem install praxo-core`
14
14
  - install_source: `gem install praxo-core`
15
- - source_tag: `ruby/v0.8.2`
15
+ - source_tag: `ruby/v0.9.0`
16
16
  - tier: Core
17
17
  - contract: `SPEC_VERSION` `0.2.0`
18
18
  - documentation: https://axisvela.github.io/praxo-core/languages/ruby/
19
19
 
20
20
  ## Capabilities and Status
21
21
 
22
- - OpenAI-compatible model: native (`Praxo::Adapters::OpenAICompatible`)
23
- - Anthropic model: native (`Praxo::Adapters::Anthropic`; injectable transport)
24
- - Gemini model: native (`Praxo::Adapters::Gemini`; injectable transport)
22
+ - OpenAI-compatible model: native (`Praxo::Adapters::OpenAICompatible`; `generate_stream` reassembles SSE content, tool calls, usage, and finish reason)
23
+ - Anthropic model: native (`Praxo::Adapters::Anthropic`; injectable transport; `generate_stream` reassembles Anthropic SSE)
24
+ - Gemini model: native (`Praxo::Adapters::Gemini`; injectable transport; `generate_stream` reassembles Gemini SSE)
25
25
  - MCP client: native (`Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26)
26
26
  - Harmovela sink: native (`Praxo::Adapters::HarmovelaSink`)
27
27
  - OpenTelemetry sink: native (transport seam) (`OtelSink`; caller supplies OTLP/HTTP transport)
@@ -44,8 +44,8 @@
44
44
 
45
45
  ## Boundaries
46
46
 
47
- - In-process framework; not an HTTP user agent, crawler, model provider, hosted
48
- service, workflow engine, identity provider, or safety controller.
47
+ - In-process framework; not a model provider, hosted service, workflow engine,
48
+ identity provider, or safety controller.
49
49
  - No exactly-once, sandbox-isolation, production-security, real-time, or
50
50
  physical-safety claim.
51
51
  - Registry pages are release snapshots. Verify the published version and read the
data/llms.txt CHANGED
@@ -7,21 +7,21 @@
7
7
  # Package
8
8
 
9
9
  - package: `praxo-core`
10
- - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.8.1)
11
- - source_version: `0.8.2`
12
- - published_version: `0.8.1`
10
+ - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.8.2)
11
+ - source_version: `0.9.0`
12
+ - published_version: `0.8.2`
13
13
  - install_published: `gem install praxo-core`
14
14
  - install_source: `gem install praxo-core`
15
- - source_tag: `ruby/v0.8.2`
15
+ - source_tag: `ruby/v0.9.0`
16
16
  - tier: Core
17
17
  - contract: `SPEC_VERSION` `0.2.0`
18
18
  - documentation: https://axisvela.github.io/praxo-core/languages/ruby/
19
19
 
20
20
  # Capabilities and Status
21
21
 
22
- - OpenAI-compatible model: native (`Praxo::Adapters::OpenAICompatible`)
23
- - Anthropic model: native (`Praxo::Adapters::Anthropic`; injectable transport)
24
- - Gemini model: native (`Praxo::Adapters::Gemini`; injectable transport)
22
+ - OpenAI-compatible model: native (`Praxo::Adapters::OpenAICompatible`; `generate_stream` reassembles SSE content, tool calls, usage, and finish reason)
23
+ - Anthropic model: native (`Praxo::Adapters::Anthropic`; injectable transport; `generate_stream` reassembles Anthropic SSE)
24
+ - Gemini model: native (`Praxo::Adapters::Gemini`; injectable transport; `generate_stream` reassembles Gemini SSE)
25
25
  - MCP client: native (`Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26)
26
26
  - Harmovela sink: native (`Praxo::Adapters::HarmovelaSink`)
27
27
  - OpenTelemetry sink: native (transport seam) (`OtelSink`; caller supplies OTLP/HTTP transport)
@@ -44,8 +44,8 @@
44
44
 
45
45
  # Boundaries
46
46
 
47
- - In-process framework; not an HTTP user agent, crawler, model provider, hosted
48
- service, workflow engine, identity provider, or safety controller.
47
+ - In-process framework; not a model provider, hosted service, workflow engine,
48
+ identity provider, or safety controller.
49
49
  - No exactly-once, sandbox-isolation, production-security, real-time, or
50
50
  physical-safety claim.
51
51
  - Registry pages are release snapshots. Verify the published version and read the
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: praxo-core
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.8.2
4
+ version: 0.9.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - AxisVela
@@ -31,6 +31,7 @@ files:
31
31
  - api/0.8.0.txt
32
32
  - api/0.8.1.txt
33
33
  - api/0.8.2.txt
34
+ - api/0.9.0.txt
34
35
  - lib/praxo.rb
35
36
  - lib/praxo/adapters/anthropic.rb
36
37
  - lib/praxo/adapters/gemini.rb
@@ -47,6 +48,7 @@ files:
47
48
  - lib/praxo/middleware.rb
48
49
  - lib/praxo/models.rb
49
50
  - lib/praxo/plugin.rb
51
+ - lib/praxo/plugin_process.rb
50
52
  - lib/praxo/retriever.rb
51
53
  - lib/praxo/runtime.rb
52
54
  - lib/praxo/sse.rb