robot_lab 0.0.7 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eaa090a87b2f82890dc8ee350bb1326b380c41d6560c3ae01e0ea1a4fc0d84a
-  data.tar.gz: 8232818730ba698d09ed9537adbc774f5d2ad84013942016e48ebad192a653c9
+  metadata.gz: c852fcf7f4aed4ce95fabdc5b0296723ca8aa10e780dabaa7759e618a22bc640
+  data.tar.gz: 1bcb205c958ede9967886dae78a1d1a6d47da42e4cd9bd29d7bdd3e094b0a088
 SHA512:
-  metadata.gz: ce75a3733e3d153196f85995c1363e542aa9b039f523cb15388a2d0d0f7a13d7ea26390a12abf6582680da5b119f1df8f6f35a7837a28a8b6f07f5aca72639db
-  data.tar.gz: c2c4f50e6352dc6018c8f0077549450e05adccb3eaa555236c46b131c557f69acf6f59ca6af12c823e429db777019bca684846338af273de2e2ce5587be5a976
+  metadata.gz: 5620e7798ac04441cb23c6a7cc5f0cdad7447103825db35ef6f3a3987785b8ff5fb355ec03a309ef9c8a5ce5b0b7a29d9f5adef0e6a5d9de5cd66d3c94fb0469
+  data.tar.gz: 9300b1f5ed98e70226c7c670bcf2e3dee033310db6b2182b2705085f02474a1ea6157a011c93906da1d45ba38b4c9f8b9e62545cdb5fd304ca1550734f7dc043

data/CHANGELOG.md

@@ -1,8 +1,5 @@
 # Changelog
 
