praxo-core 0.2.0 → 0.3.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: 502bce398e33748c87f2943e8815ca97e790aa2cc294fbf81d1ecd5cbd82e742
4
- data.tar.gz: 5b062bf089d542f73f77cef34ba8a023450023782fd32f9be6aba1ecf244575c
3
+ metadata.gz: 6b5277a84676a585ae272a89166d4cf957c2d295ae65ce17e469f8b406c1c9b6
4
+ data.tar.gz: 196c814209b547fdc344f692f2b8eb721c7c934f60a8f213ad846d22feca3242
5
5
  SHA512:
6
- metadata.gz: 5544e44f1881d0116dab1e92ae17bf5294111165a1f001b6b132f67f9be840e1837a2c6a03400546ab295e9c0e7106bed6f21be81d7ef038262efd161c0be407
7
- data.tar.gz: 9da94d37f066d0ae549366c3f09efd3e283c4167264639a84f15662d7b04a53de8c673efe93c24ca05ae5d1764a4f64874aecef0740ec343523cef9e25b21023
6
+ metadata.gz: 5c3d00bbb7ebe5e62fbce729af6fb9fb756ef7cac79d6a3625bfd18edbd368e5990cdd213828cd07a42ac5da98da9430f0f536470cf8c377c47bf4a7233b2113
7
+ data.tar.gz: a3facc141b9639e06bc0ecca22f672496c56def5834dd52a98b00c928bf9e8c2a2e30d2255302ce6be3bdb616820e24df4499e8f1e46919b20d4ac0c53041c6b
data/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 AxisVela
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AxisVela
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md CHANGED
@@ -1,74 +1,92 @@
1
- # PRAXO-CORE Ruby Core
2
-
3
- PRAXO-CORE is an embeddable, MIT-licensed agent framework. This gem is its
4
- native Ruby Core: an agent loop with tool registration and dispatch, policy
5
- hooks, typed events, memory, checkpoints, context budgets, middleware, JSON
6
- Schema validation, and plugin manifest parsing.
7
-
8
- The normative contract is [`spec/`](../../spec/README.md); Go remains the
9
- reference implementation.
10
-
11
- - `SPEC_VERSION`: `0.2.0`
12
- - Core version: `0.2.0`
13
- - Tier: core
14
- - License: MIT
15
- - Dependencies: Ruby standard library only
16
- - The latest RubyGems package is `praxo-core@0.1.0`; `0.2.0` is a source release
17
-
18
- ## Install
19
-
20
- ```bash
21
- gem install praxo-core
22
- ```
23
-
24
- ## Scope
25
-
26
- The Core implements all eleven vector groups: toolcall, JSON Schema, plugin,
27
- memory, event, stream, checkpoint, policy, context, middleware, and the agent
28
- loop. It includes a public API snapshot and a dependency-free test runner.
29
-
30
- ## Build and test
31
-
32
- ```bash
33
- ruby language/ruby/conformance/run.rb
34
- ruby language/ruby/api-snapshot.rb --check
35
- ruby language/ruby/tests/run.rb
36
- ```
37
-
38
- ## Quickstart
39
-
40
- ```ruby
41
- $LOAD_PATH.unshift('language/ruby/lib')
42
- require 'praxo'
43
-
44
- model = Praxo::Agent::StaticModel.new('hello')
45
- options = Praxo::Agent::AgentOptions.new(model)
46
- result = Praxo::Agent.run_agent(
47
- options,
48
- Praxo::Models.session(id: 'demo'),
49
- 'hello'
50
- )
51
- puts result.output
52
- ```
53
-
54
- Tools register on the options object:
55
-
56
- ```ruby
57
- registry = Praxo::Agent::ToolRegistry.new
58
- registry.register(Praxo::Agent::FuncTool.new('echo', 'Echo arguments',
59
- ->(arguments) { arguments }))
60
- options.tools = registry
61
- options.max_steps = 8
62
- ```
63
-
64
- ## Layout
65
-
66
- - `lib/praxo/` package source.
67
- - `conformance/run.rb` vector runner.
68
- - `api-snapshot.rb` and `api/` public API snapshot.
69
- - `tests/run.rb` test suite.
70
-
71
- ## Release
72
-
73
- Tag shape: `ruby/v0.2.0`. The tag targets `SPEC_VERSION` `0.2.0`. See
74
- [CHANGELOG.md](CHANGELOG.md) for per-release changes and compatibility notes.
1
+ # PRAXO-CORE Ruby Core
2
+
3
+ PRAXO-CORE is an embeddable, MIT-licensed agent framework. This gem is its
4
+ native Ruby Core: an agent loop with tool registration and dispatch, policy
5
+ hooks, typed events, memory, checkpoints, context budgets, middleware, JSON
6
+ Schema validation, and plugin manifest parsing.
7
+
8
+ The normative contract is [`spec/`](../../spec/README.md); Go remains the
9
+ reference implementation.
10
+
11
+ - `SPEC_VERSION`: `0.2.0`
12
+ - Core version: `0.3.0`
13
+ - Tier: core
14
+ - License: MIT
15
+ - Dependencies: Ruby standard library only
16
+ - The latest RubyGems package is `praxo-core@0.1.0`; `0.3.0` is a source release
17
+
18
+ ## Install
19
+
20
+ ```bash
21
+ gem install praxo-core
22
+ ```
23
+
24
+ ## Scope
25
+
26
+ The Core implements all eleven vector groups: toolcall, JSON Schema, plugin,
27
+ memory, event, stream, checkpoint, policy, context, middleware, and the agent
28
+ loop. It includes a public API snapshot and a dependency-free test runner.
29
+
30
+ ## Build and test
31
+
32
+ ```bash
33
+ ruby language/ruby/conformance/run.rb
34
+ ruby language/ruby/api-snapshot.rb --check
35
+ ruby language/ruby/tests/run.rb
36
+ ```
37
+
38
+ ## Quickstart
39
+
40
+ ```ruby
41
+ $LOAD_PATH.unshift('language/ruby/lib')
42
+ require 'praxo'
43
+
44
+ model = Praxo::Agent::StaticModel.new('hello')
45
+ options = Praxo::Agent::AgentOptions.new(model)
46
+ result = Praxo::Agent.run_agent(
47
+ options,
48
+ Praxo::Models.session(id: 'demo'),
49
+ 'hello'
50
+ )
51
+ puts result.output
52
+ ```
53
+
54
+ Tools register on the options object:
55
+
56
+ ```ruby
57
+ registry = Praxo::Agent::ToolRegistry.new
58
+ registry.register(Praxo::Agent::FuncTool.new('echo', 'Echo arguments',
59
+ ->(arguments) { arguments }))
60
+ options.tools = registry
61
+ options.max_steps = 8
62
+ ```
63
+
64
+ ## Agent options
65
+
66
+ `AgentOptions` supports cancellation, stream callbacks, bounded parallel tool
67
+ execution, and run-scoped call limits:
68
+
69
+ - `cancellation` accepts a proc or an object responding to `cancelled?`. The
70
+ runner checks it before model work and before and after each tool.
71
+ - `on_stream` receives `Models::StreamPart` values for `values` and `messages`.
72
+ A callback error aborts the run and runs after-run cleanup.
73
+ - `max_parallel_tools` starts tool invocations in threads within each batch while
74
+ preserving result order. Tool implementations remain responsible for their own
75
+ thread safety.
76
+ - `Middleware::CallLimit` keeps counters per run ID, so independent runs do not
77
+ share limits.
78
+
79
+ `Praxo::SSE.parse` parses OpenAI-compatible server-sent-event text and raises
80
+ `MODEL_STREAM` for truncated streams or malformed half packets.
81
+
82
+ ## Layout
83
+
84
+ - `lib/praxo/` package source.
85
+ - `conformance/run.rb` vector runner.
86
+ - `api-snapshot.rb` and `api/` public API snapshot.
87
+ - `tests/run.rb` test suite.
88
+
89
+ ## Release
90
+
91
+ Tag shape: `ruby/v0.3.0`. The tag targets `SPEC_VERSION` `0.2.0`. See
92
+ [CHANGELOG.md](CHANGELOG.md) for per-release changes and compatibility notes.
data/api/0.3.0.txt ADDED
@@ -0,0 +1,119 @@
1
+ # PRAXO-CORE Ruby API 0.3.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 FuncTool
11
+ class MemoryStore
12
+ class MultiSink
13
+ class PathChecker
14
+ class PiiRedactor
15
+ class Runner
16
+ class StaticModel
17
+ class StructuredOutput
18
+ class ToolRegistry
19
+ class ToolSelection
20
+ def action
21
+ def after_run
22
+ def allowed?
23
+ def allows?
24
+ def apply
25
+ def array
26
+ def as_int
27
+ def as_object
28
+ def as_string
29
+ def authorize
30
+ def before_model
31
+ def before_run
32
+ def before_tool
33
+ def bool
34
+ def check
35
+ def check_cancelled
36
+ def check_enum
37
+ def check_keys
38
+ def compact
39
+ def content_block
40
+ def decision
41
+ def emit
42
+ def emit_stream
43
+ def equals
44
+ def error
45
+ def error_code
46
+ def estimate_tokens
47
+ def event
48
+ def execute_tool
49
+ def extract_json
50
+ def fallback_model
51
+ def filter
52
+ def generate
53
+ def get
54
+ def has?
55
+ def initialize
56
+ def int
57
+ def invoke
58
+ def invoke_tool
59
+ def invoke_tools
60
+ def marshal
61
+ def memory_record
62
+ def message
63
+ def message_assistant
64
+ def message_text
65
+ def message_tool
66
+ def message_wire
67
+ def parse
68
+ def parse_input_json
69
+ def parse_json_call
70
+ def parse_manifest
71
+ def parse_plain
72
+ def parse_tag
73
+ def parse_toolcall
74
+ def parse_xml
75
+ def plus
76
+ def prepare_tool
77
+ def put
78
+ def redact
79
+ def redact_value
80
+ def register
81
+ def reject
82
+ def request
83
+ def resolve_path
84
+ def response
85
+ def run
86
+ def run_agent
87
+ def run_result
88
+ def search
89
+ def session
90
+ def specs
91
+ def stream_part
92
+ def string
93
+ def stringify
94
+ def strip_markup
95
+ def structured_apply
96
+ def text_present
97
+ def tool_call
98
+ def tool_spec
99
+ def truncate_to_tokens
100
+ def unmarshal
101
+ def usage
102
+ def validate
103
+ def visit
104
+ def visit_array
105
+ def visit_boolean
106
+ def visit_number
107
+ def visit_object
108
+ def visit_string
109
+ def within?
110
+ module Agent
111
+ module Json
112
+ module JsonSchema
113
+ module Middleware
114
+ module Models
115
+ module Plugin
116
+ module Praxo
117
+ module Runtime
118
+ module SSE
119
+ module Toolcall
data/lib/praxo/agent.rb CHANGED
@@ -54,7 +54,8 @@ module Praxo
54
54
  class AgentOptions
