praxo-core 0.6.0 → 0.7.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: 6e50f98ad5296f743956594ac18c6e4675c27aecc3ba8da8de988ac71c2b3925
4
- data.tar.gz: 2025d3d8b1ea545d9759034921c4387265f2ce734995b0fb883d94299819343d
3
+ metadata.gz: 6b720116e91a4927eacec6a64291d1f9d7ae845e6d1d3e2f55af7dfeb11a21bd
4
+ data.tar.gz: a4da48da732eb8cf41a303ad09a8d91d0ba0d17e4d6a57da1d2a9c7fe2bd1305
5
5
  SHA512:
6
- metadata.gz: 3d3879cf7f8e5cf9437568252cb31896c96890dcd83284febcf2c9dadb28d12da6e9ea50b939da2a35d67108b7b6dab21c34510a72eceb32b28fec9a84bcb700
7
- data.tar.gz: 70f2686e31b7d4dbdc7cfc8d2e93d9a1484ee76e2f460690a6e69a16570d88d70a3152703dc131990e067e6a1393940e81cb534ffb7c82e10a14a6e2edf48bc8
6
+ metadata.gz: 69c1fb1c50aaa2ca8adb3e55030a12f2563be7e974e0c92967e6cda12167803d945b83d6a1968c1be3eda23f0f17e7c3ccd17869a45149d2f5a6c456dad61880
7
+ data.tar.gz: c688bf1bbae8f98aa6a6890822213806203a20d77fedea103376b0dedb64c9d9a42bfc99eb8f7e628820a7cebd3c975056ee4eb9eec86d9321065a15f9840620
data/README.md CHANGED
@@ -132,5 +132,5 @@ before emitting.
132
132
 
133
133
  ## Release
134
134
 
