robot_lab 0.2.6 → 0.2.7

data/docs/getting-started/installation.md

@@ -37,36 +37,47 @@ RobotLab automatically installs these core dependencies:
 |-----|---------|
 | `ruby_llm` (~> 1.12) | LLM provider integrations (Anthropic, OpenAI, Gemini, etc.) |
 | `prompt_manager` (~> 1.0) | Template-based prompt management with YAML front matter |
-| `simple_flow` (~> 0.3) | Pipeline workflow execution for networks |
+| `simple_flow` (~> 0.4) | Pipeline workflow execution for networks |
 | `myway_config` (~> 0.1) | Layered configuration (defaults, env vars, config files) |
-| `ruby_llm-mcp` | Model Context Protocol client for external tool servers |
-| `ruby_llm-schema` | Schema validation for structured outputs |
-| `ruby_llm-semantic_cache` | Semantic caching for LLM responses |
+| `ruby_llm-mcp` (~> 1.0) | Model Context Protocol client for external tool servers |
+| `ruby_llm-schema` (~> 0.3) | Schema validation for structured outputs |
+| `ruby_llm-semantic_cache` (~> 0.1) | Semantic caching for LLM responses |
 | `zeitwerk` (~> 2.6) | Autoloading and eager loading |
 | `async` (~> 2.0) | Fiber-based concurrency |
+| `async-http` (~> 0.60) | MCP SSE and streamable-HTTP transports |
+| `async-websocket` (~> 0.30) | MCP WebSocket transport |
+| `typed_bus` (~> 0.0.1) | Typed message bus for robot-to-robot messaging |
+| `ractor_queue` (~> 0.2) | Queue used by the Network bus poller |
 
-### Optional Dependencies
-
-For specific features, you may need additional gems:
-
-=== "MCP WebSocket Transport"
+> [!NOTE]
+> `async-http` and `async-websocket` are hard runtime dependencies, not optional
+> extras — they install with the gem whether or not you use MCP.
 
-    ```ruby
-    gem "async-websocket"
-    ```
+### Optional Dependencies
 
-=== "MCP HTTP Transport"
+Several features are gated behind gems the core gem does **not** install. Add
+whichever you need to your own `Gemfile`:
 
-    ```ruby
-    gem "async-http"
-    ```
+| Gem | Enables | Without it |
+|-----|---------|------------|
+| `classifier` (~> 2.3) | `robot.compress_history`, `RobotLab::Convergence` | `RobotLab::DependencyError` |
+| `robot_lab-document_store` | `memory.store_document` / `search_documents` / `document_keys` / `delete_document`, and `AgentSkill` catalogs | `RobotLab::DependencyError` (skill catalogs raise `LoadError`) |
+| `redis` | Redis-backed `Memory` | `Memory#redis?` is `false` and the store silently stays in-process |
+| `robot_lab-ractor` | Ractor-parallel tool execution and `Network` ractor scheduling | tools run inline; a network run with `parallel_mode: :ractor` raises `RobotLab::DependencyError` |
 
-=== "Rails Integration"
+```ruby
+# Gemfile
+gem "classifier", "~> 2.3"
+gem "robot_lab-document_store"
+gem "redis"
+gem "robot_lab-ractor"
+```
 
-    ```ruby
-    # Rails is detected automatically
-    gem "rails", ">= 7.0"
-    ```
+> [!NOTE]
+> Several capabilities advertised on the [home page](../index.md) — embedding-based
+> document retrieval, runtime skill matching, and CPU parallelism — depend on the
+> gems above. They are genuinely optional, but the feature is unavailable until the
+> gem is installed.
 
 ## Verify Installation
 
@@ -84,33 +95,33 @@ Run it:
 
 ```bash
 ruby test_robot_lab.rb
-# => RobotLab version: 0.1.0
+# => RobotLab version: 0.2.6
 # => Installation successful!
 ```
 
 ## Rails Installation
 
-For Rails applications, use the install generator:
-
-```bash
-rails generate robot_lab:install
-```
-
-This creates:
+> [!IMPORTANT]
+> The core `robot_lab` gem ships **no Rails Engine, no Railtie, and no generators**.
+> Rails integration lives in the separate
+> [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails) gem.
 
-- `config/initializers/robot_lab.rb` - Configuration file
-- `db/migrate/*_create_robot_lab_tables.rb` - Database migrations
-- `app/models/robot_lab_thread.rb` - Thread model
-- `app/models/robot_lab_result.rb` - Result model
-- `app/robots/` - Directory for robot definitions
-- `app/tools/` - Directory for tool definitions
+Core RobotLab only performs two bare `defined?(::Rails)` checks: it uses
+`Rails.logger` as the default logger, and it resolves the template path to
+`app/prompts` when `Rails.root` is present. Nothing else is Rails-aware.
 
-Then run migrations:
+For generators, an `ActiveJob` base class, and Turbo Stream broadcasting, add the
+extension gem:
 