55
55
  attr_accessor :model, :tools, :events, :policy, :system_prompt, :context,
56
56
  :max_steps, :max_tokens, :tool_choice, :middleware,
57
- :allowed_tools
57
+ :allowed_tools, :cancellation, :on_stream,
58
+ :max_parallel_tools
58
59
 
59
60
  def initialize(model)
60
61
  @model = model
@@ -68,6 +69,9 @@ module Praxo
68
69
  @tool_choice = nil
69
70
  @middleware = []
70
71
  @allowed_tools = []
72
+ @cancellation = nil
73
+ @on_stream = nil
74
+ @max_parallel_tools = 1
71
75
  end
72
76
  end
73
77
 
@@ -94,9 +98,14 @@ module Praxo
94
98
  raise
95
99
  end
96
100
  emit(options, 'run.started', session.id, run_id)
101
+ emit_stream(options, Models.stream_part(
102
+ run_id: run_id, session_id: session.id, kind: 'values',
103
+ step: 0, data: prompt.to_s
104
+ ))
97
105
  after_run_invoked = false
98
106
  begin
99
107
  (1..max_steps).each do |step|
108
+ check_cancelled(options)
100
109
  authorize(options, Models.action(kind: 'model.generate', session_id: session.id))
101
110
  if options.context
102
111
  compacted, ok = options.context.compact(messages)
