ruby_llm-code_mode 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65329e122014fe96a542cab62f9eb0bb002f3c1ac9f53fae0f5d7b384183433e
-  data.tar.gz: c9f4272b1b65da90128fb4a62d211a47606814091ee07095fe55535126aea154
+  metadata.gz: fb23ad192879e9ce6bcac0204c62c44ad068943dadd5e46a3a2e82bd177411c7
+  data.tar.gz: 39b52ca9cf5f733224a1a8a999ae50cbe091467819d86f63a7c38610be665233
 SHA512:
-  metadata.gz: 7f31a40ab23606bfd6f2c5799ff90c780c514eac95bd3f63d4e4ef933c97adf38ae7d61ca65fe4dc53ba472f8ed38a8a64ae3fcf286656c7694ac2c8c9842817
-  data.tar.gz: 1316c738fba0e23e1dc0db07ea63d926cb535bd082cf649a0511c68639e86e777e9077cbe7f1a9973b05e110f023ba9d4d21df3638602956525ca33a2d8e3602
+  metadata.gz: 6e41645fd4404b2a70e3a3606ab6b1aba047e20e1e610278ddaac8ae85b8512d0c0af134a897fface831e7a1547b77610444bbb8dffb6a80b468bf4a79f09af2
+  data.tar.gz: 60adf578f5deafbd36822e14179e8bcd74856ba6d4b598910cc2be40520ef577f8fd534ffde0ecad2d5ab5c512ff2ac2b98ae60f8c66b0cc0dfa8253bde5b609

data/README.md

@@ -22,21 +22,41 @@ gem "ruby_llm-code_mode"
 
 ## Usage
 
-Define a tool class, declare the host folders the sandbox may see, and give it to
-your chat:
+Define a tool class, declare the host folders the sandbox may see, bind the
+host tools and MCP servers the code may call, and give it to your chat:
 
 ```ruby
 require "ruby_llm"
 require "ruby_llm/code_mode"
 
+# A host tool the sandboxed code can call with SB.call("notes", note: "...").
+class Notes < RubyLLM::Tool
+  description "Records a finding in the analysis log"
+
+  parameter :note, type: "string", description: "The finding to record"
+
+  def execute(note:)
+    # host-side write: log file, HTTP call, database query, ...
+    { recorded: note }
+  end
+end
+
+# An MCP server whose tools become callable from inside the sandbox too.
+docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
+
 class Analytics < RubyLLM::CodeMode
   mount    source: "data/input", dest: "/data",      description: "CSV files with the raw data (read only)"
   mount_rw source: "workspace",  dest: "/workspace", description: "Write generated reports and artifacts here"
+
+  tools Notes                   # one, several (`tools A, B`) or arrays (`tools [A, B]`)
+  mcps   docs                   # one, several (`mcps A, B`) or arrays — classes work too
 end
 
 chat = RubyLLM.chat
 chat.with_tools(Analytics)
-chat.ask "Compute the total sales per month from the CSVs in /data and save the report to /workspace/report.md"
+chat.ask "Compute the total sales per month from the CSVs in /data, save the " \
+         "report to /workspace/report.md, record the biggest finding in the " \
+         "notes log and check the Azure docs for the storage API you used"
 ```
 
 ### What the model sees
@@ -179,6 +199,36 @@ result[:error]      # => true when the tool reported a failure
 The sandbox itself never sees the network — every `SB.call` performs the MCP
 request on the host. A runnable example lives in `sample/ruby_llm_mcp/`.
 