135
- Tag shape: `ruby/v0.4.1`. The tag targets `SPEC_VERSION` `0.2.0`. See
135
+ Tag shape: `ruby/v0.7.0`. The tag targets `SPEC_VERSION` `0.2.0`. See
136
136
  [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.6.0`, source
4
- tag `ruby/v0.6.0`. Published registry version: `0.5.0`. Registry
3
+ **Status:** published; split source repository. Source version `0.7.0`, source
4
+ tag `ruby/v0.7.0`. Published registry version: `0.5.0`. Registry
5
5
  pages are release snapshots; verify the published version before relying on a
6
6
  feature.
7
7
 
@@ -15,15 +15,28 @@ PRAXO-CORE is an embeddable, MIT-licensed agent framework. This gem is its nativ
15
15
  | --- | --- |
16
16
  | Package | `praxo-core` |
17
17
  | Registry | [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.5.0) |
18
- | Source version | `0.6.0` |
18
+ | Source version | `0.7.0` |
19
19
  | Published registry version | `0.5.0` |
20
20
  | Install (published) | `gem install praxo-core` |
21
21
  | Install (source/release prepared) | `gem install praxo-core` |
22
- | Source tag | `ruby/v0.6.0` |
22
+ | Source tag | `ruby/v0.7.0` |
23
23
  | Tier | Core |
24
24
  | Contract | `SPEC_VERSION` `0.2.0` |
25
25
  | Documentation | https://axisvela.github.io/praxo-core/languages/ruby/ |
26
26
 
27
+ ## Capabilities and Status
28
+
29
+ | Adapter | Status | Detail |
30
+ | --- | --- | --- |
31
+ | OpenAI-compatible model | native | `Praxo::Adapters::OpenAICompatible` |
32
+ | Anthropic model | native | `Praxo::Adapters::Anthropic`; injectable transport |
33
+ | Gemini model | native | `Praxo::Adapters::Gemini`; injectable transport |
34
+ | MCP client | native | `Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26 |
35
+ | Harmovela sink | native | `Praxo::Adapters::HarmovelaSink` |
36
+ | OpenTelemetry sink | native (transport seam) | `OtelSink`; caller supplies OTLP/HTTP transport |
37
+ | Subagent delegation | native | `Delegation::SubagentManager` |
38
+ | Retriever | native | `Document`, `FuncRetriever` |
39
+
27
40
  ## Coding-agent entry
28
41
 
29
42
  - [llms.txt](llms.txt): compact machine-readable entry for this language.
data/api/0.7.0.txt ADDED
@@ -0,0 +1,135 @@
1
+ # PRAXO-CORE Ruby API 0.7.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 Runner
17
+ class StaticModel
18
+ class StructuredOutput
19
+ class SubagentManager
20
+ class ToolRegistry
21
+ class ToolSelection
22
+ def action
23
+ def after_run
24
+ def allowed?
25
+ def allows?
26
+ def apply
27
+ def apply_interrupt
28
+ def array
29
+ def as_int
30
+ def as_object
31
+ def as_string
32
+ def authorize
33
+ def before_model
34
+ def before_run
35
+ def before_tool
36
+ def bool
37
+ def cancel
38
+ def check
39
+ def check_cancelled
40
+ def check_enum
41
+ def check_keys
42
+ def compact
43
+ def content_block
44
+ def copy
45
+ def decision
46
+ def emit
47
+ def emit_stream
48
+ def equals
49
+ def error
50
+ def error_code
51
+ def estimate_tokens
52
+ def event
53
+ def execute
54
+ def execute_tool
55
+ def extract_json
56
+ def fallback_model
57
+ def filter
58
+ def generate
59
+ def get
60
+ def has?
61
+ def initialize
62
+ def int
63
+ def interrupt
64
+ def interrupt_decision
65
+ def invoke
66
+ def invoke_tool
67
+ def invoke_tools
68
+ def launch
69
+ def marshal
70
+ def memory_record
71
+ def message
72
+ def message_assistant
73
+ def message_text
74
+ def message_tool
75
+ def message_wire
76
+ def parse
77
+ def parse_input_json
78
+ def parse_json_call
79
+ def parse_manifest
80
+ def parse_plain
81
+ def parse_tag
82
+ def parse_toolcall
83
+ def parse_xml
84
+ def plus
85
+ def prepare_tool
86
+ def put
87
+ def redact
88
+ def redact_value
89
+ def register
90
+ def reject
91
+ def request
92
+ def resolve_path
93
+ def response
94
+ def retrieve
95
+ def run
96
+ def run_agent
97
+ def run_result
98
+ def search
99
+ def session
100
+ def set
101
+ def specs
102
+ def stream_part
103
+ def string
104
+ def stringify
105
+ def strip_markup
106
+ def structured_apply
107
+ def text_present
108
+ def timestamp
109
+ def to_wire
110
+ def tool_call
111
+ def tool_spec
112
+ def truncate_to_tokens
113
+ def unmarshal
114
+ def update
115
+ def usage
116
+ def validate
117
+ def visit
118
+ def visit_array
119
+ def visit_boolean
120
+ def visit_number
121
+ def visit_object
122
+ def visit_string
123
+ def wait
124
+ def within?
125
+ module Agent
126
+ module Delegation
127
+ module Json
128
+ module JsonSchema
129
+ module Middleware
130
+ module Models
131
+ module Plugin
132
+ module Praxo
133
+ module Runtime
134
+ module SSE
135
+ module Toolcall
@@ -0,0 +1,121 @@
1
+ require 'net/http'
2
+ require 'time'
3
+ require 'uri'
4
+ require_relative '../errors'
5
+ require_relative '../json'
6
+
7
+ module Praxo
8
+ module Adapters
9
+ class OtelSink
10
+ MAX_BODY = 512
11
+
12
+ def initialize(endpoint: 'http://127.0.0.1:4318/v1/traces',
13
+ service_name: 'praxo-core', transport: nil,
14
+ allowed_data_keys: [], timeout: 10)
15
+ @endpoint = endpoint.to_s.empty? ? 'http://127.0.0.1:4318/v1/traces' : endpoint
16
+ @service_name = service_name.to_s.empty? ? 'praxo-core' : service_name
17
+ @transport = transport
18
+ @allowed_data_keys = Array(allowed_data_keys).map(&:to_s)
19
+ @timeout = timeout
20
+ end
21
+
22
+ def emit(event)
23
+ now = Time.now.utc
24
+ stamp = otel_stamp(event, now)
25
+ nanos = now.to_i * 1_000_000_000 + now.nsec
26
+ data = event.data || {}
27
+ key = [event.session_id, event.run_id, event.type,
28
+ Json.stringify(data)].join('|')
29
+ trace_id = [2166136261, 3307539480, 1540483477, 2807494644]
30
+ .map { |seed| hex32(fnv1a(key, seed)) }.join
31
+ span_key = "#{key}|span"
32
+ span_id = [2166136261, 3307539480]
33
+ .map { |seed| hex32(fnv1a(span_key, seed)) }.join
34
+ attributes = [attribute('praxo.event.type', event.type)]
35
+ if event.session_id && !event.session_id.empty?
36
+ attributes << attribute('praxo.session.id', event.session_id)
37
+ end
38
+ if event.run_id && !event.run_id.empty?
39
+ attributes << attribute('praxo.run.id', event.run_id)
40
+ end
41
+ attributes << attribute('praxo.event.at', stamp)
42
+ @allowed_data_keys.each do |name|
43
+ next unless data.key?(name)
44
+
45
+ attributes << attribute("praxo.event.data.#{name}", otel_text(data[name]))
46
+ end
47
+ payload = {
48
+ 'resourceSpans' => [{
49
+ 'resource' => {
50
+ 'attributes' => [attribute('service.name', @service_name)]
51
+ },
52
+ 'scopeSpans' => [{
53
+ 'scope' => { 'name' => 'praxo-core' },
54
+ 'spans' => [{
55
+ 'traceId' => trace_id,
56
+ 'spanId' => span_id,
57
+ 'name' => "praxo.#{event.type}",
58
+ 'kind' => 1,
59
+ 'startTimeUnixNano' => nanos.to_s,
60
+ 'endTimeUnixNano' => nanos.to_s,
61
+ 'attributes' => attributes
62
+ }]
63
+ }]
64
+ }]
65
+ }
66
+ body = Json.stringify(payload)
67
+ headers = { 'content-type' => 'application/json' }
68
+ status, response_body = @transport ? @transport.call(@endpoint, body, headers) : post(body, headers)
69
+ return if status.to_i >= 200 && status.to_i < 300
70
+
71
+ bounded = response_body.to_s[0, MAX_BODY]
72
+ Praxo.error('OTEL_HTTP', "otel: HTTP #{status}: #{bounded}")
73
+ end
74
+
75
+ private
76
+
77
+ def otel_stamp(event, now)
78
+ if event.respond_to?(:at) && event.at
79
+ event.at.to_s
80
+ else
81
+ now.iso8601(9)
82
+ end
83
+ end
84
+
85
+ def attribute(key, value)
86
+ { 'key' => key, 'value' => { 'stringValue' => value.to_s } }
87
+ end
88
+
89
+ def otel_text(value)
90
+ value.is_a?(String) ? value : Json.stringify(value)
91
+ end
92
+
93
+ def fnv1a(text, seed)
94
+ value = seed & 0xFFFFFFFF
95
+ text.to_s.bytes.each do |byte|
96
+ value ^= byte
97
+ value = (value * 16_777_619) & 0xFFFFFFFF
98
+ end
99
+ value
100
+ end
101
+
102
+ def hex32(value)
103
+ format('%08x', value & 0xFFFFFFFF)
104
+ end
105
+
106
+ def post(body, headers)
107
+ uri = URI.parse(@endpoint)
108
+ request = Net::HTTP::Post.new(uri)
109
+ headers.each { |key, value| request[key] = value }
110
+ request.body = body
111
+ response = Net::HTTP.start(
112
+ uri.host,
113
+ uri.port,
114
+ use_ssl: uri.scheme == 'https',
115
+ read_timeout: @timeout
116
+ ) { |http| http.request(request) }
117
+ [response.code.to_i, response.body.to_s]
118
+ end
119
+ end
120
+ end
121
+ end
@@ -0,0 +1,150 @@
1
+ require_relative 'errors'
2
+
3
+ module Praxo
4
+ module Delegation
5
+ SubagentRequest = Struct.new(
6
+ :parent_session_id, :agent_id, :prompt, :context, :mode, :history,
7
+ keyword_init: true
8
+ )
9
+ SubagentResult = Struct.new(
10
+ :task_id, :agent_id, :output, :usage, keyword_init: true
11
+ )
12
+ SubagentTask = Struct.new(
13
+ :id, :parent_session_id, :agent_id, :mode, :status, :output, :error,
14
+ :created_at, :updated_at, keyword_init: true
15
+ )
16
+
17
+ class SubagentManager
18
+ TERMINAL = %w[completed failed canceled].freeze
19
+
20
+ def initialize(runner)
21
+ @runner = runner
22
+ @tasks = {}
23
+ @mutex = Mutex.new
24
+ @condition = ConditionVariable.new
25
+ @sequence = 0
26
+ end
27
+
28
+ def launch(request)
29
+ raise Praxo::Error.new('SUBAGENT_INVALID', 'agent: subagent runner is required') if @runner.nil?
30
+
31
+ parent = request.parent_session_id.to_s
32
+ agent = request.agent_id.to_s
33
+ if parent.empty? || agent.empty?
34
+ raise Praxo::Error.new(
35
+ 'SUBAGENT_INVALID',
36
+ 'agent: subagent parent session and agent id are required'
37
+ )
38
+ end
39
+ id = @mutex.synchronize { @sequence += 1; "subagent-#{@sequence}" }
40
+ now = timestamp
41
+ task = SubagentTask.new(
42
+ id: id, parent_session_id: parent, agent_id: agent,
43
+ mode: request.mode || 'isolated', status: 'queued',
44
+ output: '', error: '', created_at: now, updated_at: now
45
+ )
46
+ @mutex.synchronize { @tasks[id] = { task: task, done: false } }
47
+ Thread.new { execute(id, request) }
48
+ copy(task)
49
+ end
50
+
51
+ def check(task_id)
52
+ @mutex.synchronize do
53
+ state = @tasks[task_id]
54
+ state.nil? ? nil : copy(state[:task])
55
+ end
56
+ end
57
+
58
+ def wait(task_id, timeout = nil)
59
+ deadline = timeout.nil? ? nil : Time.now + timeout
60
+ @mutex.synchronize do
61
+ state = @tasks[task_id]
62
+ raise Praxo::Error.new('SUBAGENT_NOT_FOUND', "agent: unknown subagent task \"#{task_id}\"") if state.nil?
63
+
64
+ until state[:done]
65
+ if deadline.nil?
66
+ @condition.wait(@mutex)
67
+ else
68
+ remaining = deadline - Time.now
69
+ if remaining <= 0
70
+ raise Praxo::Error.new(
71
+ 'SUBAGENT_TIMEOUT',
72
+ 'agent: subagent wait timed out'
73
+ )
74
+ end
75
+ @condition.wait(@mutex, remaining)
76
+ end
77
+ end
78
+ copy(state[:task])
79
+ end
80
+ end
81
+
82
+ def update(task_id, prompt)
83
+ unless @runner.respond_to?(:update)
84
+ raise Praxo::Error.new(
85
+ 'SUBAGENT_UPDATE_UNSUPPORTED',
86
+ 'agent: subagent update unsupported'
87
+ )
88
+ end
89
+ @mutex.synchronize do
90
+ state = @tasks[task_id]
91
+ raise Praxo::Error.new('SUBAGENT_NOT_FOUND', "agent: unknown subagent task \"#{task_id}\"") if state.nil?
92
+ unless state[:task].status == 'running'
93
+ raise Praxo::Error.new(
94
+ 'SUBAGENT_NOT_RUNNING',
95
+ "agent: subagent task \"#{task_id}\" is not running"
96
+ )
97
+ end
98
+ end
99
+ @runner.update(task_id, prompt)
100
+ end
101
+
102
+ def cancel(task_id)
103
+ @mutex.synchronize do
104
+ state = @tasks[task_id]
105
+ raise Praxo::Error.new('SUBAGENT_NOT_FOUND', "agent: unknown subagent task \"#{task_id}\"") if state.nil?
106
+ return if TERMINAL.include?(state[:task].status)
107
+
108
+ state[:task].status = 'canceled'
109
+ state[:task].updated_at = timestamp
110
+ state[:done] = true
111
+ @condition.broadcast
112
+ end
113
+ end
114
+
115
+ private
116
+
117
+ def execute(task_id, request)
118
+ set(task_id, 'running')
119
+ result = @runner.run(request)
120
+ set(task_id, 'completed', output: result.output.to_s)
121
+ rescue StandardError => error
122
+ set(task_id, 'failed', error: error.message)
123
+ end
124
+
125
+ def set(task_id, status, output: '', error: '')
126
+ @mutex.synchronize do
127
+ state = @tasks[task_id]
128
+ return if state.nil? || TERMINAL.include?(state[:task].status)
129
+
130
+ state[:task].status = status
131
+ state[:task].output = output
132
+ state[:task].error = error
133
+ state[:task].updated_at = timestamp
134
+ if TERMINAL.include?(status)
135
+ state[:done] = true
136
+ @condition.broadcast
137
+ end
138
+ end
139
+ end
140
+
141
+ def copy(task)
142
+ SubagentTask.new(**task.to_h)
143
+ end
144
+
145
+ def timestamp
146
+ Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
147
+ end
148
+ end
149
+ end
150
+ end
@@ -0,0 +1,22 @@
1
+ module Praxo
2
+ Document = Struct.new(:id, :content, :metadata, :score, keyword_init: true) do
3
+ def to_wire
4
+ out = { 'id' => id, 'content' => content }
5
+ out['metadata'] = metadata if metadata && !metadata.empty?
6
+ out['score'] = score if score && score != 0
7
+ out
8
+ end
9
+ end
10
+
11
+ class FuncRetriever
12
+ def initialize(&block)
13
+ raise ArgumentError, 'retriever: block is required' unless block
14
+
15
+ @block = block
16
+ end
17
+
18
+ def retrieve(query, limit)
19
+ @block.call(query.to_s, limit.to_i)
20
+ end
21
+ end
22
+ end
data/lib/praxo.rb CHANGED
@@ -14,3 +14,6 @@ require_relative 'praxo/adapters/gemini'
14
14
  require_relative 'praxo/adapters/mcp'
15
15
  require_relative 'praxo/adapters/mcp_http'
16
16
  require_relative 'praxo/adapters/harmovela_sink'
17
+ require_relative 'praxo/retriever'
18
+ require_relative 'praxo/delegation'
19
+ require_relative 'praxo/adapters/otel_sink'
data/llms.md CHANGED
@@ -8,15 +8,26 @@
8
8
 
9
9
  - package: `praxo-core`
10
10
  - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.5.0)