@@ -109,6 +118,7 @@ module Praxo
109
118
  tool_choice: options.tool_choice
110
119
  )
111
120
  response = options.model.generate(request)
121
+ check_cancelled(options)
112
122
  usage = usage.plus(response.usage || Models.usage)
113
123
  total = usage.input_tokens.to_i + usage.output_tokens.to_i
114
124
  if options.max_tokens.to_i.positive? && total > options.max_tokens
@@ -122,15 +132,17 @@ module Praxo
122
132
  run_id: run_id, output: message.content.to_s, steps: step,
123
133
  usage: usage
124
134
  )
135
+ emit_stream(options, Models.stream_part(
136
+ run_id: run_id, session_id: session.id, kind: 'messages',
137
+ step: step, data: message.content.to_s
138
+ ))
125
139
  after_run_invoked = true
126
140
  cleanup_error = after_run(options, entered, result, nil)
127
141
  raise cleanup_error if cleanup_error
128
142
  emit(options, 'run.completed', session.id, run_id)
129
143
  return result
130
144
  end
131
- calls.each do |call|
132
- messages << invoke_tool(options, call, run_id, session.id)
133
- end
145
+ messages.concat(invoke_tools(options, calls, run_id, session.id))
134
146
  end
135
147
  Praxo.error('AGENT_MAX_STEPS', 'maximum steps')