+### Per-instance tools and servers
+
+Class-level `tools`/`mcps` bind once for every instance of the class. When the
+same tool class needs a different toolset per chat — per-user credentials, a
+server list composed at runtime — bind additions on the instance instead:
+
+```ruby
+tool = Analytics.new
+tool.add_tools(UserSearch.new(user: current_user))   # ready instance (classes work too)
+tool.add_mcps(user_linear)                           # server instance, class or array
+
+chat = RubyLLM.chat
+chat.with_tools(tool)   # the description already includes the additions
+chat.ask "Search the docs and log the findings"
+tool.execute(code: 'SB.call("user_search", q: "...")')
+```
+
+- `add_tools` accepts the same forms as `tools`: classes, ready instances,
+  several at once, arrays and `"name" => tool` pairs. Names may not collide
+  with the class-level bindings or each other, and the 64-tool limit counts
+  both levels together.
+- `add_mcps` accepts the same forms as `mcps`; the servers' tools bind into
+  this instance only — other instances and the class itself are unaffected.
+- Both are all-or-nothing: on any failure nothing is bound.
+- The instance description includes the additions, so register the tool with
+  the chat after calling them.
+- The sandbox is configured on the first execution: after that,
+  `add_tools`/`add_mcps` raise — create a new instance instead. Instances
+  without additions share the class configuration.
+
 ### Sandbox limits
 
 Defaults: `timeout_ms: 30_000` (wall clock), `fuel_ms: 10_000` (CPU budget).

data/lib/ruby_llm/code_mode.rb

@@ -5,7 +5,7 @@ require "security_box"
 
 module RubyLLM
   class CodeMode < Tool
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
 
     DEFAULT_TIMEOUT_MS = 30_000
     DEFAULT_FUEL_MS = 10_000
@@ -53,6 +53,221 @@ module RubyLLM
 
     McpEntry = Struct.new(:name, :mcp, :instructions, keyword_init: true)
 
