robot_lab 0.2.1 → 0.2.7

data/docs/api/core/state.md

@@ -1,255 +1,145 @@
-# Memory (State Management)
+# StateProxy
 
-Memory manages conversation data, results, and runtime state. There is no separate `State` class; `Memory` serves this role.
+!!! danger "There is no `RobotLab::State` class"
+    RobotLab has never had a `State` class. Runtime state lives in
+    [`RobotLab::Memory`](memory.md). The only state object is
+    **`RobotLab::StateProxy`** (`lib/robot_lab/state_proxy.rb`), which is what
+    `memory.data` returns — and that is what this page documents.
 
-## Class: `RobotLab::Memory`
+    This page is listed as "State" in the site navigation for historical reasons.
+    For the key-value store, subscriptions, blocking reads, results, and
+    serialization, go to **[Memory](memory.md)**.
 
-```ruby
-memory = RobotLab.create_memory(
-  data: { user_id: "123" }
-)
-```
-
-## Attributes
-
-### session_id
-
-```ruby
-memory.session_id  # => String | nil
-```
-
-Conversation session identifier for persistence.
-
-### data
-
-```ruby
-memory.data  # => StateProxy
-```
-
-Access workflow data as a proxy object.
-
-```ruby
-memory.data[:user_id]          # Hash access
-memory.data.user_id            # Method access
-memory.data[:status] = "active"
-```
-
-### results
-
-```ruby
-memory.results  # => Array<RobotResult>
-```
-
-All robot execution results.
+## Class: `RobotLab::StateProxy`
 
-### messages
+A thin wrapper around a symbol-keyed Hash that adds method-style access and an
+optional change callback. It is not a `Hash` subclass and does not implement the
+full `Hash` interface — the supported methods are listed below.
 
 ```ruby
-memory.messages  # => Array<Message>
-```
-
-Formatted conversation messages for LLM.
+proxy = RobotLab::StateProxy.new({ count: 0, name: "test" })
 
-## Methods
-
-### append_result
-
-```ruby
-memory.append_result(robot_result)
+proxy[:count] = 1
+proxy.count       # => 1
+proxy[:name]      # => "test"
+proxy.to_h        # => { count: 1, name: "test" }
 ```
 
-Add a robot result to history.
+## Where you get one
 
-### set_results
+`memory.data` — the reserved `:data` key of a `Memory` — is the only place the
+framework hands you a `StateProxy`:
 
 ```ruby
-memory.set_results(array_of_results)
-```
-
-Replace all results.
-
-### results_from
-
-```ruby
-memory.results_from(5)  # => Array<RobotResult>
-```
-
-Get results starting at index.
-
-### session_id=
-
-```ruby
-memory.session_id = "session_123"
-```
-
-Set the session identifier.
+memory = RobotLab.create_memory(data: { user_id: "123" })
 
-### format_history
-
-```ruby
-memory.format_history  # => Array<Message>
-```
-
-Format results as conversation history.
-
-### clone
-
-```ruby
-new_memory = memory.clone
-```
-
-Create a deep copy.
-
-### to_h
-
-```ruby
-memory.to_h  # => Hash
+memory.data                    # => #<RobotLab::StateProxy {user_id: "123"}>
+memory.data[:user_id]          # => "123"     Hash access
+memory.data.user_id            # => "123"     method access
+memory.data[:status] = "active"
 ```
 
-Hash representation.
-
-### to_json
-
-```ruby
-memory.to_json  # => String
-```
+The proxy is memoized (`@data ||= StateProxy.new(...)`) and is reset whenever
+`memory[:data] = ...` or `memory.reset` is called.
 
-JSON representation.
+!!! warning "`memory.data` mutations are not reactive"
+    `memory.data[:x] = 1` writes through the proxy into the `:data` hash. It does
+    **not** go through `Memory#set`, so it wakes no blocking readers and notifies
+    no subscribers. Use `memory.set(:x, 1)` on a non-reserved key when you need
+    reactive semantics.
 
-### from_hash (class method)
+## Constructor
 
 ```ruby
-memory = Memory.from_hash(hash)
+RobotLab::StateProxy.new(data = {}, on_change: nil)
 ```
 
-Restore from hash.
-
-## StateProxy
-
-The `data` attribute is a `StateProxy`:
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `Hash` | `{}` | Initial data. Keys are converted to Symbols via `transform_keys(&:to_sym)` |
+| `on_change` | `Proc`, `nil` | `nil` | Called as `on_change.call(key, old_value, new_value)` on `[]=`, and only when the value actually changed (`old_value != value`) |
 