-```bash
-rails db:migrate
+```ruby
+# Gemfile
+gem "robot_lab"
+gem "robot_lab-rails"
 ```
 
+Then follow that gem's own installation instructions for its generators and
+migrations.
+
 ## Environment Setup
 
 RobotLab uses a layered configuration system (see [Configuration](configuration.md) for full details). The simplest way to get started is with environment variables:
@@ -165,11 +176,12 @@ gem install robot_lab --verbose
 
 ### Missing Dependencies
 
-If you see "LoadError" for optional gems:
+If you see a `LoadError` (or a `RobotLab::DependencyError`) naming a gem RobotLab
+does not depend on, add it yourself:
 
 ```bash
-# Install the specific gem mentioned in the error
-bundle add async-websocket
+# e.g. compress_history / Convergence need the classifier gem
+bundle add classifier
 ```
 
 ### API Key Issues

data/docs/getting-started/quick-start.md

@@ -13,11 +13,15 @@ export ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY="sk-ant-..."
 Or create a config file at `./config/robot_lab.yml`:
 
 ```yaml
-defaults:
-  ruby_llm:
-    anthropic_api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
+ruby_llm:
+  anthropic_api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
 ```
 
+> [!IMPORTANT]
+> Config files are **flat** — put the keys at the top level. Wrapping them in a
+> `defaults:` key (as the gem's own bundled `defaults.yml` does) makes the whole
+> file silently ignored.
+
 See [Configuration](configuration.md) for all configuration options.
 
 ## Step 2: Create a Robot
@@ -140,12 +144,30 @@ assistant = RobotLab.build(
   local_tools: [CurrentTime]
 )
 
-result = assistant.run("What time is it right now?")
+# tools: :inherit is REQUIRED -- run() sends no tools without it
+result = assistant.run("What time is it right now?", tools: :inherit)
 puts result.last_text_content
 ```
 
 Tools are passed to the robot via the `local_tools:` keyword argument as an array of `RubyLLM::Tool` subclasses.
 
+> [!WARNING]
+> **Attaching a tool is not the same as sending it.** `Robot#run` defaults to
+> `tools: :none`, which means "send zero tools this turn". Without
+> `tools: :inherit` on the run, the example above builds fine, calls the LLM
+> fine, and the model simply never sees `CurrentTime` — it will guess or say it
+> cannot check the time. The same applies to MCP: pass
+> `mcp: :inherit, tools: :inherit` to connect MCP servers and expose their tools.
+>
+> Do **not** try to fix this by passing `tools: :inherit` to `RobotLab.build` for
+> a standalone robot like this one — at build time it resolves against the global
+> `:none` and yields an allowlist matching nothing, suppressing the tools even
+> when the run asks for them. Put it on the `run` call.
+>
+> (The one place build-time `:inherit` *is* correct is a robot in a network, where
+> it opts into the network `config:`'s list — see
+> [Creating Networks](../guides/creating-networks.md).)
+
 ## Method Chaining
 
 Robots support a chaining API for runtime adjustments:
@@ -162,7 +184,20 @@ result = robot
 puts result.last_text_content
 ```
 
-Available chaining methods include `with_instructions`, `with_temperature`, `with_model`, `with_max_tokens`, `with_top_p`, `with_tools`, and more.
+The complete set of chaining methods is `with_context`, `with_headers`,
+`with_instructions`, `with_model`, `with_params`, `with_schema`,
+`with_temperature`, `with_thinking`, `with_tool`, `with_tools`, plus RobotLab's
+own `with_template` and `with_bus`.
+
+> [!NOTE]
+> There is no `with_max_tokens`, `with_top_p`, `with_top_k`, `with_stop`,
+> `with_presence_penalty`, or `with_frequency_penalty` — those raise
+> `NoMethodError`. Set them as constructor keyword arguments
+> (`RobotLab.build(..., max_tokens: 2000)`) or through `with_params`:
+>
+> ```ruby
+> robot.with_params(max_tokens: 2000, top_p: 0.3).run("...")
+> ```
 
 ## Multi-Robot Network
 
@@ -205,12 +240,22 @@ if result.value.is_a?(RobotLab::RobotResult)
   puts result.value.last_text_content
 end
 
-# Access intermediate results by task name
+# Access intermediate results by ROBOT name (see note below)
 if result.context[:analyst]
   puts "\nAnalysis: #{result.context[:analyst].last_text_content}"
 end
 ```
 
+> [!IMPORTANT]
+> `result.context` is keyed by the **robot's** `name:`, not by the task name.
+> Internally each robot writes `result.with_context(@name.to_sym, robot_result)`.
+> The lookup above works only because the robot is named `"analyst"` *and* its
+> task is named `:analyst`. If you register a robot under a different task name —
+> `task :first_pass, analyst` — the result is still at
+> `result.context[:analyst]`, not `result.context[:first_pass]`. Keeping the two
+> names identical, as in this example, is the simplest way to avoid the
+> surprise.
+
 ### Network Task Dependencies
 
 Tasks declare their dependencies to control execution order: