gemlings 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e1ddaa59fb419c9b79901c5bc307303a2fe7b8f9d2860918d2cda34a95b917f
-  data.tar.gz: c136329db04947954e039bdd139081572aaae1c66a08c3196eb63fc36d453448
+  metadata.gz: 626d2d204d6ea651987fd9fa08fa642e94741d6086ee397a20be6eba8f78af82
+  data.tar.gz: da993ac05fe07c53e670b5e71b984aa5a7b879a2daed380c6ab4b1febad3ce98
 SHA512:
-  metadata.gz: d45d3793c999be51f362b868ef95039da9dadd7e52a1fb8199508a14553b0a07974146a99c652adc357a7581d997febb1639415eb3fb3bf9dbea8e97c49c868e
-  data.tar.gz: 6a0daa95cf7d74009dca1857b0f44036d663efb23cb3e8187ec0d5888b4463640634b9e8edb8f8bd493d955b770232e6c665b253986cbe72996801d906490324
+  metadata.gz: 4ff5eb3cd06d891dfa5c6994822f5d1cf1957366ad59ed14552357114add8acc7b777bd1486dd3ea759f41a35c00bf5306726e6aed1394195bc5dd2364c3dbcf
+  data.tar.gz: 0a61d59266d86180ca27d4087f0f8ab33d037c6b681bc4715d7969a7ace021bc464c3b6ebae408c19ff50da863f17af9d8c0a5496f775e1d0bf02536aa9c4d4e

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.4.0
+
+Streaming output, configurable sandboxing, and RubyLLM interop.
+
+- **Streaming output** -- `agent.run("task", stream: true)` prints LLM tokens to the terminal in real-time; CLI flag: `gemlings -S`
+- **Configurable sandbox executors** -- Choose `:fork`, `:thread`, or `:box` via `CodeAgent.new(executor: :box)`; auto-detects the best option per platform
+- **Ruby::Box executor** -- On Ruby 4.0+ with `RUBY_BOX=1`, the `:box` executor adds namespace isolation so agent code can't leak monkey-patches or constants into the host
+- **RubyLLM tool interop** -- `Gemlings.tool_from_ruby_llm(MyTool)` wraps any `RubyLLM::Tool` for use in gemlings agents
+- **RubyLLM agent interop** -- `Gemlings.agent_from_ruby_llm(MyAgent)` wraps a `RubyLLM::Agent` or `Chat` as a managed sub-agent
+- **Test coverage** -- Added specs for agent base class, CLI, prompt templates, and UI (106 -> 172 tests)
+
 ## 0.3.2
 
 Bug fixes and Ollama improvements.

data/README.md

