robot_lab 0.2.8 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de87b78206bc424703b465d3a1f236db723ea38fe4235c07413466ab5b469ead
-  data.tar.gz: 6a7db14e4530e615e258415491422f297567a2f640983035f1542d88e7d200e5
+  metadata.gz: 8ae306b218ea8c7c5d68b9de5c0bce088e40a9f1c482278fd54557624bc0ad72
+  data.tar.gz: 92206741b254631a7e09da7247db35702eb12a70409622aa3634c594e83207a0
 SHA512:
-  metadata.gz: f6814c9a8b86b8e6d1df2adcc2d9b4ab84c176c67211424e8404e9d83c1e08ffd353587523e4c45efec295d0e47bbd731b0cdc6f3e62754cfd4f1ce2a33d7655
-  data.tar.gz: 37682af098203ae333cc83fa6e66a95f1883aae0bed8411524a05d6795bb47b4a99f231353fe3546b2fdae8a5c098d0f45b863e531edaf237aab33e4e1bc3859
+  metadata.gz: 36c52283dfd0edc88cfc71e358a82e463ddfad501a69097ef2aaa28b37f7c5f5d08938d39b1c6312c2b1a3aaf19494895d3bcfd6f74870b4b770942f3ae60d3e
+  data.tar.gz: 1477bf01cb700d41bab40950cd650960676f1589a5f2f4dc8747b1f940e9f21a5b3ff53a15ca4aa2ef01c493b38c1f957406ddc1b365f1592a21b1e6bda1d992

data/CHANGELOG.md

@@ -6,6 +6,71 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+
+### Changed
+
+- **Minimum Ruby raised to 4.0.9.** `required_ruby_version` is now `>= 4.0.9` (was `>= 3.2.0`), and a `.ruby-version` file pins development to 4.0.9.
+- **Slimmer gem.** The gemspec now whitelists what ships in the `.gem`: `lib/`, `sig/`, `exe/`, README, CHANGELOG, and LICENSE. Previous releases packaged everything tracked by git — the docs site, examples with generated output, tooling config, and local design notes — which made 0.3.0 a 1.1 MB gem of 300+ files. 0.3.1 is ~130 KB and 65 files; the docs and examples remain on GitHub.
+- Verified against ruby_llm 2.1.1 (the newest release the `~> 2.0` constraint admits) in addition to 2.0.0; the full suite passes on both.
+
+### Fixed
+
+- `MCP::Transports::StreamableHTTP#connect` no longer raises inside its Async task when the initialize handshake returns no result; the session id is simply left unset.
+
+## [0.3.0] - 2026-09-18
+
+The ruby_llm 2.0 release. Core moves from ruby_llm 1.x to the official 2.0.0
+release; every `robot_lab-*` extension gem releases in lockstep at 0.3.0 and
+now requires `robot_lab ~> 0.3.0`.
+
+### Changed (BREAKING)
+- **ruby_llm 1.x → 2.0.** The gemspec now requires `ruby_llm "~> 2.0"`
+  (official release). Robot tools written with the 1.x DSL must migrate:
+  `param` → `parameter`, `desc:` → `description:`; `halt` is gone (the caller
+  controls the loop). Token counts moved to `response.tokens.input/.output`,
+  and `finish_reason` (Symbol) replaces `stop_reason`. The `claude-sonnet-4`
+  registry alias no longer resolves; the default models are now
+  `claude-sonnet-4-6` (production) and `claude-haiku-4-5` (test).
+- **Dropped hard dependencies** on `ruby_llm-mcp`, `ruby_llm-schema`, and
+  `ruby_llm-semantic_cache`. Semantic caching is now optional: `Memory#cache`
+  returns `nil` when `ruby_llm-semantic_cache` is not installed and Memory
+  runs with caching disabled. (Its released versions still pin ruby_llm 1.x,
+  so it cannot co-resolve with 2.0 yet.)
+
+### Added
+- `ruby_llm-providers-apfel` and `ruby_llm-providers-lms` (`~> 0.2.1`) as
+  runtime dependencies, consumed as released gems — the local `path:`
+  overrides for sibling checkouts are gone from the Gemfiles.
+- `Robot::ResultBuilding` — extracted module that adapts a ruby_llm response
+  into a `RobotResult` (token accounting, stop-reason normalization, message
+  coercion).
+- `examples/run_all.rb` — runs every executable `NN_*.rb` demo serially with
+  a banner between each; works from any cwd, and Ctrl-C terminates only the
+  demo currently running (the runner notes it and moves on).
+- READMEs for the subdirectory demos: `15_memory_network_and_bus`,
+  `26_document_store` (corpus), and `27_incident_response`.
+- Fasterer quality gate now actually runs: `fasterer` added to the
+  development group, with a `.fasterer.yml` documenting the disabled
+  speed-over-readability checks.
+
+### Changed
+- Robot, Tool, RunConfig, and the hook system adapted to the ruby_llm 2.0
+  API; docs and examples synced to match.
+- Examples run against a local LM Studio server through the `:lms` provider;
+  `examples/common.rb` anchors `BUNDLE_GEMFILE` to the gem root so demos run
+  from any directory, and `examples/README.md` notes that demo speed and
+  answer quality depend on the provider/model in use.
+- `.envrc` no longer exports `BUNDLE_GEMFILE`; it is inherited from the
+  project root (`asgard dev` / `asgard prod`).
+
+### Fixed
+- amazing_print 3.0 crash at demo startup (`undefined method 'try' for
+  module ActiveSupport`): robot_lab's dependencies load parts of
+  ActiveSupport, which tricked amazing_print into loading its Rails
+  extension; `examples/common.rb` now preloads
+  `active_support/core_ext/object/try` and `active_support/log_subscriber`.
+
 ## [0.2.8] - 2026-09-09
 
 ### Added

data/README.md

@@ -21,7 +21,7 @@
 - <strong>Human-in-the-Loop</strong> - AskUser tool for interactive prompting<br>
 - <strong>Content Streaming</strong> - Stored callbacks, per-call blocks, or both<br>
 - <strong>MCP Integration</strong> - Connect to external tool servers with timeouts and retry<br>
-- <strong>Local LLM Providers</strong> - Ollama and GPUStack via provider passthrough<br>
+- <strong>Local LLM Providers</strong> - LM Studio (via ruby_llm-providers-lms), Ollama, and GPUStack via provider passthrough<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
@@ -55,7 +55,7 @@ gem install robot_lab
 
 ### Requirements
 
-- Ruby >= 3.2
+- Ruby >= 4.0.9
 - [One or more API Keys for LLM providers supported by RubyLLM](https://rubyllm.com/configuration/#provider-configuration)
 
 For comprehensive guides and API documentation, visit **[https://madbomber.github.io/robot_lab](https://madbomber.github.io/robot_lab)**
@@ -82,17 +82,15 @@ puts result.last_text_content
 
 ### Local LLM Providers
 
-For local LLM providers, use the `provider:` parameter. RubyLLM's provider list is the authority on valid values — `:ollama` and `:gpustack` are the local ones (alongside `:anthropic`, `:azure`, `:bedrock`, `:deepseek`, `:gemini`, `:mistral`, `:openai`, `:openrouter`, `:perplexity`, `:vertexai`, and `:xai`). The provider's API base must be configured first, or building the robot raises `RubyLLM::ConfigurationError`:
-
-```bash
-export ROBOT_LAB_RUBY_LLM__OLLAMA_API_BASE=http://localhost:11434/v1
-```
+For local LLM providers, use the `provider:` parameter. RubyLLM's provider list is the authority on valid values — `:ollama` and `:gpustack` are built in, and provider gems add more (alongside `:anthropic`, `:azure`, `:bedrock`, `:deepseek`, `:gemini`, `:mistral`, `:openai`, `:openrouter`, `:perplexity`, `:vertexai`, and `:xai`). The examples in this repo use LM Studio through the [ruby_llm-providers-lms](https://github.com/madbomber/ruby_llm-providers-lms) gem, which registers the `:lms` provider (defaults to `http://localhost:1234/v1`, no API key needed):
 
 ```ruby
+require "ruby_llm/providers/lms"
+
 robot = RobotLab.build(
   name: "local_bot",
-  model: "llama3.2",
-  provider: :ollama,
+  model: "qwen/qwen3.8-27b",   # complex work; use "openai/gpt-oss-20b" for simple chat
+  provider: :lms,
   system_prompt: "You are a helpful assistant."
 )
 ```
@@ -113,12 +111,12 @@ RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layer
 # Set API keys via environment variables (double underscore for nesting)
 export ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
 export ROBOT_LAB_RUBY_LLM__OPENAI_API_KEY=sk-...
-export ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
+export ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4-6
 ```
 
 ```ruby
 # Access configuration values
-RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4-6"
 RobotLab.config.ruby_llm.request_timeout  #=> 120
 ```
 
@@ -126,7 +124,7 @@ Or create a project config file at `./config/robot_lab.yml`:
 
 ```yaml
 ruby_llm:
-  model: claude-sonnet-4
+  model: claude-sonnet-4-6
   anthropic_api_key: sk-ant-...
   request_timeout: 180
 ```
@@ -202,7 +200,7 @@ mcp:
       type: stdio
       command: npx
       args: ["-y", "@modelcontextprotocol/server-github"]
-model: claude-sonnet-4
+model: claude-sonnet-4-6
 ---
 You are a GitHub assistant. Use available tools to help with repository tasks.
 ```
@@ -265,7 +263,7 @@ robot = RobotLab.build(
 ```ruby
 # Create a shared config
 shared = RobotLab::RunConfig.new(
-  model: "claude-sonnet-4",
+  model: "claude-sonnet-4-6",
   temperature: 0.7,
   max_tokens: 2000
 )
@@ -302,16 +300,16 @@ RunConfig supports keyword construction, block DSL, and merge semantics:
 ```ruby
 # Block DSL
 config = RobotLab::RunConfig.new do |c|
-  c.model "claude-sonnet-4"
+  c.model "claude-sonnet-4-6"
   c.temperature 0.7
 end
 
 # Merge (more-specific wins)
-network_config = RobotLab::RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+network_config = RobotLab::RunConfig.new(model: "claude-sonnet-4-6", temperature: 0.5)
 robot_config   = RobotLab::RunConfig.new(temperature: 0.9)
 effective      = network_config.merge(robot_config)
 effective.temperature  #=> 0.9
-effective.model        #=> "claude-sonnet-4"
+effective.model        #=> "claude-sonnet-4-6"
 ```
 
 ### Chaining Configuration
@@ -323,7 +321,7 @@ robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer
 
 result = robot
   .with_temperature(0.9)
-  .with_model("claude-sonnet-4")
+  .with_model("claude-sonnet-4-6")
   .run("Write a haiku about Ruby programming")
 ```
 

data/lib/robot_lab/ask_user.rb

@@ -33,9 +33,9 @@ module RobotLab
   #
   class AskUser < Tool
     description "Ask the user a question and wait for their typed response"
-    param :question, type: "string",  desc: "The question to ask the user"
-    param :choices,  type: "array",   desc: "Optional list of choices to present", required: false
-    param :default,  type: "string",  desc: "Default value if user presses Enter",  required: false
+    parameter :question, type: "string",  description: "The question to ask the user"
+    parameter :choices,  type: "array",   description: "Optional list of choices to present", required: false
+    parameter :default,  type: "string",  description: "Default value if user presses Enter",  required: false
 
     # :reek:FeatureEnvy -- rendering and resolving the caller-supplied choices list is this tool's whole job.
     # :reek:TooManyStatements -- linear prompt/read/resolve terminal interaction.

data/lib/robot_lab/config/defaults.yml

@@ -41,13 +41,13 @@ defaults:
     with_model:
       provider: null # chat-specific provider
       model: null # chat-specific model
-      assume_exists: null # assume the model exists primarily for local providers
+      assume_model_exists: null # assume the model exists primarily for local providers
     with_temperature: 0.7 # Controls randomness (0.0-2.0, null = model default)
+    with_max_output_tokens: null # Maximum tokens in response
     with_tools: null # ?? not sure about this one.
-    with_params:
+    with_provider_options: # merged into the request payload (ruby_llm 2.0)
       top_p: null # Nucleus sampling threshold (0.0-1.0)
       top_k: null # Top-k sampling (integer, provider-specific)
-      max_tokens: null # Maximum tokens in response
       presence_penalty: null # Penalize new tokens based on presence (-2.0 to 2.0)
       frequency_penalty: null # Penalize new tokens based on frequency (-2.0 to 2.0)
       stop: null # Stop sequences (string or array of strings)
@@ -55,7 +55,7 @@ defaults:
   # RubyLLM Configuration Section
   ruby_llm:
     provider: :anthropic
-    model: claude-sonnet-4
+    model: claude-sonnet-4-6
     assume_model_exists: false # (dep of assume_exists in chat section) set true for Ollama and other local LLM providers
     # Provider API Keys (null = use env vars directly)
     anthropic_api_key: null
@@ -117,7 +117,7 @@ test:
   max_iterations: 3
   streaming_enabled: false
   ruby_llm:
-    model: claude-3-haiku-20240307
+    model: claude-haiku-4-5
     request_timeout: 30
     max_retries: 1
     log_level: :warn

data/lib/robot_lab/config.rb

@@ -14,7 +14,7 @@ module RobotLab
   # - Automatic RubyLLM configuration application
   #
   # @example Access configuration values
-  #   RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+  #   RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4-6"
   #   RobotLab.config.ruby_llm.request_timeout  #=> 120
   #   RobotLab.config.development?              #=> true
   #
@@ -28,7 +28,7 @@ module RobotLab
   #   # defaults.yml. This file is NOT run through ERB, so keep secrets in
   #   # environment variables or in ./config/robot_lab.yml (which is).
   #   ruby_llm:
-  #     model: claude-sonnet-4
+  #     model: claude-sonnet-4-6
   #     request_timeout: 120
   #
   class Config < MywayConfig::Base

data/lib/robot_lab/mcp/transports/streamable_http.rb

@@ -50,7 +50,7 @@ module RobotLab
 
             # Initialize MCP protocol
             result = send_initialize
-            @session_id ||= result.dig(:serverInfo, :sessionId)
+            @session_id ||= result&.dig(:serverInfo, :sessionId)
           end
 
           self
@@ -116,9 +116,7 @@ module RobotLab
         # Returns the session identifier.
         #
         # @return [String, nil] the session ID
-        def session_id
-          @session_id
-        end
+        attr_reader :session_id
 
         private
 

data/lib/robot_lab/memory.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
-require "ruby_llm/semantic_cache"
+# Optional: ruby_llm-semantic_cache has not shipped a ruby_llm 2.0-compatible
+# release. When the gem is absent, Memory#cache returns nil and semantic
+# caching is silently disabled.
+begin
+  require "ruby_llm/semantic_cache"
+rescue LoadError
+  # Semantic caching unavailable; Memory runs without it.
+end
 
 module RobotLab
   # Raised when a blocking get times out
@@ -106,7 +113,7 @@ module RobotLab
       set_internal(:results, Array(results))
       set_internal(:messages, Array(messages).map { |m| normalize_message(m) })
       set_internal(:session_id, session_id)
-      set_internal(:cache, @enable_cache ? RubyLLM::SemanticCache : nil)
+      set_internal(:cache, @enable_cache ? create_semantic_cache : nil)
 
       # Data proxy for method-style access
       @data = nil
@@ -215,9 +222,11 @@ module RobotLab
 
     # Get the semantic cache module
     #
-    # The cache is always active and provides semantic similarity matching
-    # for LLM responses, reducing costs and latency by returning cached
-    # responses for semantically equivalent queries.
+    # When the optional ruby_llm-semantic_cache gem is installed (and
+    # enable_cache is true), provides semantic similarity matching for LLM
+    # responses, reducing costs and latency by returning cached responses
+    # for semantically equivalent queries. Returns nil when the gem is
+    # absent or caching is disabled.
     #
     # @example Using the cache with fetch
     #   response = memory.cache.fetch("What is Ruby?") do
@@ -228,7 +237,7 @@ module RobotLab
     #   chat = memory.cache.wrap(RubyLLM.chat(model: "gpt-4"))
     #   chat.ask("What is Ruby?")  # Cached on semantic similarity
     #
-    # @return [RubyLLM::SemanticCache] the semantic cache module
+    # @return [RubyLLM::SemanticCache, nil] the semantic cache module, or nil when unavailable
     #
     def cache
       get_internal(:cache)
@@ -702,7 +711,7 @@ module RobotLab
     end
 
     def create_semantic_cache
-      RubyLLM::SemanticCache
+      defined?(RubyLLM::SemanticCache) ? RubyLLM::SemanticCache : nil
     end
 
     # :reek:ControlParameter -- factory method; the preference symbol is exactly what selects the backend.

data/lib/robot_lab/robot/hooking.rb

@@ -54,6 +54,32 @@ module RobotLab
       def hook_registries(network = nil)
         [RobotLab.hooks, network&.hooks, @hooks]
       end
+
+      # Arm the per-run circuit breaker checked by the chat's before_tool_call
+      # dispatcher (see Robot#register_chat_callbacks). Raises ToolLoopError
+      # once tool calls exceed @config.max_tool_rounds. ruby_llm 2.0 callbacks
+      # are additive and cannot be removed, so the breaker toggles a flag the
+      # permanent dispatcher consults instead of swapping callbacks per run.
+      def install_circuit_breaker
+        @circuit_breaker_call_count = 0
+        @circuit_breaker_armed = true
+      end
+
+      # Disarm the circuit breaker after a run.
+      def restore_tool_call_callback
+        @circuit_breaker_armed = false
+      end
+
+      # Count a tool call against max_tool_rounds and raise once exceeded.
+      def enforce_circuit_breaker!
+        max = @config.max_tool_rounds
+        @circuit_breaker_call_count += 1
+        return if @circuit_breaker_call_count <= max
+
+        raise ToolLoopError,
+              "Circuit breaker triggered: #{@circuit_breaker_call_count} tool calls exceeded " \
+              "max_tool_rounds (#{max})"
+      end
     end
   end
 end

data/lib/robot_lab/robot/result_building.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Adapts a ruby_llm response into a RobotResult, including token
+    # accounting, stop-reason normalization, and message coercion helpers.
+    #
+    # Owns:    nothing (pure adapters over the response and @chat)
+    # Reads:   @chat, @name; Writes: @total_input_tokens, @total_output_tokens
+    module ResultBuilding
+      private
+
+      # :reek:TooManyStatements :reek:FeatureEnvy -- adapting a provider response's many optional fields into
+      #   a RobotResult is inherently response-centric.
+      def build_result(response, _memory)
+        text = result_text(response)
+        output = text ? [TextMessage.new(role: 'assistant', content: text)] : []
+
+        tool_calls = response.respond_to?(:tool_calls) ? (response.tool_calls || []) : []
+
+        input_toks, output_toks = extract_token_counts(response)
+        @total_input_tokens += input_toks
+        @total_output_tokens += output_toks
+
+        RobotResult.new(
+          robot_name: @name,
+          output: output,
+          tool_calls: normalize_tool_calls(tool_calls),
+          stop_reason: extract_stop_reason(response),
+          raw: response,
+          input_tokens: input_toks,
+          output_tokens: output_toks
+        )
+      end
+
+      # Token usage from the response. ruby_llm 2.0 nests counts under
+      # response.tokens; duck-typed responses may still answer input_tokens.
+      # :reek:FeatureEnvy -- reading the response's optional token fields is the extraction itself.
+      def extract_token_counts(response)
+        if response.respond_to?(:tokens) && (tokens = response.tokens)
+          [tokens.input.to_i, tokens.output.to_i]
+        elsif response.respond_to?(:input_tokens)
+          [response.input_tokens.to_i,
+           response.respond_to?(:output_tokens) ? response.output_tokens.to_i : 0]
+        else
+          [0, 0]
+        end
+      end
+
+      # ruby_llm 2.0's add_message accepts a Message, an attribute Hash, or a
+      # record responding to to_llm. Compression summaries (and tests) hand us
+      # plain role/content value objects; convert those to attribute hashes so
+      # the chat can coerce them.
+      def coerce_replacement_message(message)
+        if message.is_a?(RubyLLM::Message) || message.is_a?(Hash) || message.respond_to?(:to_llm)
+          message
+        else
+          { role: message.role, content: message.content }
+        end
+      end
+
+      # The response's normalized stop reason. ruby_llm 2.0 exposes it as
+      # finish_reason (a Symbol such as :stop or :tool_calls); older or
+      # duck-typed responses may still answer stop_reason.
+      def extract_stop_reason(response)
+        return response.finish_reason if response.respond_to?(:finish_reason)
+
+        response.respond_to?(:stop_reason) ? response.stop_reason : nil
+      end
+
+      # Text for the result's output. Prefers the final response's content, then
+      # falls back in order to: (1) thinking text for models that route all output
+      # through reasoning_content (e.g. qwen3 on Ollama), (2) the most recent
+      # assistant text within the current turn for models that end on a tool call
+      # with no trailing text.
+      #
+      # The chat-history fallback is scoped to messages AFTER the last user message
+      # (the current turn) to prevent a previous turn's response from being returned
+      # when a thinking-mode model emits nothing in response.content.
+      # :reek:TooManyStatements :reek:FeatureEnvy -- documented fallback chain over the response's optional content/thinking/history fields.
+      def result_text(response)
+        content = response.content if response.respond_to?(:content)
+        return content if content && !content.to_s.empty?
+
+        # Ollama routes qwen3's reasoning to reasoning_content, which ruby_llm
+        # surfaces as response.thinking (a RubyLLM::Thinking object). When content
+        # is nil and thinking is present, the thinking IS the response for that turn.
+        if response.respond_to?(:thinking) && (thinking = response.thinking)
+          thinking_text = thinking.respond_to?(:text) ? thinking.text.to_s : thinking.to_s
+          return thinking_text unless thinking_text.empty?
+        end
+
+        return nil unless @chat.respond_to?(:messages)
+
+        messages = @chat.messages
+        last_user_idx = messages.rindex { |m| m.role == :user } || -1
+        current_turn = messages[(last_user_idx + 1)..]
+
+        last = current_turn.rfind { |m| m.role == :assistant && m.content && !m.content.to_s.empty? }
+        last&.content
+      end
+
+      def normalize_tool_calls(tool_calls)
+        return [] unless tool_calls
+
+        tool_calls.map do |tc|
+          if tc.is_a?(Hash)
+            ToolResultMessage.new(
+              tool: tc,
+              content: tc[:result] || tc['result']
+            )
+          else
+            tc
+          end
+        end
+      end
+    end
+  end
+end