ruby_llm-code_mode 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d933b7782ef9b21eb6c9c704630a456b1aa96ffecc52e4a258aa50fd99e09ebf
-  data.tar.gz: d006d9fbac9d85b569a0978f5bf74cca9430ffe8bf7ba47c526a83ecdb52b7ac
+  metadata.gz: 99df9f45b17d0bfb00c9251a705350b87e17bc0d35388284b7d9968afe0945e9
+  data.tar.gz: bad8594e60eff854ad3d891a12714e1cc879f7015ea57077b28afc9920239715
 SHA512:
-  metadata.gz: 0ce747225815a3dd6a9aeccc8ccbb74ac64d9a24e7716797941d75afb009e55c7a56a899abafaeac5a490ad7a921ce0c771955ced03d72861f9472c42f3a2c13
-  data.tar.gz: e62fdd4dbe81c6dd7034ea4e27d1ff18c0aa2bf22d83ab58a94d35e1b51fc045db31e73fd4a560c13ffc5615d8e800cdb83be2f0c38c704c1a8e9c767fec97cd
+  metadata.gz: 3b32708303afcbe27574ee5bf9504168e0a93021cf06f62ce0065bd44ee20a06199c21825791946bd27c394279f9bcf9e20f53f62367750942e760b14ddace7f
+  data.tar.gz: d5efdf5b03124ba97ff9ba07f0f1db87c7b5aeb2de3edd99619e294207ded741ed562635db4a2224f39acb1cd601d8cdbcd43751d7a4f6210a96cb4784dbd95e

data/README.md

@@ -48,7 +48,9 @@ a fixed description built from the declared mounts:
   from the host, with a private `/work` scratch directory wiped between
   executions and no state carried over between runs;
 - a **Read-only folders** section listing each `mount` as `` `/guest/path` — description``;
-- a **Read-write folders** section listing each `mount_rw`.
+- a **Read-write folders** section listing each `mount_rw`;
+- a **Host tools** section listing every bound `RubyLLM::Tool` with its
+  parameters, when any are bound with `tool`.
 
 The single parameter is `code` — a complete, self-contained Ruby script.
 
@@ -68,6 +70,8 @@ A JSON object sent back to the model:
 ```ruby
 mount    source: host_path, dest: guest_path, description: "..."  # read-only
 mount_rw source: host_path, dest: guest_path, description: "..." # read-write
+tool     SomeRubyLLMTool                                          # host tool
+tool     "name" => SomeRubyLLMTool                                # explicit name
 ```
 
 - `source:` — folder on the host machine, relative to the process working
@@ -75,9 +79,56 @@ mount_rw source: host_path, dest: guest_path, description: "..." # read-write
 - `dest:` — absolute, normalized path inside the sandbox (may not overlap
   the reserved `/work`, `/usr` or `/src` trees, and must be unique).
 - `description:` — shown to the model in the tool description.
+- `tool` — a `RubyLLM::Tool` class or instance; the name inside the sandbox
+  is derived from the class-name leaf (`MyApp::Tools::Weather` → `weather`),
+  or the explicit one from the one-pair form.
 
 Invalid declarations raise at class-definition time, so a misconfigured tool
-never reaches a live chat. Subclasses inherit their parent's mounts.
+never reaches a live chat. Subclasses inherit their parent's mounts and tools.
+
+### Host tools
+
+Bind existing `RubyLLM::Tool`s so the sandboxed code can call them through
+SecurityBox's host RPC channel:
+
+```ruby
+class Weather < RubyLLM::Tool
+  description "Current weather for a city"
+  parameter :city, type: "string", description: "City name"
+
+  def execute(city:)
+    # host-side HTTP call, database query, ...
+  end
+end
+
+class Assistant < RubyLLM::CodeMode
+  mount source: "data", dest: "/data", description: "Project data"
+  tool  Weather                 # binds as `weather`
+  tool  "forecast" => Weather   # or bind it under an explicit name
+end
+```
+
+The description tells the model what is available, and inside the sandbox it
+writes Ruby like:
+
+```ruby
+report = SB.call("weather", city: "Porto Alegre")
+```
+
+- Bound classes are instantiated once at definition time; every call shares
+  that instance, so state persists across calls (like the sandbox itself).
+- Arguments must be JSON-serializable; they arrive as the tool's keyword
+  arguments (top-level string keys become symbols, nested data keeps string
+  keys). Bad arguments come back as an `error` hash — RubyLLM's
+  recoverable-failure convention.
+- The return value is JSON round-tripped: hashes, arrays and scalars pass
+  through; non-serializable objects surface as their `inspect` string.
+- A tool that raises surfaces as `SB::ToolError` (class name and message
+  only — no backtrace), which the sandboxed code can rescue. Unbound names
+  raise `SB::UnknownTool`.
+- Limits per execution: 1000 tool calls and 1 MiB per result. At most 64
+  tools can be bound to one class.
+- A `RubyLLM::CodeMode` cannot be bound inside another `CodeMode`.
 
 ### Sandbox limits
 