-```ruby
-proxy = memory.data
-
-# Hash-style access
-proxy[:key]
-proxy[:key] = value
-
-# Method-style access
-proxy.key
-proxy.key = value
-
-# Hash operations
-proxy.key?(:key)
-proxy.keys
-proxy.values
-proxy.each { |k, v| ... }
-proxy.merge!(other_hash)
-proxy.delete(:key)
-proxy.to_h
-proxy.empty?
-proxy.size
-```
+`Memory#data` constructs the proxy **without** an `on_change` callback.
 
-## Creating Memory
+## Methods
 
-### Basic
+### Element access
 
 ```ruby
-memory = RobotLab.create_memory
+proxy[:key]          # => value (keys are symbolized on read)
+proxy[:key] = value  # fires on_change when the value differs
 ```
 
-### With Data
-
-```ruby
-memory = RobotLab.create_memory(
-  data: {
-    user_id: "user_123",
-    order_id: "ord_456"
-  }
-)
-```
+Both `[]` and `[]=` call `key.to_sym`, so `proxy["a"]` and `proxy[:a]` are the same entry.
 
-### With Session ID
+### Method-style access
 
 ```ruby
-memory = RobotLab.create_memory
-memory.session_id = "session_123"
+proxy.name        # same as proxy[:name] — only when :name already exists
+proxy.name = "x"  # same as proxy[:name] = "x" — always works
 ```
 
-### With Existing Results
+Implemented with `method_missing`. A **getter** for a key that does not exist
+falls through to `super` and raises `NoMethodError`; a **setter** always works and
+creates the key. `respond_to?(:name)` is true only once the key exists.
 
-```ruby
-memory = RobotLab.create_memory
-memory.set_results(previous_results)
-```
+Method-style access cannot reach a key whose name collides with a real
+`StateProxy` method (`keys`, `size`, `map`, `each`, `delete`, `dup`, `inspect`, …).
+Use `proxy[:keys]` for those.
 
-## UserMessage
+### Full method list
 
-Enhanced message with metadata:
-
-```ruby
-message = UserMessage.new(
-  "What's my order status?",
-  session_id: "session_123",
-  system_prompt: "Respond in Spanish",
-  metadata: { source: "web" }
-)
+| Method | Returns | Notes |
+|--------|---------|-------|
+| `[](key)` | value | Symbolizes the key |
+| `[]=(key, value)` | value | Symbolizes the key; fires `on_change` |
+| `key?(key)` | `Boolean` | Aliases: `has_key?`, `include?` |
+| `keys` | `Array<Symbol>` | |
+| `values` | `Array` | |
+| `each { \|k, v\| }` | delegates to `Hash#each` | |
+| `map { \|k, v\| }` | `Array` | |
+| `delete(key)` | deleted value | Does **not** fire `on_change` |
+| `merge!(other)` | `self` | Assigns each pair through `[]=`, so `on_change` fires per key |
+| `to_h` | `Hash` | A **shallow** `dup`; aliased as `to_hash` |
+| `dup` | `StateProxy` | Deep duplicate, preserving `on_change` |
+| `empty?` | `Boolean` | |
+| `size` | `Integer` | Aliased as `length` |
+| `inspect` | `String` | `#<RobotLab::StateProxy {...}>` |
 
-message.content       # => "What's my order status?"
-message.session_id    # => "session_123"
-message.system_prompt # => "Respond in Spanish"
-message.metadata      # => { source: "web" }
-message.id            # => UUID
-message.created_at    # => Time
-```
+There is no `clear`, no `fetch`, no `dig`, and no `clone`. `to_h` is a shallow
+copy, so nested Hashes are shared with the proxy — mutate them and the proxy sees
+it. Use `dup` when you need isolation.
 
 ## Examples
 
-### Accessing Data
+### Nested data
 
 ```ruby
 memory = RobotLab.create_memory(
   data: { user: { name: "Alice", plan: "pro" } }
 )
 