-> [!CAUTION]
-> This gem is under active development. APIs and features may change without notice.
-
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
@@ -11,6 +8,105 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.9] - 2026-03-02
+
+### Added
+
+- **Provider passthrough** — `provider:` parameter on Robot constructor for local LLM providers (Ollama, GPUStack, etc.)
+  - Automatically sets `assume_model_exists: true` when provider is specified
+  - Exposed via `robot.provider` accessor
+- **MCP request timeouts** — configurable timeout for all MCP transports
+  - `MCP::Server` accepts `timeout:` parameter (default 15s); auto-converts millisecond values
+  - `MCP::Transports::Base` extracts and exposes `timeout` from config
+  - `MCP::Transports::Stdio` wraps all blocking I/O with `Timeout.timeout` — hung servers no longer block the caller forever
+  - Timeout propagated from `MCP::Server` through `MCP::Client` to transport layer
+- **MCP connection resilience** — improved error handling and retry logic
+  - `ensure_mcp_clients` retries previously failed servers on subsequent calls
+  - `@failed_mcp_configs` tracks servers that failed to connect
+  - `robot.failed_mcp_server_names` — query which MCP servers are down
+  - `robot.connect_mcp!` — eagerly connect to MCP servers (normally lazy)
+  - `init_mcp_client` rescues `StandardError` so one bad server doesn't prevent others from connecting
+  - `cleanup_process` in Stdio transport for reliable resource cleanup
+  - Better error messages for command-not-found (`Errno::ENOENT`), broken pipe (`Errno::EPIPE`), and EOF conditions
+- **`robot.inject_mcp!`** — inject pre-connected MCP clients and tools from an external host application
+- **Conversation management APIs** on Robot
+  - `robot.chat` — access the underlying `RubyLLM::Chat` instance
+  - `robot.messages` — return conversation messages
+  - `robot.clear_messages(keep_system:)` — clear history, optionally preserving the system prompt
+  - `robot.replace_messages(messages)` — restore a saved conversation (checkpoint/restore)
+  - `robot.chat_provider` — query the provider name without reaching into chat internals
+  - `robot.mcp_client(server_name)` — find an MCP client by server name
+- **`RobotResult#duration`** — elapsed seconds for a robot run, set automatically during pipeline execution
+- **`RobotResult#raw`** — raw LLM response stored on every result (previously only settable via accessor)
+- **Pipeline error resilience** — `Robot#call` (pipeline step) rescues all exceptions so one failing robot doesn't crash the entire network; error is captured in a `RobotResult` with the elapsed duration
+
+### Changed
+
+- Bumped version to 0.0.9
+- Display `scout_path` in Rusty Circuit example updated to use `output/` subdirectory
+- Updated `onnxruntime` dependency to 0.11.0
+- Updated Gemfile.lock dependencies (erb, minitest, rails-html-sanitizer, json_schemer)
+
+## [0.0.8] - 2026-02-22
+
+### Added
+
+- **Skills as composable templates** — prepend reusable prompt snippets at build time via `skills:` parameter
+  - Skills are regular PromptManager templates (no special subdirectory)
+  - Recursive expansion — skills can declare nested skills via front matter `skills:` key
+  - Depth-first ordering — nested skills appear before their parent
+  - Cycle detection via `Set` of visited IDs; cycles log a warning and skip
+  - Config cascade — skill₁ → skill₂ → ... → main template → constructor kwargs
+  - Shared context — all skills and the main template render with the same `context:` hash
+  - Example: `examples/17_skills.rb` — SRE incident response system with flat and recursive skills
+  - 20 new tests covering expansion, ordering, cycles, config cascade, and factory passthrough
+- **Streaming content callback (`on_content:`)** — wire streaming at robot build time
+  - Stored callback fires on every `run()` call automatically
+  - Pass-through block on `run()` for per-call streaming
+  - When both exist, both fire (stored first, then runtime block)
+  - `effective_streaming_block` merges stored + runtime into a single Proc
+  - Added `:on_content` to `RunConfig::CALLBACK_FIELDS`
+  - 12 new tests
+- **Graceful tool error handling** — `RobotLab::Tool#call` wraps `execute` with `rescue StandardError`
+  - Errors returned as plain string (`"Error (tool_name): message"`) so the LLM can reason about them
+  - Class-level `raise_on_error` opt-out for critical tools
+  - MCP tools inherit the same wrapper via `Tool.create` subclasses
+  - 10 new tests
+- **`RobotRunJob` generator template** (`job.rb.tt`) — turnkey ActiveJob background job for robot runs
+  - Resolves robot class via `constantize.build`
+  - Wires `TurboStreamCallbacks` when `turbo-rails` is available (graceful no-op otherwise)
+  - Persists results via `result.export`; broadcasts completion/error via Turbo Streams
+  - `--skip-job` option on install generator
+- **`TurboStreamCallbacks` module** (`lib/robot_lab/rails_integration/turbo_stream_callbacks.rb`)
+  - `available?` — runtime check for `Turbo::StreamsChannel`
+  - `build_content_callback(stream_name:, target:)` — broadcasts HTML-escaped content chunks
+  - `build_tool_call_callback(stream_name:, target:)` — broadcasts tool call badges
+  - 13 tests
+- **Rails demo app** (`examples/18_rails/`) — minimal hand-built Rails 8 app exercising all Rails integration
+  - ChatRobot with TimeTool, RobotRunJob, Turbo Stream token streaming, SQLite persistence
+  - No asset pipeline — Turbo JS via importmap from CDN
+  - `:async` adapters for both ActiveJob and ActionCable (no Redis, no Solid Queue)
+  - User messages persisted in history; auto-scrolling via MutationObserver; form clears after submit
+  - Rake tasks: `examples:rails_setup`, `examples:rails`
+- **Routing robot example** in Rails integration docs — `ClassifierRobot` subclass with `call(result)` override
+- **Custom tool example** in Rails integration docs — `OrderLookup` tool with ActiveRecord
+
+### Changed
+
+- Bumped version to 0.0.8
+- **Renamed `RobotLab::Rails` → `RobotLab::RailsIntegration`** — eliminates constant shadowing where bare `Rails` inside `module RobotLab` resolved to the gem's own namespace instead of `::Rails`
+  - Moved `lib/robot_lab/rails/` → `lib/robot_lab/rails_integration/`
+  - Updated all require paths, loader.ignore, generator templates, tests, and documentation
+  - Reverted `::Rails` back to bare `Rails` in `config.rb` (shadow eliminated)
+- Rakefile updated with `STANDALONE_APPS` map for standalone demo apps
+- Documentation updates across README, guides, API reference, and examples for all new features
+- Updated Gemfile.lock dependencies
+
+### Fixed
+
+- `RobotLab::Rails` namespace shadowing `::Rails` in `config.rb` (`NoMethodError: undefined method 'root' for module RobotLab::Rails`)
+- MkDocs broken anchor link in `docs/examples/index.md` (`#with-conversation-history` → `#with-memory`)
+
 ## [0.0.7] - 2026-02-17 [unreleased]
 
 ### Added

data/README.md

@@ -1,7 +1,8 @@
 # RobotLab
 
-> [!CAUTION]
-> This gem is under active development. APIs and features may change without notice. See the [CHANGELOG](CHANGELOG.md) for details.
+> [!INFO]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes.  The [examples directory has a good cross section  of demo apps](examples/README.md) that show-off the various capabilities of the RobotLab library.
+
 <br>
 <table>
 <tr>
@@ -10,24 +11,28 @@
 <em>"Build robots. Solve problems."</em>
 </td>
 <td width="50%" valign="top">
-<strong>Multi-robot LLM workflow orchestration for Ruby</strong><br><br>
-RobotLab enables you to build sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own system prompt, tools, and capabilities.<br><br>
 <strong>Key Features</strong><br>
 
 - <strong>Multi-Robot Architecture</strong> - Build with specialized AI agents<br>
 - <strong>Network Orchestration</strong> - Connect robots with flexible routing<br>