@@ -96,11 +147,9 @@ every subsequent evaluation then takes a few hundred milliseconds.
 - Guest code is sandboxed by [SecurityBox](https://rubygems.org/gems/security_box):
   no network, no threads, no processes, no host filesystem beyond the mounts,
   deterministic CPU/memory/time limits, and forged results are rejected.
-
-## Roadmap
-
-- v2: a **Tools** section in the description backed by SecurityBox host RPC
-  handlers, so guest code can call registered host functions via `SB.call`.
+- Bound host tools execute on the host, behind the sandbox's call boundary:
+  their arguments come from model-generated code, so treat them as untrusted
+  input, and only bind tools whose effects you are willing to grant the model.
 
 ## Development
 

data/lib/ruby_llm/code_mode.rb

@@ -5,10 +5,14 @@ require "security_box"
 
 module RubyLLM
   class CodeMode < Tool
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
 
     DEFAULT_TIMEOUT_MS = 30_000
     DEFAULT_FUEL_MS = 10_000
+    MAX_TOOLS = SecurityBox::Rpcs::MAX_RPCS
+
+    TOOL_USAGE = "tool expects a RubyLLM::Tool class or instance, " \
+                 'or exactly one "name" => tool pair'
 
     FIXED_DESCRIPTION = <<~DESC.freeze
       Executes Ruby code inside a secure sandbox and returns what it produced.
@@ -29,12 +33,24 @@ module RubyLLM
       class, message and backtrace are returned so you can fix and retry.
     DESC
 
+    HOST_TOOLS_INTRO = <<~DESC.freeze
+      Registered host tools are callable from inside the sandbox. Call one with
+      `SB.call('name', key: value)`: arguments must be JSON-serializable and become
+      the tool's keyword arguments, and the return value is the tool's result
+      (non-serializable values come back as their inspect string). Bad arguments
+      come back as an `error` hash; handler failures raise `SB::ToolError`
+      (rescuable); unknown names raise `SB::UnknownTool`. Limits: at most 1000
+      tool calls per execution and 1 MiB per result.
+    DESC
+
     Mount = Struct.new(:host, :guest, :mode, :description, keyword_init: true) do
       def payload
         { host: host, guest: guest, mode: mode }
       end
     end
 
+    ToolEntry = Struct.new(:name, :tool, keyword_init: true)
+
     class << self
       def tool_name
         leaf = name.to_s.split('::').last
@@ -51,15 +67,38 @@ module RubyLLM
         add_mount(source, dest, :read_write, description)
       end
 
+      def tool(mapping = nil, **kwargs)
+        if !kwargs.empty?
+          raise ArgumentError, TOOL_USAGE unless kwargs.size == 1 && mapping.nil?
+
+          name, bound = kwargs.first
+          mapping = { name.to_s => bound }
+        end
+
+        if mapping.is_a?(Hash)
+          raise ArgumentError, TOOL_USAGE unless mapping.size == 1
+
+          name, bound = mapping.first
+          add_tool(bound, name.to_s)
+        else
+          add_tool(mapping, nil)
+        end
+      end
+
       def mounts
         @mounts ||= []
       end
 
+      def tools
+        @tools ||= {}
+      end
+
       def configuration
         @configuration ||= SecurityBox::Configuration.build(
           timeout_ms: DEFAULT_TIMEOUT_MS,
           fuel_ms: DEFAULT_FUEL_MS,
-          mounts: mounts.map(&:payload)
+          mounts: mounts.map(&:payload),
+          rpcs: build_rpcs
         )
       end
 
@@ -68,7 +107,8 @@ module RubyLLM
         [
           FIXED_DESCRIPTION.rstrip,
           folder_section("## Read-only folders (readable, never writable)", read_only),
-          folder_section("## Read-write folders (readable and writable)", read_write)
+          folder_section("## Read-write folders (readable and writable)", read_write),
+          tools_section
         ].compact.join("\n\n")
       end
 
@@ -87,6 +127,7 @@ module RubyLLM
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@mounts, mounts.dup)
+        subclass.instance_variable_set(:@tools, tools.dup)
         subclass.instance_variable_set(:@configuration, nil)
       end
 
@@ -106,6 +147,58 @@ 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 || leaf_tool_name(instance.class)).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
+
+      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
+
+        entry.tool.call(**args)
+      end
+
       def folder_section(header, entries)
         return nil if entries.empty?
 
@@ -116,6 +209,39 @@ module RubyLLM
         end
         [header, *lines].join("\n")
       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 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
 
     parameter :code, description: "Complete Ruby script to execute in the sandbox"

metadata

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