136
148
  rescue StandardError => e
@@ -142,7 +154,45 @@ module Praxo
142
154
 
143
155
  private
144
156
 
157
+ def invoke_tools(options, calls, run_id, session_id)
158
+ limit = [options.max_parallel_tools.to_i, 1].max
159
+ results = []
160
+ calls.each_slice(limit) do |batch|
161
+ check_cancelled(options)
162
+ prepared = batch.map do |call|
163
+ prepare_tool(options, call, run_id, session_id)
164
+ end
165
+ if limit <= 1
166
+ prepared.each do |tool, call|
167
+ results << execute_tool(tool, call)
168
+ check_cancelled(options)
169
+ end
170
+ else
171
+ outcomes = prepared.map do |tool, call|
172
+ Thread.new do
173
+ begin
174
+ [:ok, execute_tool(tool, call)]
175
+ rescue StandardError => caught
176
+ [:error, caught]
177
+ end
178
+ end
179
+ end.map(&:value)
180
+ outcomes.each do |status, payload|
181
+ raise payload if status == :error
182
+ results << payload
183
+ end
184
+ check_cancelled(options)
185
+ end
186
+ end
187
+ results
188
+ end
189
+
145
190
  def invoke_tool(options, call, run_id, session_id)
191
+ tool, prepared = prepare_tool(options, call, run_id, session_id)
192
+ execute_tool(tool, prepared)
193
+ end
194
+
195
+ def prepare_tool(options, call, run_id, session_id)
146
196
  original_name = call.name
147
197
  original_arguments = call.arguments
148
198
  unless allowed?(options, original_name)
@@ -169,10 +219,31 @@ module Praxo
169
219
  tool = options.tools.get(call.name)
170
220
  emit(options, 'tool.call', session_id, run_id,
171
221
  { 'name' => call.name, 'arguments' => call.arguments || {} })
222
+ [tool, call]
223
+ end
224
+
225
+ def execute_tool(tool, call)
172
226
  value = tool.invoke(call.arguments || {})
173
227
  Models.message_tool(Json.stringify(value), call.id.to_s)
174
228
  end
175
229
 