+    # Shared registration and rendering core, parameterized by the target
+    # collections: the class-level DSL (tools/mcps) and the instance-level API
+    # (add_tools/add_mcps) run the exact same validation and rollback logic,
+    # only over different hashes/arrays.
+    module Registry
+      EMPTY = {}.freeze
+
+      class << self
+        # Binds tools into `target` (a name => ToolEntry hash). Accepts tool
+        # classes/instances, arrays of them, and "name" => tool pairs (hash
+        # arguments or kwargs). All-or-nothing: on any failure `target` is
+        # restored and the error re-raised. `reserved` lists names already
+        # taken elsewhere (e.g. the class-level bindings for instance
+        # additions); duplicates against it raise.
+        def register_tools(target, args, kwargs, reserved: EMPTY)
+          snapshot = target.dup
+          begin
+            args.flatten(1).each do |item|
+              if item.is_a?(Hash)
+                item.each { |name, bound| add_tool(target, bound, name.to_s, reserved) }
+              else
+                add_tool(target, item, nil, reserved)
+              end
+            end
+            kwargs.each { |name, bound| add_tool(target, bound, name.to_s, reserved) }
+          rescue StandardError
+            target.replace(snapshot)
+            raise
+          end
+          target
+        end
+
+        # Connects MCP server(s) and binds all their tools into
+        # `target_tools`/`target_mcps`. All-or-nothing across both
+        # collections.
+        def register_mcps(target_tools, target_mcps, servers, inputs, reserved: EMPTY)
+          snapshot_tools = target_tools.dup
+          snapshot_mcps = target_mcps.dup
+          flat = servers.flatten(1)
+          raise ArgumentError, "expected at least one RubyLLM::MCP server" if flat.empty?
+          unless inputs.empty? || flat.all?(Class)
+            raise ArgumentError, "inputs only apply when passing RubyLLM::MCP classes"
+          end
+
+          normalize_mcp_servers(flat, inputs).each do |server|
+            bind_mcp_server(target_tools, target_mcps, server, reserved)
+          end
+          target_mcps
+        rescue StandardError
+          target_tools.replace(snapshot_tools)
+          target_mcps.replace(snapshot_mcps)
+          raise
+        end
+
+        def rpc_handlers(tools)
+          tools.transform_values { |entry| ->(args) { call_bound_tool(entry, args) } }
+        end
+
+        def tools_section(tools)
+          return nil if tools.empty?
+
+          [
+            "## Host tools (call with SB.call)",
+            HOST_TOOLS_INTRO.rstrip,
+            *tools.values.flat_map { |entry| tool_lines(entry) }
+          ].join("\n")
+        end
+
+        def server_notes_section(mcps)
+          notes = mcps.filter_map do |entry|
+            instructions = entry.instructions.to_s
+            next if instructions.empty?
+
+            "- **#{entry.name}** — #{instructions}"
+          end
+          return nil if notes.empty?
+
+          ["## Server notes", *notes].join("\n")
+        end
+
+        private
+
+        def add_tool(target, bound, name, reserved)
+          instance = normalize_bound_tool(bound)
+          if instance.is_a?(RubyLLM::CodeMode)
+            raise ArgumentError, "cannot bind a RubyLLM::CodeMode inside another CodeMode"
+          end
+
+          name = (name || tool_binding_name(instance)).to_s
+          raise ArgumentError, "tool name must be a non-empty String" if name.empty?
+          if target.key?(name) || reserved.key?(name)
+            raise ArgumentError, "tool name #{name.inspect} is already bound"
+          end
+          total = target.size + reserved.size
+          if total >= MAX_TOOLS
+            raise ArgumentError, "too many tools (#{total + 1}); the limit is #{MAX_TOOLS}"
+          end
+
+          target[name] = ToolEntry.new(name: name, tool: instance)
+        end
+
+        def normalize_bound_tool(bound)
+          if bound.is_a?(Class)
+            unless bound <= RubyLLM::Tool
+              raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
+            end
+
+            bound.new
+          elsif bound.is_a?(RubyLLM::Tool)
+            bound
+          else
+            raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
+          end
+        end
+
+        # Leaf-only name derivation, like .tool_name — the guest has no use
+        # for the RubyLLM namespace ("MyApp::Tools::Search" binds as "search").
+        def leaf_tool_name(klass)
+          leaf = klass.name.to_s.split('::').last
+          return "" unless leaf
+
+          RubyLLM::Support::Utils.underscore(leaf).delete_suffix('_tool')
+        end
+
+        # Regular tools keep the leaf-only derivation; MCP tools carry their
+        # own (server) name, which is what they bind under inside the sandbox.
+        def tool_binding_name(instance)
+          return instance.name.to_s if instance.respond_to?(:server_name)
+
+          leaf_tool_name(instance.class)
+        end
+
+        def call_bound_tool(entry, args)
+          unless args.is_a?(Hash)
+            raise ArgumentError,
+                  "tool #{entry.name.inspect} expects a hash of arguments, got #{args.class}"
+          end
+
+          normalize_result(entry.tool.call(**args))
+        end
+
+        # MCP tools return RubyLLM::MCP::Result objects; SecurityBox JSON
+        # round-trips handler returns, so give the guest plain data instead
+        # of an inspect string.
+        def normalize_result(value)
+          return value unless defined?(RubyLLM::MCP::Result) && value.is_a?(RubyLLM::MCP::Result)
+
+          { text: value.text, structured: value.structured, error: value.error? }
+        end
+
+        def normalize_mcp_servers(servers, inputs)
+          unless defined?(RubyLLM::MCP)
+            raise ArgumentError,
+                  "RubyLLM::MCP is not available; mcps needs a ruby_llm version with MCP support"
+          end
+
+          servers.map do |server|
+            case server
+            when Class
+              unless server <= RubyLLM::MCP
+                raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
+              end
+
+              server.new(**inputs)
+            when RubyLLM::MCP
+              server
+            else
+              raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
+            end
+          end
+        end
+
+        def bind_mcp_server(target_tools, target_mcps, server, reserved)
+          # Fetching .tools connects to the server; snapshot the instructions
+          # right after, so description builds never touch the network.
+          tools_list = server.tools
+          target_mcps << McpEntry.new(
+            name: server.name.to_s, mcp: server, instructions: server.instructions.to_s
+          )
+          tools_list.each { |tool| bind_mcp_tool(target_tools, server, tool, reserved) }
+        end
+
+        def bind_mcp_tool(target_tools, server, tool, reserved)
+          name = tool_binding_name(tool)
+          if (target_tools.key?(name) || reserved.key?(name)) && !server.name.to_s.empty?
+            name = "#{server.name}_#{name}"
+          end
+          add_tool(target_tools, tool, name, reserved)
+        end
+
+        def tool_lines(entry)
+          line = "- `#{entry.name}`"
+          description = entry.tool.description.to_s
+          line += " — #{description}" unless description.empty?
+
+          [line, *param_lines(entry.tool).map { |param| "  #{param}" }]
+        end
+
+        def param_lines(tool)
+          schema = tool.parameters_schema || {}
+          properties = schema["properties"] || {}
+          required = schema["required"] || []
+
+          properties.filter_map do |param, spec|
+            spec ||= {}
+            status = required.include?(param) ? "required" : "optional"
+            line = "- `#{param}` (#{spec["type"] || "string"}, #{status})"
+            description = spec["description"].to_s
+            line += " — #{description}" unless description.empty?
+            line
+          end
+        end
+      end
+    end
+
     class << self
       def tool_name
         leaf = name.to_s.split('::').last