-- <strong>Extensible Tools</strong> - Give robots custom capabilities<br>
-- <strong>MCP Integration</strong> - Connect to external tool servers<br>
+- <strong>Prompt Templates</strong> - Self-contained .md files with YAML front matter<br>
+- <strong>Composable Skills</strong> - Mix reusable prompt behaviors into any robot<br>
+- <strong>Extensible Tools</strong> - Custom capabilities with graceful error handling<br>
+- <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, GPUStack, LM Studio via provider passthrough<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
-- <strong>Conversation History</strong> - Persist and restore threads<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
-- <strong>Streaming</strong> - Real-time event streaming<br>
-- <strong>Rails Integration</strong> - Generators and ActiveRecord support
+- <strong>Layered Configuration</strong> - Cascading YAML, env vars, and RunConfig<br>
+- <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting
 </td>
 </tr>
 </table>
 
+<p>RobotLab enables sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own instructions, skills, tools, and capabilities.  Review the [full documentation website](https://madbomber.github.io/robot_lab) snd explore the [many examples](examples/README.md) available as working demo applications.</p>
+
 ## Installation
 
 ```bash
@@ -67,6 +72,19 @@ puts result.last_text_content
 # => "The capital of France is Paris."
 ```
 
+### Local LLM Providers
+
+For local LLM providers (Ollama, GPUStack, LM Studio, etc.), use the `provider:` parameter:
+
+```ruby
+robot = RobotLab.build(
+  name: "local_bot",
+  model: "llama3.2",
+  provider: :ollama,
+  system_prompt: "You are a helpful assistant."
+)
+```
+
 ### Configuration
 
 RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layered configuration. There is no `configure` block. Configuration is loaded automatically from multiple sources in priority order:
@@ -172,7 +190,35 @@ You are a GitHub assistant. Use available tools to help with repository tasks.
 robot = RobotLab.build(template: :github_assistant)
 ```
 
-Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `parameters`, and LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`). Constructor-provided values always take precedence over front matter.
+Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters`, and LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`). Constructor-provided values always take precedence over front matter.
+
+### Composable Skills
+
+Skills let you compose robot behaviors from reusable templates. A skill is just a template whose prompt body is prepended before the main template. Use skills to mix in capabilities like "ask clarifying questions", "respond in JSON", or "follow safety guidelines" without creating a dedicated template for every combination.
+
+```ruby
+# Compose a support robot from reusable skills
+robot = RobotLab.build(
+  name: "support",
+  template: :support_agent,
+  skills: [:clarifier, :sentiment_aware, :json_responder],
+  context: { company: "Acme Corp" }
+)
+```
+
+Skills can also be declared in template front matter:
+
+```markdown
+---
+description: Support agent with built-in skills
+skills:
+  - clarifier
+  - sentiment_aware
+---
+You are a support agent for <%= company %>.
+```
+
+Skills are expanded depth-first and can reference other skills (with automatic cycle detection). Config cascades through skills in order — later values override earlier ones, and constructor kwargs always win.
 
 ### Combining Templates with System Prompts
 
@@ -252,6 +298,28 @@ result = robot
   .run("Write a haiku about Ruby programming")
 ```
 
+## Graceful Tool Error Handling
+
+`RobotLab::Tool` automatically catches exceptions in `execute` and returns a plain-text error to the LLM instead of crashing the run. The LLM can then reason about the error and try an alternative approach.
+
+```ruby
+tool = RobotLab::Tool.create(name: "fetch_data") do |args|
+  raise IOError, "connection refused"
+end
+
+result = tool.call({})
+# => "Error (fetch_data): connection refused"
+```
+
+This applies to all tools — subclasses, factory tools, and MCP tools. For critical tools where you want exceptions to propagate, opt out per class:
+
+```ruby
+class CriticalTool < RobotLab::Tool
+  self.raise_on_error = true
+  # ...
+end
+```
+
 ## Creating a Robot with Tools
 
 ```ruby
@@ -389,14 +457,15 @@ puts result.value.last_text_content
 Connect to external tool servers via Model Context Protocol:
 
 ```ruby
-# Configure MCP server
+# Configure MCP server (with optional timeout)
 filesystem_server = {
   name: "filesystem",
   transport: {
     type: "stdio",
     command: "mcp-server-filesystem",
     args: ["/path/to/allowed/directory"]
-  }
+  },
+  timeout: 30  # seconds (default: 15)
 }
 
 # Create robot with MCP server - tools are auto-discovered
@@ -406,10 +475,18 @@ robot = RobotLab.build(
   mcp: [filesystem_server]
 )
 
+# Optionally connect eagerly (default is lazy on first run)
+robot.connect_mcp!
+
+# Check connection status
+puts "Failed: #{robot.failed_mcp_server_names}" if robot.failed_mcp_server_names.any?
+
 # Robot can now use filesystem tools
 result = robot.run("List the files in the current directory")
 ```
 