-memory.data[:user][:name]  # => "Alice"
+memory.data[:user][:name]  # => "Alice"   (plain Hash below the top level)
+memory.data.user           # => { name: "Alice", plan: "pro" }
 memory.data.to_h           # => { user: { name: "Alice", plan: "pro" } }
 ```
 
-### Working with Results
-
-```ruby
-# After running network
-memory.results.size           # Number of results
-memory.results.last           # Most recent
-memory.results.map(&:robot_name)  # ["classifier", "support"]
-```
-
-### Using Reactive Memory
-
-```ruby
-memory.set(:intent, "billing")
-intent = memory.get(:intent)
-
-memory.subscribe(:status) do |change|
-  puts "Status changed to #{change.value} by #{change.writer}"
-end
-```
+Only the top level is proxied. Nested values are returned as-is — a nested Hash
+is a plain Hash, not another `StateProxy`.
 
-### Serialization
+### Change tracking
 
 ```ruby
-# Save memory
-json = memory.to_json
-File.write("memory.json", json)
+proxy = RobotLab::StateProxy.new({ status: "pending" }, on_change: lambda { |key, old, new|
+  puts "#{key}: #{old.inspect} -> #{new.inspect}"
+})
 
-# Restore memory
-data = JSON.parse(File.read("memory.json"))
-memory = Memory.from_hash(data)
+proxy[:status] = "active"   # "status: \"pending\" -> \"active\""
+proxy[:status] = "active"   # silent — value unchanged
+proxy.delete(:status)       # silent — delete does not fire on_change
 ```
 
 ## See Also
 
+- [Memory](memory.md) — the store that owns the proxy: keys, subscriptions, blocking reads, results, serialization
 - [State Management Architecture](../../architecture/state-management.md)
-- [Memory](memory.md)

data/docs/api/core/tool.md

@@ -49,6 +49,12 @@ Tool.new(robot: nil)
 |------|------|-------------|
 | `robot` | `Robot, nil` | The owning robot instance |
 
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `RobotLab::Robot::DEFAULT_MAX_TOOLS` | `128` | Ceiling on the number of tools a robot hands the provider per turn. Override per robot with `RunConfig#max_tools`; a nil, zero, or negative value falls back to 128, so the cap cannot be disabled |
+
 ## Class Methods
 
 ### raise_on_error / raise_on_error?
@@ -58,7 +64,60 @@ MyTool.raise_on_error = true
 MyTool.raise_on_error?  # => true
 ```
 
-Per-class flag controlling whether `call` propagates exceptions from `execute` instead of catching them. Defaults to `false`. Does not affect other tool classes.
+Per-class flag controlling whether `call` propagates exceptions from `execute` instead of catching them. Defaults to `false`.
+
+!!! warning "`raise_on_error` does not walk the inheritance chain"
+    The reader is `defined?(@raise_on_error) ? @raise_on_error : false` — it
+    inspects only the receiving class's own instance variable. A subclass of a
+    class that set `self.raise_on_error = true` silently reverts to `false`:
+
+    ```ruby
+    class Critical < RobotLab::Tool; self.raise_on_error = true; end
+    class Derived  < Critical; end
+
+    Critical.raise_on_error?  # => true
+    Derived.raise_on_error?   # => false   <-- errors are swallowed again
+    ```
+
+    Set the flag explicitly on every subclass that needs it. Contrast
+    [`ractor_safe`](#ractor_safe-ractor_safe), which *does* walk the chain.
+
+### ractor_safe / ractor_safe?
+
+```ruby
+class Pure < RobotLab::Tool
+  ractor_safe true
+end
+
+Pure.ractor_safe?  # => true
+```
+
+Declares that the tool class is safe to run inside a Ractor. With no argument it
+acts as a getter; with a Boolean it sets the value. `ractor_safe?` is an alias
+for `ractor_safe`.
+
+Unlike `raise_on_error`, the getter **does** walk the inheritance chain: if the
+class has no `@ractor_safe` of its own it asks its superclass, terminating at
+`false`.
+
+```ruby
+class Pure    < RobotLab::Tool; ractor_safe true; end
+class Derived < Pure; end
+
+Derived.ractor_safe?   # => true — inherited
+```
+
+**Ractor pool dispatch.** `Tool#call` routes through the Ractor worker pool
+(`RobotLab.ractor_pool.submit(self.class.name, args)`) only when **all three**
+hold:
+
+1. `self.class.ractor_safe?` is true
+2. `self.class.name` is not `nil` (an anonymous class — including everything from
+   `Tool.create` — always falls through to the inline path)
+3. `RobotLab.extension_loaded?(:ractor)` — i.e. the `robot_lab-ractor` gem is loaded
+
+Otherwise `execute` runs inline on the calling thread. Ractor-safe tools must be
+stateless: they are instantiated fresh inside the worker for each call.
 
 ### Tool.create
 