@@ -86,21 +301,7 @@ module RubyLLM
       def tools(*args, **kwargs)
         return @tools ||= {} if args.empty? && kwargs.empty?
 
-        snapshot = @tools.dup
-        begin
-          args.flatten(1).each do |item|
-            if item.is_a?(Hash)
-              item.each { |name, bound| add_tool(bound, name.to_s) }
-            else
-              add_tool(item, nil)
-            end
-          end
-          kwargs.each { |name, bound| add_tool(bound, name.to_s) }
-        rescue StandardError
-          instance_variable_set(:@tools, snapshot)
-          raise
-        end
-        tools
+        Registry.register_tools(tools, args, kwargs)
       end
 
       # Connects MCP server(s) and binds all their tools into the sandbox:
@@ -126,20 +327,7 @@ module RubyLLM
       def mcps(*servers, **inputs)
         return @mcps ||= [] if servers.empty? && inputs.empty?
 
-        flat = servers.flatten(1)
-        raise ArgumentError, "expected at least one RubyLLM::MCP server" if flat.empty?
-        unless inputs.empty? || flat.all?(Class)
-          raise ArgumentError, "inputs only apply when passing RubyLLM::MCP classes"
-        end
-
-        snapshot_tools = tools.dup
-        snapshot_mcps = mcps.dup
-        normalize_mcp_servers(flat, inputs).each { |server| bind_mcp_server(server) }
-        mcps
-      rescue StandardError
-        instance_variable_set(:@tools, snapshot_tools)
-        instance_variable_set(:@mcps, snapshot_mcps)
-        raise
+        Registry.register_mcps(tools, mcps, servers, inputs)
       end
 
       def mounts
@@ -151,18 +339,21 @@ module RubyLLM
           timeout_ms: DEFAULT_TIMEOUT_MS,
           fuel_ms: DEFAULT_FUEL_MS,
           mounts: mounts.map(&:payload),
-          rpcs: build_rpcs
+          rpcs: Registry.rpc_handlers(tools)
         )
       end
 
-      def build_description
+      # Builds the description the model sees. `extra_tools`/`extra_mcps`
+      # carry the per-instance additions (see #add_tools/#add_mcps); with no
+      # extras the output is identical to the class-level description.
+      def build_description(extra_tools: {}, extra_mcps: [])
         read_only, read_write = mounts.partition { |m| m.mode == :read_only }
         [
           FIXED_DESCRIPTION.rstrip,
           folder_section("## Read-only folders (readable, never writable)", read_only),
           folder_section("## Read-write folders (readable and writable)", read_write),
-          tools_section,
-          server_notes_section
+          Registry.tools_section(tools.merge(extra_tools)),
+          Registry.server_notes_section(mcps + extra_mcps)
         ].compact.join("\n\n")
       end
 
@@ -202,113 +393,6 @@ module RubyLLM
               "Invalid mount #{source.inspect} => #{dest.inspect}: #{e.message}"
       end
 