11
- - source_version: `0.6.0`
11
+ - source_version: `0.7.0`
12
12
  - published_version: `0.5.0`
13
13
  - install_published: `gem install praxo-core`
14
14
  - install_source: `gem install praxo-core`
15
- - source_tag: `ruby/v0.6.0`
15
+ - source_tag: `ruby/v0.7.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
+ ## Capabilities and Status
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)
25
+ - MCP client: native (`Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26)
26
+ - Harmovela sink: native (`Praxo::Adapters::HarmovelaSink`)
27
+ - OpenTelemetry sink: native (transport seam) (`OtelSink`; caller supplies OTLP/HTTP transport)
28
+ - Subagent delegation: native (`Delegation::SubagentManager`)
29
+ - Retriever: native (`Document`, `FuncRetriever`)
30
+
20
31
  ## Start
21
32
 
22
33
  - README: `README.md`
data/llms.txt CHANGED
@@ -8,15 +8,26 @@
8
8
 
9
9
  - package: `praxo-core`
10
10
  - registry: [RubyGems](https://rubygems.org/gems/praxo-core/versions/0.5.0)
11
- - source_version: `0.6.0`
11
+ - source_version: `0.7.0`
12
12
  - published_version: `0.5.0`
13
13
  - install_published: `gem install praxo-core`
14
14
  - install_source: `gem install praxo-core`
15
- - source_tag: `ruby/v0.6.0`
15
+ - source_tag: `ruby/v0.7.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
+ # Capabilities and Status
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)
25
+ - MCP client: native (`Praxo::Adapters::MCPClient`; stdio, plus `HttpMCPTransport` for Streamable HTTP 2025-03-26)
26
+ - Harmovela sink: native (`Praxo::Adapters::HarmovelaSink`)
27
+ - OpenTelemetry sink: native (transport seam) (`OtelSink`; caller supplies OTLP/HTTP transport)
28
+ - Subagent delegation: native (`Delegation::SubagentManager`)
29
+ - Retriever: native (`Document`, `FuncRetriever`)
30
+
20
31
  # Start
21
32
 
22
33
  - README: `README.md`
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.6.0
4
+ version: 0.7.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - AxisVela
@@ -27,6 +27,7 @@ files:
27
27
  - api/0.4.1.txt
28
28
  - api/0.5.0.txt
29
29
  - api/0.6.0.txt
30
+ - api/0.7.0.txt
30
31
  - lib/praxo.rb
31
32
  - lib/praxo/adapters/anthropic.rb
32
33
  - lib/praxo/adapters/gemini.rb
@@ -34,13 +35,16 @@ files:
34
35
  - lib/praxo/adapters/mcp.rb
35
36
  - lib/praxo/adapters/mcp_http.rb
36
37
  - lib/praxo/adapters/openai_compatible.rb
38
+ - lib/praxo/adapters/otel_sink.rb
37
39
  - lib/praxo/agent.rb
40
+ - lib/praxo/delegation.rb
38
41
  - lib/praxo/errors.rb
39
42
  - lib/praxo/json.rb
40
43
  - lib/praxo/jsonschema.rb
41
44
  - lib/praxo/middleware.rb
42
45
  - lib/praxo/models.rb
43
46
  - lib/praxo/plugin.rb
47
+ - lib/praxo/retriever.rb
44
48
  - lib/praxo/runtime.rb
45
49
  - lib/praxo/sse.rb
46
50
  - lib/praxo/toolcall.rb