@@ -90,6 +90,23 @@ tools = Gemlings.tools_from_mcp(command: ["npx", "-y", "@modelcontextprotocol/se
 tool = Gemlings.tool_from_mcp(command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"], tool_name: "read_file")
 ```
 
+### RubyLLM tools
+
+Use existing [RubyLLM](https://rubyllm.com) tools directly:
+
+```ruby
+class SearchTool < RubyLLM::Tool
+  description "Search the web"
+  param :query, type: :string, desc: "Search query"
+  def execute(query:) = "results for #{query}"
+end
+
+agent = Gemlings::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  tools: [Gemlings.tool_from_ruby_llm(SearchTool)]
+)
+```
+
 ## Multi-agent workflows
 
 Nest agents as tools. The manager agent calls sub-agents by name:
@@ -110,6 +127,21 @@ manager = Gemlings::CodeAgent.new(
 manager.run("Find out when Ruby 3.4 was released and summarize the key features")
 ```
 
+RubyLLM agents work too:
+
+```ruby
+class Researcher < RubyLLM::Agent
+  model "openai/gpt-4o"
+  tools SearchTool
+  instructions "You are a research assistant."
+end
+
+manager = Gemlings::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  agents: [Gemlings.agent_from_ruby_llm(Researcher, name: "researcher", description: "Researches topics")]
+)
+```
+
 ## Output validation
 
 Validate final answers against a JSON Schema:
@@ -214,6 +246,7 @@ gemlings -m openai/gpt-4o -t web_search "Who won the latest Super Bowl?"
 gemlings -a tool_calling -m openai/gpt-4o "What is 6 * 7?"
 gemlings --mcp "npx -y @modelcontextprotocol/server-filesystem /tmp" "List files in /tmp"
 gemlings -i  # interactive mode
+gemlings -S "What is 2+2?"  # stream tokens to terminal
 ```
 
 ## Configuration
@@ -231,8 +264,13 @@ gemlings -i  # interactive mode
 | `final_answer_checks:` | `[]` | Procs `(answer, memory) -> bool` |
 | `callbacks:` | `[]` | Array of `Callback` instances |
 | `step_callbacks:` | `[]` | Procs `(step, agent:) -> void` |
+| `executor:` | auto | CodeAgent sandbox: `:fork`, `:thread`, or `:box` (Ruby 4.0+) |
+
+Requires Ruby 3.2+. JRuby 10+ is also supported. On Ruby 4.0+ with `RUBY_BOX=1`, the `:box` executor adds namespace isolation via `Ruby::Box`.
+
+## Ecosystem
 
-Requires Ruby 3.2+. JRuby 10+ is also supported.
+- [gemlings_browser](https://github.com/parolkar/gemlings_browser) -- Browser automation tools for gemlings agents
 
 ## License
 

data/gemlings.gemspec

@@ -35,7 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rouge", "~> 4.0"
   spec.add_dependency "json-schema", "~> 4.0"
   spec.add_dependency "bigdecimal"
-  spec.add_dependency "mcp", "~> 0.7"
+  spec.add_dependency "mcp", ">= 0.9.2"
   spec.add_dependency "ruby_llm", "~> 1.1"
 
   spec.add_development_dependency "rake", "~> 13.0"

data/lib/gemlings/agent.rb

@@ -27,7 +27,7 @@ module Gemlings
       @tool_map = @tools.each_with_object({}) { |t, h| h[t.class.tool_name] = t }
     end
 
-    def run(task, reset: true, return_full_result: false, &on_stream)
+    def run(task, reset: true, return_full_result: false, stream: false, &on_stream)
       @interrupt_switch = false
 
       if reset || @memory.nil?
@@ -46,7 +46,7 @@ module Gemlings
         maybe_plan(step_number)
 
         # Call LLM with timing
-        llm_duration, response = timed { generate_response(memory.to_messages, &on_stream) }
+        llm_duration, response = timed { generate_response(memory.to_messages, stream: stream, &on_stream) }
 
         # Parse response
         thought, action = parse_response(response)
@@ -159,11 +159,18 @@ module Gemlings
       raise NotImplementedError
     end
 
-    def generate_response(messages, &on_stream)
-      spin = on_stream ? nil : UI.spinner("Thinking...")
-      spin&.start
-      response = @model.generate(messages, &on_stream)
-      spin&.stop
+    def generate_response(messages, stream: false, &on_stream)
+      if on_stream
+        response = @model.generate(messages, &on_stream)
+      elsif stream
+        response = @model.generate(messages) { |token| UI.stream_token(token) }
+        UI.stream_end
+      else
+        spin = UI.spinner("Thinking...")
+        spin.start
+        response = @model.generate(messages)
+        spin.stop
+      end
       response
     end
 

data/lib/gemlings/cli.rb

@@ -23,9 +23,11 @@ module Gemlings
         tools: [],
         mcp: [],
         interactive: false,
+        stream: false,
         max_steps: 10,
         planning_interval: nil,
-        agent_type: "code"
+        agent_type: "code",
+        executor: nil
       }
       parse_options!
     end
@@ -67,6 +69,10 @@ module Gemlings
           @options[:interactive] = true
         end
 
+        opts.on("-S", "--stream", "Stream LLM tokens to the terminal") do
+          @options[:stream] = true
+        end
+
         opts.on("--mcp COMMAND", "MCP server command (repeatable)") do |cmd|
           @options[:mcp] << cmd
         end
@@ -75,6 +81,10 @@ module Gemlings
           @options[:max_steps] = n
         end
 
+        opts.on("-e", "--executor NAME", "Sandbox executor: fork, thread, box (default: auto)") do |e|
+          @options[:executor] = e.to_sym
+        end
+
         opts.on("-v", "--version", "Show version") do
           puts "gemlings #{VERSION}"
           exit
@@ -108,18 +118,20 @@ module Gemlings
 
       agent_class = @options[:agent_type] == "tool_calling" ? ToolCallingAgent : CodeAgent
 
-      agent_class.new(
+      opts = {
         model: @options[:model],
         tools: tools,
         max_steps: @options[:max_steps],
         planning_interval: @options[:planning_interval]
-      )
+      }
+      opts[:executor] = @options[:executor] if @options[:executor] && agent_class == CodeAgent
+      agent_class.new(**opts)
     end
 
     def single_query(query)
       UI.welcome
       agent = build_agent
-      agent.run(query)
+      agent.run(query, stream: @options[:stream])
     end
 
     def interactive_mode
@@ -135,7 +147,7 @@ module Gemlings
         query = $stdin.gets&.strip
         break if query.nil? || query.empty?
 
-        agent.run(query, reset: first)
+        agent.run(query, reset: first, stream: @options[:stream])
         first = false
         puts
       end

data/lib/gemlings/code_agent.rb

@@ -5,9 +5,9 @@ module Gemlings
     CODE_BLOCK_RE = /```ruby\s*\n(.*?)```/m
 
     def initialize(model:, tools: [], agents: [], name: nil, description: nil,
-                   max_steps: 10, timeout: 30, planning_interval: nil, step_callbacks: [],
-                   callbacks: [], final_answer_checks: [], prompt_templates: nil,
-                   instructions: nil, output_type: nil)
+                   max_steps: 10, timeout: 30, executor: nil, planning_interval: nil,
+                   step_callbacks: [], callbacks: [], final_answer_checks: [],
+                   prompt_templates: nil, instructions: nil, output_type: nil)
       require_relative "tools/list_gems"
       tools = [ListGems] + tools unless tools.any? { |t| t == ListGems || (t.is_a?(Tool) && t.is_a?(ListGems)) }
       super(model: model, tools: tools, agents: agents, name: name, description: description,
@@ -15,6 +15,7 @@ module Gemlings
             callbacks: callbacks, final_answer_checks: final_answer_checks,
             prompt_templates: prompt_templates, instructions: instructions, output_type: output_type)
       @timeout = timeout
+      @executor = executor ? Sandbox.resolve_executor(executor) : nil
     end
 
     private
@@ -76,7 +77,7 @@ module Gemlings
     end
 
     def execute(code)
-      sandbox = Sandbox.new(tools: tools, timeout: @timeout)
+      sandbox = Sandbox.new(tools: tools, timeout: @timeout, executor: @executor)
       sandbox.execute(code)
     end
   end

data/lib/gemlings/ruby_llm.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Gemlings
+  # Wraps a RubyLLM::Tool (class or instance) as a Gemlings::Tool.
+  def self.tool_from_ruby_llm(tool)
+    require "ruby_llm"
+    instance = tool.is_a?(Class) ? tool.new : tool
+
+    raise ArgumentError, "Expected a RubyLLM::Tool, got #{instance.class}" unless instance.is_a?(RubyLLM::Tool)
+
+    tool_name = instance.name
+    tool_desc = instance.description || ""
+    params = instance.parameters || {}
+
+    klass = Class.new(Tool) do
+      self.tool_name(tool_name)
+      description(tool_desc)
+
+      params.each do |pname, param|
+        input pname.to_sym,
+              type: (param.type || "string").to_sym,
+              description: param.description || "",
+              required: param.required != false
+      end
+    end
+
+    wrapper = klass.new
+    wrapper.define_singleton_method(:call) do |**kwargs|
+      instance.call(kwargs)
+    end
+    wrapper
+  end
+
+  # Wraps a RubyLLM::Agent (class or instance) as a managed Gemlings agent.
+  # The agent can be passed in the `agents:` array of a Gemlings agent.
+  def self.agent_from_ruby_llm(agent, name: nil, description: nil)
+    require "ruby_llm"
+
+    chat = if agent.is_a?(Class) && agent < RubyLLM::Agent
+      agent.chat
+    elsif agent.is_a?(RubyLLM::Agent)
+      agent.chat
+    elsif agent.respond_to?(:ask)
+      agent
+    else
+      raise ArgumentError, "Expected a RubyLLM::Agent class, instance, or RubyLLM::Chat, got #{agent.class}"
+    end
+
+    agent_name = name || agent.class.name&.split("::")&.last&.downcase || "ruby_llm_agent"
+    agent_desc = description || "A RubyLLM agent"
+
+    RubyLLMAgentWrapper.new(chat, name: agent_name, description: agent_desc)
+  end
+
+  # Minimal agent-like wrapper around a RubyLLM::Chat so it can be used
+  # with Gemlings::ManagedAgentTool.
+  class RubyLLMAgentWrapper
+    attr_reader :name, :description
+
+    def initialize(chat, name:, description:)
+      @chat = chat
+      @name = name
+      @description = description
+    end
+
+    def run(task)
+      response = @chat.ask(task)
+      response.content
+    end
+  end
+end

data/lib/gemlings/sandbox.rb

@@ -7,12 +7,17 @@ module Gemlings
     DEFAULT_TIMEOUT = 30 # seconds
 
     # ---------------------------------------------------------------------------
-    # Executor strategy — selected once at load time based on the Ruby engine.
-    # Adding a new backend (e.g. TruffleRuby) is a new subclass + one constant.
+    # Executor strategy — user-selectable, with sensible per-platform defaults.
     # ---------------------------------------------------------------------------
+    EXECUTORS = {}
+
     class Executor
-      def self.for_platform
-        RUBY_ENGINE == "jruby" ? ThreadExecutor : ForkExecutor
+      def self.inherited(subclass)
+        super
+      end
+
+      def self.available?
+        true
       end
 
       def call(_timeout, &_block)
@@ -22,6 +27,10 @@ module Gemlings
 
     # MRI / TruffleRuby: fork gives full process isolation and safe kill.
     class ForkExecutor < Executor
+      def self.available?
+        Process.respond_to?(:fork)
+      end
+
       def call(timeout, &block)
         reader, writer = IO.pipe
 
@@ -57,6 +66,24 @@ module Gemlings
         data.empty? ? { output: "", result: nil, is_final_answer: false } : Marshal.load(data) # rubocop:disable Security/MarshalLoad
       end
     end
+    EXECUTORS[:fork] = ForkExecutor
+
+    # Ruby 4.0+: Fork with Ruby::Box namespace isolation.
+    # Agent code runs in a separate process AND a separate namespace, so
+    # monkey-patches, constants, and class variables can't leak into the host.
+    class BoxExecutor < ForkExecutor
+      def self.available?
+        super && defined?(Ruby::Box) && Ruby::Box.enabled?
+      end
+
+      def call(timeout, &block)
+        super(timeout) do
+          box = Ruby::Box.new
+          block.call(box)
+        end
+      end
+    end
+    EXECUTORS[:box] = BoxExecutor
 
     # JRuby: fork is unavailable; use a thread with a join-based timeout.
     # STDOUT_MUTEX serializes $stdout redirection so concurrent sandbox calls
@@ -82,19 +109,38 @@ module Gemlings
         error ? { error: error } : result
       end
     end
+    EXECUTORS[:thread] = ThreadExecutor
+
+    def self.default_executor
+      if BoxExecutor.available?
+        :box
+      elsif ForkExecutor.available?
+        :fork
+      else
+        :thread
+      end
+    end
 
-    EXECUTOR = Executor.for_platform.new
+    def self.resolve_executor(name)
+      klass = EXECUTORS[name]
+      raise ArgumentError, "Unknown executor: #{name.inspect}. Available: #{EXECUTORS.keys.join(", ")}" unless klass
+      unless klass.available?
+        raise Error, "Executor #{name.inspect} is not available on this platform (#{RUBY_ENGINE} #{RUBY_VERSION})"
+      end
+      klass.new
+    end
 
     attr_reader :timeout
 
-    def initialize(tools:, timeout: DEFAULT_TIMEOUT)
+    def initialize(tools:, timeout: DEFAULT_TIMEOUT, executor: nil)
       @tools = tools
       @timeout = timeout
+      @executor = executor || self.class.resolve_executor(self.class.default_executor)
       @tool_map = tools.each_with_object({}) { |t, h| h[t.class.tool_name] = t }
     end
 
     def execute(code)
-      EXECUTOR.call(@timeout) { run_in_child(code) }
+      @executor.call(@timeout) { run_in_child(code) }
     end
 
     private

data/lib/gemlings/tool_calling_agent.rb

@@ -15,12 +15,19 @@ module Gemlings
       prompt
     end
 
-    def generate_response(messages, &on_stream)
+    def generate_response(messages, stream: false, &on_stream)
       tool_schemas = tools.map { |t| t.class.to_schema }
-      spin = on_stream ? nil : UI.spinner("Thinking...")
-      spin&.start
-      response = @model.generate(messages, tools: tool_schemas, &on_stream)
-      spin&.stop
+      if on_stream
+        response = @model.generate(messages, tools: tool_schemas, &on_stream)
+      elsif stream
+        response = @model.generate(messages, tools: tool_schemas) { |token| UI.stream_token(token) }
+        UI.stream_end
+      else
+        spin = UI.spinner("Thinking...")
+        spin.start
+        response = @model.generate(messages, tools: tool_schemas)
+        spin.stop
+      end
       response
     end
 

data/lib/gemlings/ui.rb

@@ -208,6 +208,14 @@ module Gemlings
         Spinner.new(message)
       end
 
+      def stream_token(text)
+        $stderr.print text
+      end
+
+      def stream_end
+        $stderr.print "\n"
+      end
+
       def welcome
         if LIPGLOSS_AVAILABLE
           title = Lipgloss::Style.new

data/lib/gemlings/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gemlings
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/gemlings.rb

@@ -18,4 +18,5 @@ require_relative "gemlings/agent"
 require_relative "gemlings/code_agent"
 require_relative "gemlings/tool_calling_agent"
 require_relative "gemlings/mcp"
+require_relative "gemlings/ruby_llm"
 require_relative "gemlings/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemlings
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Chris Hasiński
@@ -83,16 +83,16 @@ dependencies:
   name: mcp
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: 0.9.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: 0.9.2
 - !ruby/object:Gem::Dependency
   name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
@@ -181,6 +181,7 @@ files:
 - lib/gemlings/model.rb
 - lib/gemlings/models/ruby_llm_adapter.rb
 - lib/gemlings/prompt.rb
+- lib/gemlings/ruby_llm.rb
 - lib/gemlings/sandbox.rb
 - lib/gemlings/tool.rb
 - lib/gemlings/tool_calling_agent.rb