-      def add_tool(bound, name)
-        instance = normalize_bound_tool(bound)
-        if instance.is_a?(RubyLLM::CodeMode)
-          raise ArgumentError, "cannot bind a RubyLLM::CodeMode inside another CodeMode"
-        end
-
-        name = (name || tool_binding_name(instance)).to_s
-        raise ArgumentError, "tool name must be a non-empty String" if name.empty?
-        raise ArgumentError, "tool name #{name.inspect} is already bound" if tools.key?(name)
-        if tools.size >= MAX_TOOLS
-          raise ArgumentError, "too many tools (#{tools.size + 1}); the limit is #{MAX_TOOLS}"
-        end
-
-        tools[name] = ToolEntry.new(name: name, tool: instance)
-      end
-
-      def normalize_bound_tool(bound)
-        if bound.is_a?(Class)
-          unless bound <= RubyLLM::Tool
-            raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
-          end
-
-          bound.new
-        elsif bound.is_a?(RubyLLM::Tool)
-          bound
-        else
-          raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
-        end
-      end
-
-      # Leaf-only name derivation, like .tool_name — the guest has no use
-      # for the RubyLLM namespace ("MyApp::Tools::Search" binds as "search").
-      def leaf_tool_name(klass)
-        leaf = klass.name.to_s.split('::').last
-        return "" unless leaf
-
-        RubyLLM::Support::Utils.underscore(leaf).delete_suffix('_tool')
-      end
-
-      # Regular tools keep the leaf-only derivation; MCP tools carry their
-      # own (server) name, which is what they bind under inside the sandbox.
-      def tool_binding_name(instance)
-        return instance.name.to_s if instance.respond_to?(:server_name)
-
-        leaf_tool_name(instance.class)
-      end
-
-      def build_rpcs
-        tools.transform_values { |entry| ->(args) { call_bound_tool(entry, args) } }
-      end
-
-      def call_bound_tool(entry, args)
-        unless args.is_a?(Hash)
-          raise ArgumentError,
-                "tool #{entry.name.inspect} expects a hash of arguments, got #{args.class}"
-        end
-
-        normalize_result(entry.tool.call(**args))
-      end
-
-      # MCP tools return RubyLLM::MCP::Result objects; SecurityBox JSON
-      # round-trips handler returns, so give the guest plain data instead
-      # of an inspect string.
-      def normalize_result(value)
-        return value unless defined?(RubyLLM::MCP::Result) && value.is_a?(RubyLLM::MCP::Result)
-
-        { text: value.text, structured: value.structured, error: value.error? }
-      end
-
-      def normalize_mcp_servers(servers, inputs)
-        unless defined?(RubyLLM::MCP)
-          raise ArgumentError,
-                "RubyLLM::MCP is not available; mcps needs a ruby_llm version with MCP support"
-        end
-
-        servers.map do |server|
-          case server
-          when Class
-            unless server <= RubyLLM::MCP
-              raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
-            end
-
-            server.new(**inputs)
-          when RubyLLM::MCP
-            server
-          else
-            raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
-          end
-        end
-      end
-
-      def bind_mcp_server(server)
-        # Fetching .tools connects to the server; snapshot the instructions
-        # right after, so description builds never touch the network.
-        tools_list = server.tools
-        mcps << McpEntry.new(
-          name: server.name.to_s, mcp: server, instructions: server.instructions.to_s
-        )
-        tools_list.each { |tool| bind_mcp_tool(server, tool) }
-      end
-
-      def bind_mcp_tool(server, tool)
-        name = tool_binding_name(tool)
-        name = "#{server.name}_#{name}" if tools.key?(name) && !server.name.to_s.empty?
-        add_tool(tool, name)
-      end
-
       def folder_section(header, entries)
         return nil if entries.empty?
 
@@ -319,54 +403,37 @@ module RubyLLM
         end
         [header, *lines].join("\n")
       end
+    end
 
