actionable-tools 1.0.0.pre1

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 ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: c34a37b35ab051abe00d4334faf3f8e5094e2e343af77849c32ecaf336d67e13
4
+ data.tar.gz: 722f4fc4c5ed2dc260881c6d7be4afb2d2bc12283ce342bea6e0c166138ccb95
5
+ SHA512:
6
+ metadata.gz: 1d93f7e0443aefd7ccd6e05b4a995a21419dbb55a9093e15c199bc6bfc2c7e112b0cdf3561d3b8aa1d9906809dfb5604b9d14a4c6756357f94604e6e675cecef
7
+ data.tar.gz: cb84d0bb94433fec2c253b272f09b6c8ae7944b3b7ace273160c28ff040c0121e59d38b82fe5d697d343ca41cba3d5f7f30964241fb70df438477e46e0ee4391
data/CHANGELOG.md ADDED
@@ -0,0 +1,7 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ - First release: `Actionable::Tools.definition`, the MCP wrapper and the RubyLLM wrapper.
6
+ - The input and output schemas ask field_struct-json_schema for `decimals: :string`, so a decimal is a string in both,
7
+ as the envelope (`output.as_json`) carries it.
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Adrian Madrid
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 ADDED
@@ -0,0 +1,180 @@
1
+ # actionable-tools
2
+
3
+ Let an LLM call an [actionable-rb](../../gems/actionable) action as a tool. The action you already wrote (typed input,
4
+ validations, declared failures and skips) becomes the tool. You add a description, and you say which input fields your
5
+ server fills in (identity, station) instead of the model.
6
+
7
+ One form-neutral `Definition`, plus two thin wrappers: the MCP Ruby SDK (`mcp`) and RubyLLM (`ruby_llm`). Neither is a
8
+ dependency; each is needed only by its own require.
9
+
10
+ ```ruby
11
+ gem 'actionable-tools'
12
+ gem 'mcp', '~> 1.8' # for actionable/tools/mcp
13
+ gem 'ruby_llm', '~> 2.1' # for actionable/tools/ruby_llm
14
+ ```
15
+
16
+ Version `1.0.0.pre1`. Ruby 3.3 or newer. Load it with `require 'actionable/tools'`.
17
+
18
+ ## A tool from an action
19
+
20
+ Nothing is exposed unless you name it. The input schema comes from the action's `input` block, minus the context
21
+ fields; the model never sees them and cannot set them.
22
+
23
+ ```ruby run
24
+ require 'actionable/tools'
25
+
26
+ class ReadGauge < Actionable::Action
27
+ input do
28
+ required :code, :string, description: 'Code of the station'
29
+ required :network_id, :integer
30
+ end
31
+
32
+ output do
33
+ required :summary, :string
34
+ end
35
+
36
+ fails :unknown_station, 'no such station', suggest: 'check the code'
37
+
38
+ step :find
39
+
40
+ private
41
+
42
+ def find
43
+ fail!(:unknown_station) if input.code == '0000'
44
+ @summary = "Station #{input.code} on network #{input.network_id}"
45
+ end
46
+ end
47
+
48
+ tool = Actionable::Tools.definition(ReadGauge,
49
+ description: 'Read the latest level at a station',
50
+ context: { network_id: ->(source) { source[:network_id] } })
51
+
52
+ tool.name # => "read_gauge"
53
+ tool.action # => ReadGauge
54
+ tool.input_schema['properties'].keys # => ["code"]
55
+ tool.input_schema['required'] # => ["code"]
56
+ tool.call({ 'code' => '1234', 'network_id' => 999 }, { network_id: 3 })['output'] # => {"summary"=>"Station 1234 on network 3"}
57
+ ```
58
+
59
+ Every call returns the same six-key Hash, whether the run succeeded, failed or was skipped. A failure carries the
60
+ declared code and its metadata. The tool's `output_schema` describes it, including the declared codes.
61
+
62
+ ```ruby run
63
+ require 'actionable/tools'
64
+
65
+ class ConvertDepth < Actionable::Action
66
+ input do
67
+ required :fathoms, :float
68
+ required :to, :string, enum: %w[feet metres]
69
+ end
70
+
71
+ fails :beyond_line, 'that is deeper than the sounding line'
72
+
73
+ step :convert
74
+
75
+ private
76
+
77
+ def convert
78
+ fail!(:beyond_line) if input.fathoms > 1000
79
+ succeed(value: input.to == 'feet' ? input.fathoms * 6 : input.fathoms * 1.8288)
80
+ end
81
+ end
82
+
83
+ tool = Actionable::Tools.definition(ConvertDepth, description: 'Convert a sounding depth')
84
+
85
+ tool.call({ 'fathoms' => 100.0, 'to' => 'feet' })['output'] # => {"value"=>600.0}
86
+ bad = tool.call({ 'fathoms' => 5000.0, 'to' => 'feet' })
87
+ bad.keys # => ["status", "code", "message", "output", "errors", "metadata"]
88
+ [bad['status'], bad['code']] # => ["failure", "beyond_line"]
89
+ tool.error?(bad) # => true
90
+ tool.output_schema['properties']['code']['description'] # => "\"success\", or why the run failed or was skipped. Declared failures: beyond_line. \"invalid_input\" means the arguments were rejected; see errors."
91
+ ```
92
+
93
+ Bad input is a failure too (`invalid_input`, with `errors`). An exception the action raises is not a result: it
94
+ propagates.
95
+
96
+ ## MCP
97
+
98
+ ```ruby run
99
+ require 'actionable/tools/mcp'
100
+
101
+ class FathomsToFeet < Actionable::Action
102
+ input do
103
+ required :fathoms, :float
104
+ required :operator_id, :integer
105
+ end
106
+
107
+ step :convert
108
+
109
+ private
110
+
111
+ def convert = succeed(feet: input.fathoms * 6)
112
+ end
113
+
114
+ tool = Actionable::Tools::MCP.tool(FathomsToFeet,
115
+ description: 'Fathoms to feet',
116
+ context: { operator_id: ->(server_context) { server_context[:operator_id] } },
117
+ annotations: { read_only: true })
118
+ server = MCP::Server.new(name: 'harbour', tools: [tool], server_context: { operator_id: 7 })
119
+
120
+ request = { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'fathoms_to_feet', arguments: { fathoms: 100.0 } } }
121
+ reply = server.handle(request)
122
+ reply[:result][:isError] # => false
123
+ reply[:result][:structuredContent]['output'] # => {"feet"=>600.0}
124
+ tool.to_h[:annotations] # => {destructiveHint: true, idempotentHint: false, openWorldHint: true, readOnlyHint: true}
125
+ ```
126
+
127
+ `annotations:` takes `read_only`, `destructive`, `idempotent` and `open_world`; any other key raises when the tool is
128
+ built. A failure sets `isError`; a skip does not. The same JSON is in `content` and in `structuredContent`. Wrong-typed
129
+ arguments (a number for a decimal, which the schema calls a string) are rejected by the SDK before the action runs.
130
+ `examples/stdio_server.rb` is a complete stdio server.
131
+
132
+ ## RubyLLM
133
+
134
+ The class you get is a `RubyLLM::Tool`; construct it with the object your context procs read (the current operator, say).
135
+
136
+ ```ruby run
137
+ require 'actionable/tools/ruby_llm'
138
+
139
+ class FathomsToFeet < Actionable::Action
140
+ input do
141
+ required :fathoms, :float
142
+ required :operator_id, :integer
143
+ end
144
+
145
+ step :convert
146
+
147
+ private
148
+
149
+ def convert = succeed(feet: input.fathoms * 6)
150
+ end
151
+
152
+ Surveyor = Struct.new(:id)
153
+ Tool = Actionable::Tools::RubyLLM.tool(FathomsToFeet,
154
+ description: 'Fathoms to feet',
155
+ context: { operator_id: ->(surveyor) { surveyor.id } },
156
+ approval: true)
157
+
158
+ tool = Tool.new(Surveyor.new(7))
159
+ tool.name # => "fathoms_to_feet"
160
+ tool.requires_approval? # => true
161
+ tool.call(fathoms: 100.0)['output'] # => {"feet"=>600.0}
162
+ ```
163
+
164
+ The tool returns the envelope Hash, and a failure is returned, not raised. `RubyLLM` ignores `annotations:`.
165
+
166
+ ## What is and is not covered
167
+
168
+ - Actions with a discriminated input (`input_for`) and actions without an `input` block raise `ArgumentError`.
169
+ - `description:` is required, even when the action has a `desc`: the tool's text is written for a model, the
170
+ action's for people.
171
+ - A `big_decimal` is a string in the schema (`"12.50"`); ranges (`in:`) are not in the schema, but the action still
172
+ enforces them.
173
+ - Output is checked against the schema only on success.
174
+ - Nothing here rescues the action, authenticates, streams or exposes resources.
175
+
176
+ Signatures are in `sig/`; the library names mcp and ruby_llm return are typed `Class`.
177
+
178
+ ## Docs
179
+
180
+ The guide on the docs site, with every example run in CI: https://gliders-rb.github.io/adapters/tools/
@@ -0,0 +1,89 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Actionable
4
+ module Tools
5
+ # Form-neutral description of one action as a tool: name, description, annotations, schemas and +call+.
6
+ # Immutable once built (AT-I7).
7
+ class Definition
8
+ # @return [Class] the action
9
+ attr_reader :action
10
+ # @return [::String]
11
+ attr_reader :name
12
+ # @return [::String] as given, not stripped
13
+ attr_reader :description
14
+ # @return [::Hash{::Symbol=>Boolean}] frozen
15
+ attr_reader :annotations
16
+ # @return [::Hash{::String=>::Object}] JSON Schema of the arguments the model sends; frozen (shallowly)
17
+ attr_reader :input_schema
18
+ # @return [::Hash{::String=>::Object}] JSON Schema of the result envelope {Tools::RESULT_KEYS}; frozen (shallowly)
19
+ attr_reader :output_schema
20
+
21
+ # @param action [Class] an +Actionable::Action+ subclass
22
+ # @param description [::String]
23
+ # @param name [::String, nil]
24
+ # @param context [::Hash{::Symbol=>::Proc}]
25
+ # @param annotations [::Hash{::Symbol=>Boolean}] frozen in place (the caller's Hash)
26
+ # @raise [::ArgumentError] when the action cannot be a tool (AT-B1..B5)
27
+ def initialize(action, description:, name:, context:, annotations:)
28
+ check_shape(action, description)
29
+ @action = action
30
+ @context = normalise_context(action, context)
31
+ @name = name || default_name(action)
32
+ @description = description
33
+ @annotations = annotations.freeze
34
+ @input_schema = InputSchema.build(action.input_schema, @context.keys).freeze
35
+ @output_schema = OutputSchema.build(action).freeze
36
+ freeze
37
+ end
38
+
39
+ # Runs the action for a model's arguments and returns the six-key result envelope (AT-B20, AT-B21). Exceptions
40
+ # the action raises propagate (AT-B22).
41
+ #
42
+ # @param arguments [::Hash{::Object=>::Object}] what the model sent, under external (JSON) names
43
+ # @param source [Object, nil] handed to each context proc
44
+ # @return [::Hash{::String=>::Object}] status, code, message, output, errors, metadata
45
+ def call(arguments, source = nil)
46
+ Envelope.build(action.run(**run_input(arguments, source)))
47
+ end
48
+
49
+ # @param result [::Hash{::String=>::Object}] an envelope from {#call}
50
+ # @return [Boolean] true only for a failure (a skip is not an error)
51
+ def error?(result)
52
+ result['status'] == 'failure'
53
+ end
54
+
55
+ private
56
+
57
+ def run_input(arguments, source)
58
+ reverse = action.input_schema.metadata.reverse_serialization(:json)
59
+ input = arguments.to_h.transform_keys { |key| reverse.fetch(key.to_s) { key.to_sym } }
60
+ @context.each { |field, filler| input[field] = filler.call(source) }
61
+ input
62
+ end
63
+
64
+ def check_shape(action, description)
65
+ if action.respond_to?(:input_dispatch) && !action.input_dispatch.nil?
66
+ raise ArgumentError, "#{action} has a discriminated input (input_for), which has no single schema yet"
67
+ end
68
+ raise ArgumentError, "#{action} has no input schema; tools need one" if action.input_schema.nil?
69
+ raise ArgumentError, "#{action}: a tool needs a description" if description.to_s.strip.empty?
70
+ end
71
+
72
+ def normalise_context(action, context)
73
+ context = context.to_h { |field, source| [field.to_sym, source] }
74
+ unknown = context.keys - action.input_schema.attribute_names
75
+ raise ArgumentError, "#{action} has no input field #{unknown.join(', ')} to take from context" unless unknown.empty?
76
+
77
+ context.freeze
78
+ end
79
+
80
+ def default_name(action)
81
+ raise ArgumentError, 'an anonymous action needs name:' if action.name.nil?
82
+
83
+ snake = action.name.split('::').last
84
+ snake = snake.gsub(/([a-z\d])([A-Z])/, '\1_\2')
85
+ snake.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').downcase
86
+ end
87
+ end
88
+ end
89
+ end
@@ -0,0 +1,32 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Actionable
4
+ module Tools
5
+ # Turns an +Actionable::Result+ into the six-key Hash a tool call returns (AT-B21).
6
+ module Envelope
7
+ module_function
8
+
9
+ # @param result [Actionable::Result]
10
+ # @return [::Hash{::String=>::Object}] status, code, message, output, errors and metadata as plain JSON values
11
+ def build(result)
12
+ {
13
+ 'status' => result.status.to_s,
14
+ 'code' => result.code.to_s,
15
+ 'message' => result.message,
16
+ 'output' => plain(result.output),
17
+ 'errors' => plain(result.errors.to_h),
18
+ 'metadata' => result.respond_to?(:metadata) ? plain(result.metadata) : {}
19
+ }
20
+ end
21
+
22
+ # A JSON round trip through Oj, so structs and BigDecimals become their JSON form and symbols become strings.
23
+ #
24
+ # @param value [Object]
25
+ # @return [Object] JSON-safe plain data
26
+ def plain(value)
27
+ value = value.as_json if value.respond_to?(:as_json)
28
+ Oj.load(Oj.dump(value, mode: :compat), mode: :compat)
29
+ end
30
+ end
31
+ end
32
+ end
@@ -0,0 +1,32 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Actionable
4
+ module Tools
5
+ # Builds the JSON Schema of an action's input, minus the fields the server fills from context (AT-B10, AT-B11).
6
+ module InputSchema
7
+ module_function
8
+
9
+ # @param input [Class] the action's input struct class
10
+ # @param context_fields [Array<::Symbol>] field names taken from context
11
+ # @return [::Hash{::String=>::Object}] a fresh schema (draft 2020-12), context fields removed under their JSON names
12
+ def build(input, context_fields)
13
+ # A decimal stays a string, as the model must send it (AT-B13).
14
+ schema = FieldStruct::JSONSchema.generate(input, decimals: :string)
15
+ keys = FieldStruct::Introspection.properties(input).select { |property| context_fields.include?(property.field.name) }
16
+ keys.each { |property| remove(schema, property.key) }
17
+ schema
18
+ end
19
+
20
+ # @param schema [::Hash{::String=>::Object}]
21
+ # @param key [::String]
22
+ # @return [void]
23
+ def remove(schema, key)
24
+ schema['properties']&.delete(key)
25
+ return unless schema['required']
26
+
27
+ schema['required'].delete(key)
28
+ schema.delete('required') if schema['required'].empty?
29
+ end
30
+ end
31
+ end
32
+ end
@@ -0,0 +1,65 @@
1
+ # frozen_string_literal: true
2
+
3
+ begin
4
+ require 'mcp'
5
+ rescue LoadError
6
+ raise LoadError, "actionable/tools/mcp needs the mcp gem: add `gem 'mcp', '~> 1.8'` to your Gemfile"
7
+ end
8
+ require 'actionable/tools'
9
+
10
+ module Actionable
11
+ module Tools
12
+ # Wraps a {Definition} as an +MCP::Tool+ subclass for the MCP Ruby SDK.
13
+ module MCP
14
+ # @return [::Hash{::Symbol=>::Symbol}] the annotation keys a tool takes, and the SDK keyword each maps to
15
+ HINTS = {
16
+ read_only: :read_only_hint,
17
+ destructive: :destructive_hint,
18
+ idempotent: :idempotent_hint,
19
+ open_world: :open_world_hint
20
+ }.freeze
21
+
22
+ module_function
23
+
24
+ # Builds the tool class of one action.
25
+ #
26
+ # @param action [Class] an +Actionable::Action+ subclass
27
+ # @param options [Object] the keywords of {Tools.definition}
28
+ # @return [Class] an +MCP::Tool+ subclass
29
+ def tool(action, **options) # rubocop:disable Style/ArgumentsForwarding -- named so YARD/Sord document the keyword splat
30
+ from(Tools.definition(action, **options)) # rubocop:disable Style/ArgumentsForwarding
31
+ end
32
+
33
+ # Builds the tool class of a definition.
34
+ #
35
+ # @param definition [Actionable::Tools::Definition]
36
+ # @return [Class] an +MCP::Tool+ subclass
37
+ # @raise [::ArgumentError] on an annotation key outside {HINTS}
38
+ def from(definition)
39
+ hints = annotations(definition.annotations)
40
+ schemas = { input_schema: definition.input_schema, output_schema: definition.output_schema }
41
+ label = { name: definition.name, description: definition.description, annotations: hints }
42
+ ::MCP::Tool.define(**label, **schemas) do |server_context: nil, **args|
43
+ envelope = definition.call(args, server_context)
44
+ text = { type: 'text', text: Oj.dump(envelope, mode: :compat) }
45
+ ::MCP::Tool::Response.new([text], error: definition.error?(envelope), structured_content: envelope)
46
+ end
47
+ end
48
+
49
+ # Maps annotation hints to the SDK's keywords.
50
+ #
51
+ # @param hints [::Hash{::Symbol=>Boolean}]
52
+ # @return [::Hash{::Symbol=>Boolean}, nil] nil when there are no hints
53
+ # @raise [::ArgumentError] on an unknown key
54
+ def annotations(hints)
55
+ return nil if hints.empty?
56
+
57
+ known = HINTS.keys
58
+ stray = hints.keys.reject { |key| known.include?(key) }
59
+ raise ArgumentError, "unknown annotations: #{stray.join(', ')} (known: #{known.join(', ')})" if stray.any?
60
+
61
+ hints.each_with_object({}) { |(key, value), mapped| mapped[HINTS.fetch(key)] = value }
62
+ end
63
+ end
64
+ end
65
+ end
@@ -0,0 +1,62 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Actionable
4
+ module Tools
5
+ # Builds the JSON Schema of the result envelope a tool call returns (AT-B15..B18).
6
+ module OutputSchema
7
+ STATUSES = %w[success failure skipped].freeze
8
+ ERRORS = { 'type' => 'object', 'additionalProperties' => { 'type' => 'array', 'items' => { 'type' => 'string' } } }.freeze
9
+
10
+ module_function
11
+
12
+ # @param action [Class] an +Actionable::Action+ subclass
13
+ # @return [::Hash{::String=>::Object}] a fresh schema (draft 2020-12)
14
+ def build(action)
15
+ schema = {
16
+ '$schema' => FieldStruct::JSONSchema::DRAFT,
17
+ 'type' => 'object',
18
+ 'required' => RESULT_KEYS.dup,
19
+ 'properties' => properties(action)
20
+ }
21
+ add_output(schema, action.output_schema) if action.output_schema
22
+ schema
23
+ end
24
+
25
+ # @param action [Class]
26
+ # @return [::Hash{::String=>::Object}]
27
+ def properties(action)
28
+ {
29
+ 'status' => { 'enum' => STATUSES.dup },
30
+ 'code' => { 'type' => 'string', 'description' => code_description(action) },
31
+ 'message' => { 'type' => %w[string null] },
32
+ 'output' => {},
33
+ 'errors' => Marshal.load(Marshal.dump(ERRORS)),
34
+ 'metadata' => { 'type' => 'object' }
35
+ }
36
+ end
37
+
38
+ # @param action [Class]
39
+ # @return [::String] the text for the +code+ property
40
+ def code_description(action)
41
+ text = +'"success", or why the run failed or was skipped.'
42
+ failures = action.declared_failures.keys
43
+ skips = action.declared_skips.keys
44
+ text << " Declared failures: #{failures.join(', ')}." unless failures.empty?
45
+ text << " Declared skips: #{skips.join(', ')}." unless skips.empty?
46
+ text << ' "invalid_input" means the arguments were rejected; see errors.'
47
+ end
48
+
49
+ # @param schema [::Hash{::String=>::Object}] modified in place
50
+ # @param output [Class] the action's output struct class
51
+ # @return [void]
52
+ def add_output(schema, output)
53
+ # The envelope carries output.as_json, where a decimal is a string.
54
+ body = FieldStruct::JSONSchema.generate(output, decimals: :string).except('$schema')
55
+ shared = body.delete('$defs')
56
+ schema['$defs'] = shared if shared
57
+ schema['if'] = { 'properties' => { 'status' => { 'const' => 'success' } } }
58
+ schema['then'] = { 'properties' => { 'output' => body } }
59
+ end
60
+ end
61
+ end
62
+ end
@@ -0,0 +1,48 @@
1
+ # frozen_string_literal: true
2
+
3
+ begin
4
+ require 'ruby_llm'
5
+ rescue LoadError
6
+ raise LoadError, "actionable/tools/ruby_llm needs the ruby_llm gem: add `gem 'ruby_llm', '~> 2.1'` to your Gemfile"
7
+ end
8
+ require 'actionable/tools'
9
+
10
+ module Actionable
11
+ module Tools
12
+ # Wraps a {Definition} as a +RubyLLM::Tool+ subclass.
13
+ module RubyLLM
14
+ module_function
15
+
16
+ # Builds the tool class of one action.
17
+ #
18
+ # @param action [Class] an +Actionable::Action+ subclass
19
+ # @param approval [Boolean] true makes the chat pause for a decision before the tool runs
20
+ # @param options [Object] the keywords of {Tools.definition}
21
+ # @return [Class] a +RubyLLM::Tool+ subclass; construct it with the source handed to the context procs
22
+ def tool(action, approval: false, **options) # rubocop:disable Style/ArgumentsForwarding -- named for YARD/Sord
23
+ from(Tools.definition(action, **options), approval: approval) # rubocop:disable Style/ArgumentsForwarding
24
+ end
25
+
26
+ # Builds the tool class of a definition.
27
+ #
28
+ # @param definition [Actionable::Tools::Definition]
29
+ # @param approval [Boolean]
30
+ # @return [Class] a +RubyLLM::Tool+ subclass
31
+ def from(definition, approval: false)
32
+ klass = Class.new(::RubyLLM::Tool)
33
+ klass.description(definition.description)
34
+ klass.parameters(definition.input_schema)
35
+ klass.requires_approval if approval
36
+ klass.define_singleton_method(:tool_name) { definition.name }
37
+ klass.class_exec do
38
+ def initialize(source = nil)
39
+ super()
40
+ @source = source
41
+ end
42
+ end
43
+ klass.define_method(:execute) { |**args| definition.call(args, @source) }
44
+ klass
45
+ end
46
+ end
47
+ end
48
+ end
@@ -0,0 +1,9 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Actionable
4
+ # Expose actions as LLM tools.
5
+ module Tools
6
+ # @return [::String]
7
+ VERSION = '1.0.0.pre1'
8
+ end
9
+ end
@@ -0,0 +1,36 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'oj'
4
+ require 'actionable'
5
+ require 'field_struct/json_schema'
6
+
7
+ require_relative 'tools/version'
8
+ require_relative 'tools/input_schema'
9
+ require_relative 'tools/output_schema'
10
+ require_relative 'tools/envelope'
11
+ require_relative 'tools/definition'
12
+
13
+ # The actionable-rb namespace; this gem adds {Tools}.
14
+ module Actionable
15
+ # Expose actions as LLM tools. {Tools.definition} builds the form-neutral description; {Tools::MCP} and
16
+ # {Tools::RubyLLM} wrap it for the MCP Ruby SDK and RubyLLM (each loaded by its own require).
17
+ module Tools
18
+ # @return [Array<::String>] the keys of every result a tool call returns, in order
19
+ RESULT_KEYS = %w[status code message output errors metadata].freeze
20
+
21
+ module_function
22
+
23
+ # Builds the tool description of one named action.
24
+ #
25
+ # @param action [Class] an +Actionable::Action+ subclass with an +input+ block
26
+ # @param description [::String] what the tool does, written for a model
27
+ # @param name [::String, nil] the tool name; defaults to the action's snake-cased class name
28
+ # @param context [::Hash{::Symbol=>::Proc}] input fields the server fills in, each from a proc taking the source
29
+ # @param annotations [::Hash{::Symbol=>Boolean}] behaviour hints (MCP: read_only, destructive, idempotent, open_world)
30
+ # @return [Actionable::Tools::Definition]
31
+ # @raise [::ArgumentError] when the action cannot be a tool
32
+ def definition(action, description:, name: nil, context: {}, annotations: {})
33
+ Definition.new(action, name: name, description: description, annotations: annotations, context: context)
34
+ end
35
+ end
36
+ end
@@ -0,0 +1,131 @@
1
+ # The actionable-rb namespace; this gem adds {Tools}.
2
+ module Actionable
3
+ # Expose actions as LLM tools.
4
+ module Tools
5
+ RESULT_KEYS: ::Array[::String]
6
+ VERSION: ::String
7
+
8
+ # Builds the tool description of one named action.
9
+ #
10
+ # _@param_ `action` — an +Actionable::Action+ subclass with an +input+ block
11
+ #
12
+ # _@param_ `description` — what the tool does, written for a model
13
+ #
14
+ # _@param_ `name` — the tool name; defaults to the action's snake-cased class name
15
+ #
16
+ # _@param_ `context` — input fields the server fills in, each from a proc taking the source
17
+ #
18
+ # _@param_ `annotations` — behaviour hints (MCP: read_only, destructive, idempotent, open_world)
19
+ def self.definition: (
20
+ Class action,
21
+ description: ::String,
22
+ ?name: ::String?,
23
+ ?context: ::Hash[::Symbol, ::Proc],
24
+ ?annotations: ::Hash[::Symbol, bool]
25
+ ) -> Actionable::Tools::Definition
26
+
27
+ # Wraps a {Definition} as an +MCP::Tool+ subclass for the MCP Ruby SDK.
28
+ module MCP
29
+ HINTS: ::Hash[::Symbol, ::Symbol]
30
+
31
+ # Builds the tool class of one action.
32
+ #
33
+ # _@param_ `action` — an +Actionable::Action+ subclass
34
+ #
35
+ # _@param_ `options` — the keywords of {Tools.definition}
36
+ #
37
+ # _@return_ — an +MCP::Tool+ subclass
38
+ def self.tool: (Class action, **Object options) -> Class
39
+
40
+ # Builds the tool class of a definition.
41
+ #
42
+ # _@param_ `definition`
43
+ #
44
+ # _@return_ — an +MCP::Tool+ subclass
45
+ def self.from: (Actionable::Tools::Definition definition) -> Class
46
+
47
+ # Maps annotation hints to the SDK's keywords.
48
+ #
49
+ # _@param_ `hints`
50
+ #
51
+ # _@return_ — nil when there are no hints
52
+ def self.annotations: (::Hash[::Symbol, bool] hints) -> ::Hash[::Symbol, bool]?
53
+ end
54
+
55
+ # Wraps a {Definition} as a +RubyLLM::Tool+ subclass.
56
+ module RubyLLM
57
+ # Builds the tool class of one action.
58
+ #
59
+ # _@param_ `action` — an +Actionable::Action+ subclass
60
+ #
61
+ # _@param_ `approval` — true makes the chat pause for a decision before the tool runs
62
+ #
63
+ # _@param_ `options` — the keywords of {Tools.definition}
64
+ #
65
+ # _@return_ — a +RubyLLM::Tool+ subclass; construct it with the source handed to the context procs
66
+ def self.tool: (Class action, ?approval: bool, **Object options) -> Class
67
+
68
+ # Builds the tool class of a definition.
69
+ #
70
+ # _@param_ `definition`
71
+ #
72
+ # _@param_ `approval`
73
+ #
74
+ # _@return_ — a +RubyLLM::Tool+ subclass
75
+ def self.from: (Actionable::Tools::Definition definition, ?approval: bool) -> Class
76
+ end
77
+
78
+ # Form-neutral description of one action as a tool: name, description, annotations, schemas and +call+.
79
+ # Immutable once built (AT-I7).
80
+ class Definition
81
+ # _@param_ `action` — an +Actionable::Action+ subclass
82
+ #
83
+ # _@param_ `description`
84
+ #
85
+ # _@param_ `name`
86
+ #
87
+ # _@param_ `context`
88
+ #
89
+ # _@param_ `annotations` — frozen in place (the caller's Hash)
90
+ def initialize: (
91
+ Class action,
92
+ description: ::String,
93
+ name: ::String?,
94
+ context: ::Hash[::Symbol, ::Proc],
95
+ annotations: ::Hash[::Symbol, bool]
96
+ ) -> void
97
+
98
+ # Runs the action for a model's arguments and returns the six-key result envelope (AT-B20, AT-B21). Exceptions
99
+ # the action raises propagate (AT-B22).
100
+ #
101
+ # _@param_ `arguments` — what the model sent, under external (JSON) names
102
+ #
103
+ # _@param_ `source` — handed to each context proc
104
+ #
105
+ # _@return_ — status, code, message, output, errors, metadata
106
+ def call: (::Hash[::Object, ::Object] arguments, ?Object? source) -> ::Hash[::String, ::Object]
107
+
108
+ # _@param_ `result` — an envelope from {#call}
109
+ #
110
+ # _@return_ — true only for a failure (a skip is not an error)
111
+ def error?: (::Hash[::String, ::Object] result) -> bool
112
+
113
+ # _@return_ — the action
114
+ attr_reader action: Class
115
+
116
+ attr_reader name: ::String
117
+
118
+ # _@return_ — as given, not stripped
119
+ attr_reader description: ::String
120
+
121
+ # _@return_ — frozen
122
+ attr_reader annotations: ::Hash[::Symbol, bool]
123
+
124
+ # _@return_ — JSON Schema of the arguments the model sends; frozen (shallowly)
125
+ attr_reader input_schema: ::Hash[::String, ::Object]
126
+
127
+ # _@return_ — JSON Schema of the result envelope {Tools::RESULT_KEYS}; frozen (shallowly)
128
+ attr_reader output_schema: ::Hash[::String, ::Object]
129
+ end
130
+ end
131
+ end
metadata ADDED
@@ -0,0 +1,111 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: actionable-tools
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.0.pre1
5
+ platform: ruby
6
+ authors:
7
+ - Adrian Madrid
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: actionable-rb
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - ">="
17
+ - !ruby/object:Gem::Version
18
+ version: 2.0.0.pre1
19
+ - - "<"
20
+ - !ruby/object:Gem::Version
21
+ version: '3'
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ requirements:
26
+ - - ">="
27
+ - !ruby/object:Gem::Version
28
+ version: 2.0.0.pre1
29
+ - - "<"
30
+ - !ruby/object:Gem::Version
31
+ version: '3'
32
+ - !ruby/object:Gem::Dependency
33
+ name: field_struct-json_schema
34
+ requirement: !ruby/object:Gem::Requirement
35
+ requirements:
36
+ - - ">="
37
+ - !ruby/object:Gem::Version
38
+ version: 1.0.0.pre1
39
+ - - "<"
40
+ - !ruby/object:Gem::Version
41
+ version: '2'
42
+ type: :runtime
43
+ prerelease: false
44
+ version_requirements: !ruby/object:Gem::Requirement
45
+ requirements:
46
+ - - ">="
47
+ - !ruby/object:Gem::Version
48
+ version: 1.0.0.pre1
49
+ - - "<"
50
+ - !ruby/object:Gem::Version
51
+ version: '2'
52
+ - !ruby/object:Gem::Dependency
53
+ name: oj
54
+ requirement: !ruby/object:Gem::Requirement
55
+ requirements:
56
+ - - "~>"
57
+ - !ruby/object:Gem::Version
58
+ version: '3.16'
59
+ type: :runtime
60
+ prerelease: false
61
+ version_requirements: !ruby/object:Gem::Requirement
62
+ requirements:
63
+ - - "~>"
64
+ - !ruby/object:Gem::Version
65
+ version: '3.16'
66
+ description: One form-neutral tool definition built from an action, with thin wrappers
67
+ for the MCP Ruby SDK and RubyLLM. Context fields (identity, station) are filled
68
+ by the server, never by the model.
69
+ email:
70
+ - adrian.madrid@timeworxs.com
71
+ executables: []
72
+ extensions: []
73
+ extra_rdoc_files: []
74
+ files:
75
+ - CHANGELOG.md
76
+ - LICENSE.txt
77
+ - README.md
78
+ - lib/actionable/tools.rb
79
+ - lib/actionable/tools/definition.rb
80
+ - lib/actionable/tools/envelope.rb
81
+ - lib/actionable/tools/input_schema.rb
82
+ - lib/actionable/tools/mcp.rb
83
+ - lib/actionable/tools/output_schema.rb
84
+ - lib/actionable/tools/ruby_llm.rb
85
+ - lib/actionable/tools/version.rb
86
+ - sig/actionable-tools.rbs
87
+ homepage: https://github.com/gliders-rb/gems
88
+ licenses:
89
+ - MIT
90
+ metadata:
91
+ source_code_uri: https://github.com/gliders-rb/gems/tree/main/adapters/actionable-tools
92
+ changelog_uri: https://github.com/gliders-rb/gems/blob/main/adapters/actionable-tools/CHANGELOG.md
93
+ rubygems_mfa_required: 'true'
94
+ rdoc_options: []
95
+ require_paths:
96
+ - lib
97
+ required_ruby_version: !ruby/object:Gem::Requirement
98
+ requirements:
99
+ - - ">="
100
+ - !ruby/object:Gem::Version
101
+ version: '3.3'
102
+ required_rubygems_version: !ruby/object:Gem::Requirement
103
+ requirements:
104
+ - - ">="
105
+ - !ruby/object:Gem::Version
106
+ version: '0'
107
+ requirements: []
108
+ rubygems_version: 3.6.9
109
+ specification_version: 4
110
+ summary: Expose actionable-rb actions as LLM tools (MCP and RubyLLM).
111
+ test_files: []