robot_lab 0.6.1 → 0.6.2

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: 0b6e840221fd580897fea9a5a13e27a9a245977054ed528474eba0dcf205008a
4
- data.tar.gz: 5b430758c71fe3e21136c7805e6770454364a704bae24e203d33cd02173c7ee9
3
+ metadata.gz: 5618a855d768bbcbf613979fd8ccf8ce9a49cf27e1fad3e842355c3203bcdf76
4
+ data.tar.gz: cef1a665af0616abbdb1d92e6326fa11e7efd51dca0a51bd2b72877758a20c5b
5
5
  SHA512:
6
- metadata.gz: 67de4c052378c46c4b11dd45206021a50a495bca1af49302d19e5aca92836bb1e08c00f220011c0781cf1cbdd9af9473881ca22c5dc2858962d04626df7ad4d7
7
- data.tar.gz: de1cd93d4101be13c7881acb1829728f9855c9752a670506ee5d804d5c395b23099d56c7f2512aaf39c5f17b81f4336a9966a23ce98f5805b0a6e98489127c58
6
+ metadata.gz: 30b8395d1dde27a1f9e2137ea1e4d9374d97ee7ac6d1157e75cf037ca8016439e958fe247c8290b2c8250a2ad4e98d93c856290a140b21e1c9c73df6c2f60bf7
7
+ data.tar.gz: 0d73bdb4d4a767e5a412b08bf134731ce04bd9c2634f1073912c10532a1344b3cfbaecb4f02d3b9e449c7b8ad9aa3acb8a42cf582af75f81ebfe23aef1955257
data/CHANGELOG.md CHANGED
@@ -8,6 +8,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ### Changed
12
+
13
+ - **ruby_llm 2.2.0 or newer is required** (`ruby_llm ">= 2.2.0", "< 3"`). ruby_llm 2.2
14
+ replaced `Chat#pending_approvals` / `#pending_inputs` / `#deny` with `#pending_questions`
15
+ and `#decline`; robot_lab now uses the new API (#43).
16
+ - `on_input_request:` receives a `RubyLLM::Question` (`RubyLLM::MCP::InputRequest` is now an
17
+ alias for it), and also answers questions a plain `RubyLLM::Tool` asks with `Tool#ask`.
18
+ `on_tool_approval:` still receives the `RubyLLM::ToolCall`.
19
+ - An MCP server failing mid-call now yields ruby_llm's own error text,
20
+ `{ error: "The <server> MCP server failed: <message>" }`, instead of
21
+ `{ error: "<tool>: <message>" }`. `:tool_call` hooks still see the failure as
22
+ `tool_error` (a `RobotLab::MCPError`).
23
+ - `defaults.yml` ships `ruby_llm.provider: null` instead of `:anthropic`, so robots that name
24
+ no provider keep letting RubyLLM infer it from the model (#113).
25
+
26
+ ### Fixed
27
+
28
+ - A robot built without `provider:` falls back to the configured `ruby_llm.provider`
29
+ (config file or `ROBOT_LAB_RUBY_LLM__PROVIDER`), the same way `model` falls back to
30
+ `ruby_llm.model`. Templates can name a `provider:` in front matter. Precedence:
31
+ constructor, then front matter, then config (#113).
32
+ - With ruby_llm 2.2, runs that paused for a tool approval, an MCP input request or an MCP
33
+ task raised `NoMethodError: undefined method 'pending_approvals'` (#43).
34
+ - README and `docs/` tool examples use ruby_llm 2.x's `parameter :x, description:` DSL
35
+ instead of `param :x, desc:`, and call tools with keywords (`tool.call`, not
36
+ `tool.call({})`) (#35).
37
+
11
38
  ## [0.6.1] - 2026-11-18
12
39
 
13
40
  ### Fixed
data/README.md CHANGED
@@ -343,11 +343,11 @@ tool = RobotLab::Tool.create(name: "fetch_data") do |args|
343
343
  raise IOError, "connection refused"
344
344
  end
345
345
 
346
- result = tool.call({})
346
+ result = tool.call
347
347
  # => "Error (fetch_data): connection refused"
348
348
  ```
349
349
 
350
- This applies to every `RobotLab::Tool` — subclasses and factory tools. (MCP tools are `RubyLLM::MCP::Tool` instances; a `RubyLLM::MCP::Error` raised during one of their calls becomes an `{ error: }` tool result through the robot's tool-call bridge instead.) For critical tools where you want exceptions to propagate, opt out per class:
350
+ This applies to every `RobotLab::Tool` — subclasses and factory tools. (MCP tools are `RubyLLM::MCP::Tool` instances; a server failing one of their calls becomes an `{ error: }` tool result instead, and `:tool_call` hooks see it as `tool_error`.) For critical tools where you want exceptions to propagate, opt out per class:
351
351
 
352
352
  ```ruby
353
353
  class CriticalTool < RobotLab::Tool
@@ -363,7 +363,7 @@ end
363
363
  class Magic8Ball < RubyLLM::Tool
364
364
  description "Consult the mystical Magic 8-Ball for guidance on yes/no questions"
365
365
 
366
- param :question, type: "string", desc: "A yes/no question to ask the oracle"
366
+ parameter :question, type: "string", description: "A yes/no question to ask the oracle"
367
367
 
368
368
  RESPONSES = [
369
369
  { answer: "It is certain", certainty: 0.95, vibe: "positive" },
@@ -552,7 +552,7 @@ robot.run(robot.mcp[:git_hub].prompt("code_review", code: diff), mcp: :inherit)
552
552
  robot.disconnect # closes every server (stopping stdio processes); they reconnect on next use
553
553
  ```
554
554
 
555
- Connection failures are logged, recorded in `robot.mcp_failures` and retried on the next run that selects the server; they are not raised, and one failing server does not stop the others. A `RubyLLM::MCP::Error` during a tool call becomes an `{ error: }` tool result rather than aborting the run. See the [MCP Integration guide](docs/guides/mcp-integration.md), including its "Migrating from 0.3" section.
555
+ Connection failures are logged, recorded in `robot.mcp_failures` and retried on the next run that selects the server; they are not raised, and one failing server does not stop the others. A server failing during a tool call becomes an `{ error: }` tool result rather than aborting the run. See the [MCP Integration guide](docs/guides/mcp-integration.md), including its "Migrating from 0.3" section.
556
556
 
557
557
  ## Message Bus
558
558
 
@@ -54,7 +54,7 @@ defaults:
54
54
 
55
55
  # RubyLLM Configuration Section
56
56
  ruby_llm:
57
- provider: :anthropic
57
+ provider: null # default provider for robots built without provider: (null = let RubyLLM infer it from the model)
58
58
  model: claude-sonnet-4-6
59
59
  assume_model_exists: false # (dep of assume_exists in chat section) set true for Ollama and other local LLM providers
60
60
  # Provider API Keys (null = use env vars directly)
@@ -5,7 +5,8 @@ module RobotLab
5
5
  # Template loading, rendering, and front-matter extraction.
6
6
  #
7
7
  # Owns: @expanded_skills, @pending_agent_skills, @agent_skill_store
8
- # Reads: @chat, @template, @build_context, @name, @name_from_constructor, @description, @local_tools, @mcp_config, @config
8
+ # Reads: @chat, @template, @build_context, @name, @name_from_constructor, @description, @local_tools, @mcp_config, @config, @provider
9
+ # (front-matter provider: goes through Robot#adopt_front_matter_provider)
9
10
  # Contract: called during initialize after assign_identity_ivars and build_effective_config
10
11
  module TemplateRendering
11
12
  # Front matter keys that map to chat configuration methods
@@ -16,7 +17,7 @@ module RobotLab
16
17
 
17
18
  # Front matter keys for robot identity and capabilities.
18
19
  # Note: uses `robot_name` because PM::Metadata reserves `name` for the filename.
19
- FRONT_MATTER_EXTRA_KEYS = %i[tools mcp robot_name description skills].freeze
20
+ FRONT_MATTER_EXTRA_KEYS = %i[tools mcp robot_name description skills provider].freeze
20
21
 
21
22
  # Apply a prompt_manager template to the robot's chat
22
23
  #
@@ -245,6 +246,8 @@ module RobotLab
245
246
  # @param metadata [PM::Metadata] front matter metadata
246
247
  # @param extras [Hash] accumulator hash
247
248
  def accumulate_extras(metadata, extras)
249
+ extras[:provider] = metadata.provider if metadata.respond_to?(:provider) && metadata.provider
250
+
248
251
  if metadata.respond_to?(:robot_name) && metadata.robot_name
249
252
  extras[:robot_name] = metadata.robot_name.to_s
250
253
  end
@@ -265,6 +268,8 @@ module RobotLab
265
268
  #
266
269
  # @param extras [Hash] accumulated extras from skills + main template
267
270
  def apply_accumulated_extras(extras)
271
+ adopt_front_matter_provider(extras[:provider])
272
+
268
273
  if extras[:robot_name] && !@name_from_constructor
269
274
  @name = extras[:robot_name]
270
275
  end
@@ -285,6 +290,8 @@ module RobotLab
285
290
  # Constructor-provided values take precedence over frontmatter.
286
291
  # :reek:FeatureEnvy -- copying front-matter metadata fields into this robot's ivars is the method's purpose.
287
292
  def apply_front_matter_extras(metadata)
293
+ adopt_front_matter_provider(metadata.provider) if metadata.respond_to?(:provider)
294
+
288
295
  if metadata.respond_to?(:robot_name) && metadata.robot_name && !@name_from_constructor
289
296
  @name = metadata.robot_name.to_s
290
297
  end
@@ -10,9 +10,9 @@ module RobotLab
10
10
  # execution of such tools (RobotLab::Tool runs them itself in #call),
11
11
  # and turns an MCP transport failure mid-call into an error result so
12
12
  # the model can recover instead of the run aborting.
13
- # - The settlement loop answers what ruby_llm pauses a run for: tool
14
- # calls that require approval, MCP input requests (elicitation), and
15
- # long-running MCP tasks. A run never returns half-finished.
13
+ # - The settlement loop answers what ruby_llm pauses a run for: the
14
+ # questions in Chat#pending_questions (tool calls that require
15
+ # approval, MCP input requests, Tool#ask) and long-running MCP tasks. A run never returns half-finished.
16
16
  #
17
17
  # Owns: nothing (uses @chat, @tool_approval, @on_tool_approval, @on_input_request)
18
18
  # Reads: @name
@@ -40,7 +40,8 @@ module RobotLab
40
40
  # Run :tool_call hooks around a chat-executed tool call. Yields to the
41
41
  # chat's own execution; the PAUSED sentinel it returns for approvals,
42
42
  # input requests and tasks passes through untouched.
43
- # :reek:TooManyStatements -- context build, hook wrap and the MCP rescue are one guarded dispatch.
43
+ # :reek:TooManyStatements :reek:FeatureEnvy -- context build, hook wrap and the MCP rescue are one guarded
44
+ # dispatch that fills the hook context.
44
45
  def bridge_tool_call(tool_call)
45
46
  tool = @chat.tools[tool_call.name.to_sym]
46
47
  return yield if tool.nil? || tool.is_a?(RobotLab::Tool)
@@ -52,6 +53,7 @@ module RobotLab
52
53
  registries: scope[:registries] || hook_registries,
53
54
  per_run_hooks: scope[:per_run_hooks]) do
54
55
  context.tool_result = yield
56
+ context.tool_error = mcp_failure_error(context.tool_result)
55
57
  rescue RubyLLM::MCP::Error => e
56
58
  context.tool_error = e
57
59
  context.tool_result = { error: "#{tool.name}: #{e.message}" }
@@ -59,6 +61,19 @@ module RobotLab
59
61
  context.tool_result
60
62
  end
61
63
 
64
+ # ruby_llm (>= 2.2) catches a server failing an MCP call itself and
65
+ # returns the error Hash as the result, so the rescue in
66
+ # #bridge_tool_call never sees it. Surface it to :tool_call hooks as an
67
+ # MCPError all the same.
68
+ #
69
+ # @param result [Object] what the chat's tool execution returned
70
+ # @return [RobotLab::MCPError, nil]
71
+ def mcp_failure_error(result)
72
+ return unless result.is_a?(RubyLLM::MCP::Outages::Failure)
73
+
74
+ MCPError.new(result[:error].to_s)
75
+ end
76
+
62
77
  # Keep completing the chat until nothing waits on the outside world:
63
78
  # decide approvals, answer input requests, wait on tasks, complete again.
64
79
  #
@@ -67,20 +82,27 @@ module RobotLab
67
82
  def settle_pending_tool_calls(response, &)
68
83
  deadline = nil
69
84
  while @chat.waiting?
70
- decide_pending_approvals
71
- answer_pending_inputs
85
+ settle_pending_questions
72
86
  deadline = wait_for_mcp_tasks(deadline)
73
87
  response = @chat.complete(&)
74
88
  end
75
89
  response
76
90
  end
77
91
 
78
- def decide_pending_approvals
79
- @chat.pending_approvals.each do |tool_call|
80
- approve_tool_call?(tool_call) ? @chat.approve(tool_call) : @chat.deny(tool_call)
92
+ # Answer every question the chat waits on: approvals go through the
93
+ # approval policy; the rest (MCP input requests, Tool#ask) go to
94
+ # on_input_request.
95
+ def settle_pending_questions
96
+ @chat.pending_questions.each do |question|
97
+ question.approval? ? decide_approval(question) : settle_input_request(question)
81
98
  end
82
99
  end
83
100
 
101
+ # @param question [RubyLLM::Question] an approval question
102
+ def decide_approval(question)
103
+ approve_tool_call?(question.tool_call) ? @chat.approve(question) : @chat.decline(question)
104
+ end
105
+
84
106
  # Approval policy: an on_tool_approval Proc decides; else tool_approval
85
107
  # :approve allows; else deny with a warning naming the two settings.
86
108
  #
@@ -97,14 +119,10 @@ module RobotLab
97
119
  false
98
120
  end
99
121
 
100
- def answer_pending_inputs
101
- @chat.pending_inputs.each { |request| settle_input_request(request) }
102
- end
103
-
104
122
  # An on_input_request Proc answers a request with a Hash of field
105
123
  # values (or +true+ to accept a URL request); anything else declines.
106
124
  #
107
- # @param request [RubyLLM::MCP::InputRequest]
125
+ # @param request [RubyLLM::Question] a pending question that is not an approval
108
126
  def settle_input_request(request)
109
127
  answer = @on_input_request&.call(request)
110
128
  case answer
@@ -155,8 +155,9 @@ module RobotLab
155
155
  # on_tool_approval is given: :deny (default) or :approve
156
156
  # @param on_tool_approval [Proc, nil] called with each RubyLLM::ToolCall that requires approval;
157
157
  # a truthy return approves it
158
- # @param on_input_request [Proc, nil] called with each RubyLLM::MCP::InputRequest an MCP server
159
- # raises; return a Hash of field values (or true for a URL request) to answer, anything else declines
158
+ # @param on_input_request [Proc, nil] called with each RubyLLM::Question a tool call waits on that is
159
+ # not an approval (MCP input requests, Tool#ask); return a Hash of field values (or true for a
160
+ # URL request) to answer, anything else declines
160
161
  # @param mcp_discovery [Boolean] select only the MCP servers relevant to each message (see MCP::ServerDiscovery)
161
162
  # @param enable_cache [Boolean] whether to enable semantic caching
162
163
  # @param bus [TypedBus::MessageBus, nil] optional message bus for inter-robot communication
@@ -231,8 +232,12 @@ module RobotLab
231
232
  resolved_model = @config.model || lab_config.ruby_llm.model
232
233
  chat_kwargs = { model: resolved_model }
233
234
 
234
- # RubyLLM auto-sets assume_model_exists for local providers when provider is specified.
235
- @provider = provider
235
+ # Provider precedence: constructor > template front matter (applied
236
+ # later, see TemplateRendering#adopt_front_matter_provider) > config.
237
+ # A named provider routes the model there without a registry lookup,
238
+ # so assume_model_exists is set for it whatever its source.
239
+ @provider_from_constructor = !provider.nil?
240
+ @provider = resolve_provider(provider, lab_config)
236
241
  if @provider
237
242
  chat_kwargs[:provider] = @provider
238
243
  chat_kwargs[:assume_model_exists] = true
@@ -556,6 +561,30 @@ module RobotLab
556
561
  "(e.g. RobotLab.build(local_tools: [MyTool.new]))."
557
562
  end
558
563
 
564
+ # The provider a robot starts with: the constructor's, else the
565
+ # configured ruby_llm.provider (nil when neither names one). A configured
566
+ # String (e.g. from ROBOT_LAB_RUBY_LLM__PROVIDER) becomes a Symbol.
567
+ #
568
+ # @param provider [String, Symbol, nil] the constructor argument
569
+ # @param lab_config [RobotLab::Config]
570
+ # @return [String, Symbol, nil]
571
+ def resolve_provider(provider, lab_config)
572
+ return provider unless provider.nil?
573
+
574
+ configured = lab_config.ruby_llm.provider
575
+ configured.to_s.empty? ? nil : configured.to_sym
576
+ end
577
+
578
+ # A template's +provider:+ replaces the configured provider, but never
579
+ # one passed to the constructor.
580
+ #
581
+ # @param value [String, Symbol, nil] the front matter provider
582
+ def adopt_front_matter_provider(value)
583
+ return if @provider_from_constructor || value.to_s.empty?
584
+
585
+ @provider = value.to_sym
586
+ end
587
+
559
588
  # :reek:LongParameterList :reek:TooManyStatements -- one keyword and one assignment per identity ivar;
560
589
  # a hash would lose keyword checking.
561
590
  def assign_identity_ivars(name:, template:, system_prompt:, context:, description:,
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module RobotLab
4
- VERSION = "0.6.1"
4
+ VERSION = "0.6.2"
5
5
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: robot_lab
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.6.1
4
+ version: 0.6.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Dewayne VanHoozer
@@ -43,7 +43,7 @@ dependencies:
43
43
  requirements:
44
44
  - - ">="
45
45
  - !ruby/object:Gem::Version
46
- version: 2.1.1
46
+ version: 2.2.0
47
47
  - - "<"
48
48
  - !ruby/object:Gem::Version
49
49
  version: '3'
@@ -53,7 +53,7 @@ dependencies:
53
53
  requirements:
54
54
  - - ">="
55
55
  - !ruby/object:Gem::Version
56
- version: 2.1.1
56
+ version: 2.2.0
57
57
  - - "<"
58
58
  - !ruby/object:Gem::Version
59
59
  version: '3'