230
+ def check_cancelled(options)
231
+ return unless options.cancellation
232
+ cancelled = if options.cancellation.respond_to?(:cancelled?)
233
+ options.cancellation.cancelled?
234
+ elsif options.cancellation.respond_to?(:call)
235
+ options.cancellation.call
236
+ else
237
+ options.cancellation
238
+ end
239
+ Praxo.error('AGENT_CANCELLED', 'run cancelled') if cancelled
240
+ end
241
+
242
+ def emit_stream(options, part)
243
+ return unless options.on_stream
244
+ options.on_stream.call(part)
245
+ end
246
+
176
247
  def allowed?(options, name)
177
248
  options.allowed_tools.empty? || options.allowed_tools.include?(name)
178
249
  end
data/lib/praxo/errors.rb CHANGED
@@ -1,18 +1,18 @@
1
- module Praxo
2
- class Error < StandardError
3
- attr_reader :code
4
-
5
- def initialize(code, message)
6
- @code = code
7
- super(message)
8
- end
9
- end
10
-
11
- def self.error(code, message)
12
- raise Error.new(code, message)
13
- end
14
-
15
- def self.error_code(error)
16
- error.is_a?(Error) ? error.code : ''
17
- end
18
- end
1
+ module Praxo
2
+ class Error < StandardError
3
+ attr_reader :code
4
+
5
+ def initialize(code, message)
6
+ @code = code
7
+ super(message)
8
+ end
9
+ end
10
+
11
+ def self.error(code, message)
12
+ raise Error.new(code, message)
13
+ end
14
+
15
+ def self.error_code(error)
16
+ error.is_a?(Error) ? error.code : ''
17
+ end
18
+ end
data/lib/praxo/json.rb CHANGED
@@ -1,47 +1,47 @@
1
- require 'json'
2
-
3
- module Praxo
4
- module Json
5
- module_function
6
-
7
- def parse(text)
8
- JSON.parse(text)
9
- end
10
-
11
- def stringify(value)
12
- JSON.generate(value)
13
- end
14
-
15
- def get(node, key)
16
- node.is_a?(Hash) ? node[key] : nil
17
- end
18
-
19
- def has?(node, key)
20
- node.is_a?(Hash) && node.key?(key)
21
- end
22
-
23
- def string(node, key)
24
- value = get(node, key)
25
- value.is_a?(String) ? value : nil
26
- end
27
-
28
- def bool(node, key, fallback = false)
29
- value = get(node, key)
30
- value == true || value == false ? value : fallback
31
- end
32
-
33
- def int(node, key, fallback = 0)
34
- value = get(node, key)
35
- value.is_a?(Numeric) ? value.to_i : fallback
36
- end
37
-
38
- def array(node, key)
39
- value = get(node, key)
40
- value.is_a?(Array) ? value : []
41
- end
42
-
43
- def equals(left, right)
44
- left == right
45
- end
46
- end
47
- end
1
+ require 'json'
2
+
3
+ module Praxo
4
+ module Json
5
+ module_function
6
+
7
+ def parse(text)
8
+ JSON.parse(text)
9
+ end
10
+
11
+ def stringify(value)
12
+ JSON.generate(value)
13
+ end
14
+
15
+ def get(node, key)
16
+ node.is_a?(Hash) ? node[key] : nil
17
+ end
18
+
19
+ def has?(node, key)
20
+ node.is_a?(Hash) && node.key?(key)
21
+ end
22
+
23
+ def string(node, key)
24
+ value = get(node, key)
25
+ value.is_a?(String) ? value : nil
26
+ end
27
+
28
+ def bool(node, key, fallback = false)
29
+ value = get(node, key)
30
+ value == true || value == false ? value : fallback
31
+ end
32
+
33
+ def int(node, key, fallback = 0)
34
+ value = get(node, key)
35
+ value.is_a?(Numeric) ? value.to_i : fallback
36
+ end
37
+
38
+ def array(node, key)
39
+ value = get(node, key)
40
+ value.is_a?(Array) ? value : []
41
+ end
42
+
43
+ def equals(left, right)
44
+ left == right
45
+ end
46
+ end
47
+ end