-      def tools_section
-        return nil if tools.empty?
-
-        [
-          "## Host tools (call with SB.call)",
-          HOST_TOOLS_INTRO.rstrip,
-          *tools.values.flat_map { |entry| tool_lines(entry) }
-        ].join("\n")
-      end
-
-      def server_notes_section
-        notes = mcps.filter_map do |entry|
-          instructions = entry.instructions.to_s
-          next if instructions.empty?
-
-          "- **#{entry.name}** — #{instructions}"
-        end
-        return nil if notes.empty?
-
-        ["## Server notes", *notes].join("\n")
-      end
-
-      def tool_lines(entry)
-        line = "- `#{entry.name}`"
-        description = entry.tool.description.to_s
-        line += " — #{description}" unless description.empty?
+    parameter :code, description: "Complete Ruby script to execute in the sandbox"
 
-        [line, *param_lines(entry.tool).map { |param| "  #{param}" }]
-      end
+    # Binds more host tools onto this specific instance, on top of the
+    # class-level ones. Accepts the same forms as the class-level .tools:
+    # classes, ready instances, several at once, arrays, and
+    # "name" => tool pairs (hash or kwargs). Instances of the same class are
+    # unaffected, and the additions show up in this instance's description,
+    # so chats built after the call expose them to the model. Fails fast and
+    # rolls everything back; once the first execution happened the sandbox is
+    # already built and further additions raise.
+    def add_tools(*args, **kwargs)
+      ensure_extendable!
+
+      Registry.register_tools(instance_tools, args, kwargs, reserved: self.class.tools)
+    end
 
-      def param_lines(tool)
-        schema = tool.parameters_schema || {}
-        properties = schema["properties"] || {}
-        required = schema["required"] || []
+    # Connects MCP server(s) onto this specific instance, on top of the
+    # class-level ones. Same forms and fail-fast semantics as .mcps
+    # (instances, classes with their declared inputs, arrays); the servers'
+    # tools bind into this instance only. Raises after the first execution.
+    def add_mcps(*servers, **inputs)
+      ensure_extendable!
 
-        properties.filter_map do |param, spec|
-          spec ||= {}
-          status = required.include?(param) ? "required" : "optional"
-          line = "- `#{param}` (#{spec["type"] || "string"}, #{status})"
-          description = spec["description"].to_s
-          line += " — #{description}" unless description.empty?
-          line
-        end
-      end
+      Registry.register_mcps(instance_tools, instance_mcps, servers, inputs, reserved: self.class.tools)
     end
 
-    parameter :code, description: "Complete Ruby script to execute in the sandbox"
+    def description
+      self.class.build_description(extra_tools: instance_tools, extra_mcps: instance_mcps)
+    end
 
     def execute(code:)
       format_result(sandbox.eval(code))
@@ -376,8 +443,38 @@ module RubyLLM
 
     private
 
+    def ensure_extendable!
+      return unless instance_variable_defined?(:@sandbox)
+
+      raise ArgumentError,
+            "cannot add tools or MCP servers after the first execution; " \
+            "create a new #{self.class.name} instance instead"
+    end
+
+    def instance_tools
+      @instance_tools ||= {}
+    end
+
+    def instance_mcps
+      @instance_mcps ||= []
+    end
+
+    # Instances without additions share the class configuration; instances
+    # with additions build their own, merging the class rpcs with the
+    # instance ones (names cannot collide — the registrations validate that).
+    def configuration
+      return self.class.configuration if instance_tools.empty? && instance_mcps.empty?
+
+      @configuration ||= SecurityBox::Configuration.build(
+        timeout_ms: DEFAULT_TIMEOUT_MS,
+        fuel_ms: DEFAULT_FUEL_MS,
+        mounts: self.class.mounts.map(&:payload),
+        rpcs: self.class.configuration.rpcs.merge(Registry.rpc_handlers(instance_tools))
+      )
+    end
+
     def sandbox
-      @sandbox ||= SecurityBox::Sandbox.new(self.class.configuration)
+      @sandbox ||= SecurityBox::Sandbox.new(configuration)
     end
 
     def format_result(result)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-code_mode
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Juneira