@@ -82,9 +141,18 @@ Tool.create(
 | `name` | `String, Symbol` | Tool identifier |
 | `description` | `String` | What the tool does |
 | `parameters` | `Hash` | JSON Schema parameter definition |
-| `mcp` | `String` | MCP server name |
+| `mcp` | `String` | MCP server name; makes `mcp?` true |
 | `robot` | `Robot` | Owning robot instance |
-| `&handler` | `Block` | Receives `args` hash, returns result |
+| `&handler` | `Block` | Receives the `args` hash, returns the result |
+
+`create` builds an **anonymous** subclass (`Class.new(self)`) and stashes the
+explicit name on the instance. Two consequences:
+
+- `parameters` is read with **symbol** keys (`params_hash[:properties]`,
+  `pdef[:type]`, `pdef[:description]`, `params_hash[:required]`). A string-keyed
+  schema is silently ignored and the tool ends up with no parameters.
+- Because `self.class.name` is `nil`, a `create`d tool never dispatches to the
+  Ractor pool even if you set `ractor_safe`.
 
 ## Inherited DSL (from RubyLLM::Tool)
 
@@ -105,6 +173,22 @@ class MyTool < RobotLab::Tool
 end
 ```
 
+`param` accepts exactly four options — anything else raises
+`ArgumentError: unknown keyword`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `type` | `String` | `"string"` | JSON Schema type (`"string"`, `"integer"`, `"number"`, `"boolean"`, `"array"`, `"object"`) |
+| `desc` | `String` | `nil` | Description shown to the LLM |
+| `description` | `String` | `nil` | Synonym for `desc` |
+| `required` | `Boolean` | `true` | Whether the LLM must supply the parameter |
+
+!!! warning "There is no `enum:` option"
+    `param :unit, type: "string", enum: %w[c f]` raises
+    `ArgumentError: unknown keyword: :enum`. Constrain the value in the
+    description and validate it inside `execute`, or supply a full JSON Schema
+    through [`Tool.create(parameters:)`](#toolcreate).
+
 ### execute
 
 ```ruby
@@ -162,7 +246,19 @@ The MCP server name, set via `Tool.create(mcp: "server_name")`.
 tool.name  # => String
 ```
 
-Returns the tool name. For subclasses, derived from the class name (CamelCase to snake_case). For `create`d tools, returns the explicit name.
+Returns the tool name. For `create`d tools, the explicit `name:` you passed. For
+subclasses, ruby_llm derives it from the class name — **including the namespace**,
+with `::` rendered as `--`:
+
+```ruby
+RobotLab::AskUser.new.name   # => "robot_lab--ask_user"
+
+class Sub1 < RobotLab::Tool; end
+Sub1.new.name                # => "sub1"   (top-level class, no namespace)
+```
+
+This matters when writing a `tools:` name allowlist: the allowlist must contain
+the fully-derived name (`"robot_lab--ask_user"`), not the short one.
 
 ### mcp?
 
@@ -178,13 +274,35 @@ Whether this is an MCP-provided tool.
 result = tool.call(args_hash)
 ```
 
-Overrides `RubyLLM::Tool#call` with graceful error handling. Converts string keys to symbols and calls `execute(**args)`. If `execute` raises a `StandardError`, the error is caught and returned as a plain-text string the LLM can reason about:
+Overrides `RubyLLM::Tool#call`. The whole invocation is wrapped in the
+`:tool_call` hook family, then dispatched either to the Ractor pool or inline
+(see [`ractor_safe`](#ractor_safe-ractor_safe)); ruby_llm's `call` converts
+string keys to symbols and invokes `execute(**args)`.
 
-```
-Error (tool_name): exception message
+Errors are caught and returned to the LLM as a plain-text string it can reason
+about. There are two distinct paths:
+
+| Raised | Returned text | Logged? |
+|--------|---------------|---------|
+| `RobotLab::ToolError` | `Error (<name>): <message>` — plus `" (retryable)"` when `RobotLab::Errors.retryable?` is true | **No** |
+| any other `StandardError` | `Error (<name>): <message>` | Yes — `RobotLab.config.logger.warn("Tool '<name>' error: <Class>: <message>")` |
+
+```ruby
+class T2 < RobotLab::Tool
+  description "t"
+  def execute(**) = raise RobotLab::ToolError.new("nope", retryable: true)
+end
+T2.new.call({})   # => "Error (t2): nope (retryable)"   -- nothing logged
+
+class T3 < RobotLab::Tool
+  description "t"
+  def execute(**) = raise ArgumentError, "bad"
+end
+T3.new.call({})   # => "Error (t3): bad"                -- WARN logged
 ```
 
-The error is also logged via `RobotLab.config.logger` at `:warn` level.
+`" (retryable)"` is appended only for `ToolError`/`MCPError` instances
+constructed with `retryable: true` — see [Retryable Errors](../errors.md#retryable-errors).
 
 To propagate exceptions instead of catching them (for critical tools), set `raise_on_error` on the class:
 
@@ -195,7 +313,8 @@ class CriticalTool < RobotLab::Tool
 end
 ```
 
-`raise_on_error` is per-class (defaults to `false`) and does not affect other tool classes.
+`raise_on_error` applies to **both** paths, is per-class, defaults to `false`, and
+[is not inherited by subclasses](#raise_on_error-raise_on_error).
 
 ### params_schema
 
@@ -219,7 +338,16 @@ Inherited. Returns provider-specific parameters (e.g., `{ strict: true }`).
 tool.to_h  # => Hash
 ```
 
-Hash representation with `:name`, `:description`, `:mcp`.
+Hash representation with `:name`, `:description`, `:mcp` — `.compact`ed, so
+`:description` and `:mcp` are absent when nil:
+
+```ruby
+class T4 < RobotLab::Tool
+  description "t"
+  def execute(**) = nil
+end
+T4.new.to_h   # => { name: "t4", description: "t" }   -- no :mcp key
+```
 
 ### to_json
 
@@ -253,14 +381,18 @@ class AdjustTemperature < RobotLab::Tool
   end
 end
 
-# Pass robot: self when constructing
-robot = RobotLab.build(
-  name: "creative_bot",
-  system_prompt: "You are creative.",
-  local_tools: [AdjustTemperature.new(robot: self)]
-)
+# The robot must exist before the tool can reference it, so attach afterwards
+robot = RobotLab.build(name: "creative_bot", system_prompt: "You are creative.")
+robot.local_tools << AdjustTemperature.new(robot: robot)
+
+robot.run("Be more creative.", tools: :inherit)
 ```
 
+Passing the bare **class** (`local_tools: [AdjustTemperature]`) leaves
+`tool.robot` as `nil` — ruby_llm instantiates it with no arguments — and
+`robot.with_temperature` then raises `NoMethodError` on nil. Instantiate with
+`robot:` whenever the tool needs its owner.
+
 ## Parameter Types
 
 ### String
@@ -319,6 +451,8 @@ end
 | `choices` | `Array` | No | Numbered choices to present |
 | `default` | `String` | No | Value returned when user presses Enter without typing |
 
+Its LLM-facing name is **`robot_lab--ask_user`** (namespace included), not `ask_user`.
+
 ### IO Resolution
 
 The tool reads input and writes output using the owning robot's `input`/`output` accessors:
@@ -326,10 +460,18 @@ The tool reads input and writes output using the owning robot's `input`/`output`
 1. `robot.input` / `robot.output` if set
 2. Falls back to `$stdin` / `$stdout`
 
+The prompt label is `robot&.name || "Robot"`.
+
+!!! warning "Attach an instance, not the class"
+    `local_tools: [RobotLab::AskUser]` gives ruby_llm a bare class, which it
+    instantiates with no arguments — so `tool.robot` is `nil`, IO falls back to
+    `$stdin`/`$stdout`, and every prompt is labelled `[Robot]`. Pass
+    `RobotLab::AskUser.new(robot: robot)` to get the robot's own name and streams.
+
 ### Terminal Output
 
 ```
-[robot_name] What programming language do you want to learn?
+[interviewer] What programming language do you want to learn?
   1. Ruby
   2. Python
   3. Go
@@ -341,10 +483,13 @@ The tool reads input and writes output using the owning robot's `input`/`output`
 ```ruby
 robot = RobotLab.build(
   name: "interviewer",
-  system_prompt: "Interview the user about their project needs. Use ask_user to gather information.",
-  local_tools: [RobotLab::AskUser]
+  system_prompt: "Interview the user about their project needs. " \
+                 "Use robot_lab--ask_user to gather information."
 )
-robot.run("Find out what the user wants to build")
+robot.local_tools << RobotLab::AskUser.new(robot: robot)
+
+# run() defaults to tools: :none — :inherit is required for the tool to be sent
+robot.run("Find out what the user wants to build", tools: :inherit)
 ```
 
 ### Testing with StringIO