+MCP connections are resilient: failed servers are automatically retried on subsequent `run()` calls, and one failing server does not prevent others from connecting.
+
 ## Message Bus
 
 Robots can communicate bidirectionally via an optional message bus, independent of the Network pipeline. This enables negotiation loops, convergence patterns, and cyclic workflows.
@@ -502,26 +579,48 @@ Key features:
 
 ## Streaming
 
-Use a `Streaming::Context` with a publish callback to receive real-time events:
+Stream LLM content in real-time using a stored callback, a per-call block, or both. Each receives a [`RubyLLM::Chunk`](https://rubyllm.com/streaming/#basic-streaming) — use `chunk.content` for the text delta. Chunks also carry `model_id`, `tool_calls`, `thinking`, and token usage on the final chunk.
+
+### Stored Callback (`on_content:`)
+
+Wire streaming at build time. The callback fires on every `run()` call automatically:
 
 ```ruby
-handler = lambda do |event|
-  case event[:event]
-  when RobotLab::Streaming::Events::TEXT_DELTA
-    print event[:data][:delta]
-  when RobotLab::Streaming::Events::RUN_COMPLETED
-    puts "\nDone!"
-  end
-end
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { print chunk.content }
+)
+
+robot.run("Tell me a story")  # streams automatically
+```
+
+### Per-Call Block
+
+Pass a block to `run()` for one-off streaming:
+
+```ruby
+robot = RobotLab.build(name: "assistant", system_prompt: "You are helpful.")
+
+robot.run("Tell me a story") { |chunk| print chunk.content }
+```
 
-context = RobotLab::Streaming::Context.new(
-  run_id: SecureRandom.uuid,
-  message_id: SecureRandom.uuid,
-  scope: "robot",
-  publish: handler
+### Both Together
+
+When both a stored callback and a runtime block are provided, both fire (stored first):
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful.",
+  on_content: ->(chunk) { log_chunk(chunk.content) }
 )
+
+robot.run("Tell me a story") { |chunk| stream_to_client(chunk.content) }
 ```
 
+The `on_content:` callback participates in the RunConfig cascade, so it can be set at the network or config level and inherited by robots.
+
 ## Rails Integration
 
 ```bash

data/Rakefile

@@ -52,7 +52,12 @@ namespace :examples do
     "16_writers_room" => "writers_room.rb"
   }.freeze
 
-  desc "Run all examples"
+  # Subdirectory demos that are standalone apps (not run via `ruby`)
+  STANDALONE_APPS = {
+    "18_rails" => { setup: "bin/setup", run: "bin/dev" }
+  }.freeze
+
+  desc "Run all examples (excludes standalone apps like 18_rails)"
   task :all do
     # Single-file examples
     Dir.glob("examples/*.rb").sort.each do |example|
@@ -72,6 +77,15 @@ namespace :examples do
       puts '=' * 60
       ruby path
     end
+
+    # Remind about standalone apps
+    STANDALONE_APPS.each do |dir, commands|
+      puts "\n#{'=' * 60}"
+      puts "Skipped: examples/#{dir} (standalone app)"
+      puts "  Setup: cd examples/#{dir} && #{commands[:setup]}"
+      puts "  Run:   cd examples/#{dir} && #{commands[:run]}"
+      puts '=' * 60
+    end
   end
 
   desc "Run a specific example by number (e.g., rake examples:run[1])"
@@ -89,6 +103,16 @@ namespace :examples do
     dir = Dir.glob("examples/#{padded}_*/").first
     if dir
       dir_name = File.basename(dir)
+
+      # Check if it's a standalone app
+      if STANDALONE_APPS.key?(dir_name)
+        commands = STANDALONE_APPS[dir_name]
+        puts "Example #{args[:num]} is a standalone app (#{dir_name})."
+        puts "  Setup: cd examples/#{dir_name} && #{commands[:setup]}"
+        puts "  Run:   cd examples/#{dir_name} && #{commands[:run]}"
+        next
+      end
+
       entry = SUBDIR_ENTRY_POINTS[dir_name]
       if entry && File.exist?(File.join(dir, entry))
         ruby File.join(dir, entry)
@@ -99,6 +123,20 @@ namespace :examples do
       puts "Example #{args[:num]} not found"
     end
   end
+
+  desc "Setup the Rails demo app (example 18)"
+  task :rails_setup do
+    Dir.chdir("examples/18_rails") do
+      sh "bin/setup"
+    end
+  end
+
+  desc "Start the Rails demo app (example 18)"
+  task :rails do
+    Dir.chdir("examples/18_rails") do
+      sh "bin/dev"
+    end
+  end
 end
 
 namespace :docs do