robot_lab 0.2.6 → 0.2.7

data/docs/api/core/network.md

@@ -11,6 +11,17 @@ network = RobotLab.create_network(name: "support", config: config) do
 end
 ```
 
+`RobotLab.create_network(name:, concurrency: :auto, config: nil, &block)` is the
+factory. `Network.new` additionally accepts `memory:` and `parallel_mode:`:
+
+```ruby
+RobotLab::Network.new(name:, concurrency: :auto, memory: nil, config: nil, parallel_mode: :async, &block)
+```
+
+There is no `router:` and no `robots:` keyword. Routing is done by subclassing
+`Robot`, overriding `#call`, and activating optional tasks — see
+[Conditional Routing](#conditional-routing).
+
 ## Attributes
 
 ### name
@@ -27,7 +38,37 @@ Network identifier for logging and debugging.
 network.robots  # => Hash<String, Robot>
 ```
 
-Hash of robots keyed by name.
+Robots keyed by **String**. The key depends on how the robot was registered:
+
+| Registered via | Key |
+|----------------|-----|
+| `task(:analyzer, robot)` | the **task** name — `"analyzer"` — regardless of `robot.name` |
+| `add_robot(robot)` | `robot.name` |
+
+```ruby
+n = RobotLab.create_network(name: "n") do
+  task :a, RobotLab.build(name: "alpha"), depends_on: :none
+end
+n.add_robot(RobotLab.build(name: "helper"))
+
+n.robots.keys        # => ["a", "helper"]
+n.crew.map(&:name)   # => ["alpha", "helper"]
+```
+
+Examples that assume the two coincide only work when you name the robot after
+its task. `result.context` is keyed by the **robot's** name (`@name.to_sym`), not
+the task name — another reason to keep them identical.
+
+### memory
+
+```ruby
+network.memory  # => Memory
+```
+
+Shared reactive memory for every robot in the network. It is passed to each robot
+on `run()` as `network_memory:`, so in-network robots read and write this instance
+instead of their own inherent memory. Created as `Memory.new(network_name: name)`
+unless one is supplied to `Network.new(memory:)`.
 
 ### config
 
@@ -35,7 +76,35 @@ Hash of robots keyed by name.
 network.config  # => RunConfig
 ```
 
-Shared operational defaults for all robots in the network. Passed to robots during `run()` so they can inherit network-wide LLM settings. See [RunConfig](../../getting-started/configuration.md#runconfig-shared-operational-defaults).
+Shared operational defaults. Passed to robots during `run()` as `network_config:`.
+
+!!! warning "Only `mcp` and `tools` propagate to member robots"
+    LLM fields (`model`, `temperature`, `max_tokens`, …) and callbacks
+    (`on_content`, `on_tool_call`, `on_tool_result`) are read from each robot's
+    own config at construction time and are **never** inherited from the
+    network. A member robot picks up the network's `mcp`/`tools` only when it
+    opts in with `:inherit`. `max_concurrent_robots` is the one field the
+    network itself consumes (it is passed to `pipeline.call_parallel`).
+
+### parallel_mode
+
+```ruby
+network.parallel_mode  # => :async (default) or :ractor
+```
+
+Execution strategy for `run`. `:async` uses the SimpleFlow pipeline;
+`:ractor` routes through `RactorNetworkScheduler` and **raises
+`RobotLab::DependencyError`** unless the `robot_lab-ractor` gem is loaded. Set via
+`Network.new(parallel_mode:)`.
+
+### hooks
+
+```ruby
+network.hooks  # => RobotLab::HookRegistry
+```
+
+The network's own hook registry, populated by [`network.on`](#on). Consulted for
+network-run, robot-run, and task hooks alongside `RobotLab.hooks`.
 
 ### pipeline
 
@@ -70,12 +139,25 @@ Execute the network pipeline.
 | `message` | `String`, `nil` | The input message — as the `message:` keyword, or positionally (folded into `message:` when given) |
 | `**context` | `Hash` | Additional context passed to all robots |
 
-**Returns:** `SimpleFlow::Result`
+`run` injects three keys into the run context before executing:
+`network_memory:` (the shared `Memory`), `network:` (the network itself), and
+`network_config:` (only when the network's `RunConfig` is non-empty). The whole
+execution is wrapped in the `:network_run` hook family.
+
+**Returns:** `SimpleFlow::Result` — except under `parallel_mode: :ractor`, where
+`RactorNetworkScheduler#run_pipeline` returns its own results structure.
+
+!!! note "Member robots still default to `tools: :none`"
+    Task-level `tools:`/`mcp:` default to `:none` just like `Robot#run`. Declare
+    the task with `tools: :inherit` (or an explicit name array) for its robot to
+    receive any tools.
 
 ### task
 
 ```ruby
-network.task(name, robot, context: {}, mcp: :none, tools: :none, memory: nil, config: nil, depends_on: :none)
+network.task(name, robot,
+             context: {}, mcp: :none, tools: :none, memory: nil,
+             config: nil, depends_on: :none, poller_group: :default)
 # => self
 ```
 
@@ -83,16 +165,17 @@ Add a task to the pipeline with optional per-task configuration.
 
 **Parameters:**
 
-| Name | Type | Description |
-|------|------|-------------|
-| `name` | `Symbol` | Task identifier |
-| `robot` | `Robot` | Robot instance to execute |
-| `context` | `Hash` | Task-specific context (deep-merged with run params) |
-| `mcp` | `:none`, Array | MCP server config (`:none` or array of servers) |
-| `tools` | `:none`, Array | Tools config (`:none` or array of tools) |
-| `memory` | `Memory`, `nil` | Task-specific memory |
-| `config` | `RunConfig`, `nil` | Per-task config (merged on top of network's RunConfig) |
-| `depends_on` | `:none`, `Array<Symbol>`, `:optional` | Task dependencies |
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `Symbol` | **required** | Task identifier; also the key under which the robot is stored in `network.robots` |
+| `robot` | `Robot` | **required** | Robot instance to execute |
+| `context` | `Hash` | `{}` | Task-specific context (deep-merged with run params) |
+| `mcp` | `Symbol`, `Array` | `:none` | MCP server config for this task |
+| `tools` | `Symbol`, `Array` | `:none` | Tools config for this task — tool **names**, not instances |
+| `memory` | `Memory`, `Hash`, `nil` | `nil` | Task-specific memory, overriding the network's shared memory |
+| `config` | `RunConfig`, `nil` | `nil` | Per-task config, merged on top of the network's RunConfig. Like the network config, only `mcp`/`tools` reach the robot |
+| `depends_on` | `:none`, `Array<Symbol>`, `:optional` | `:none` | Task dependencies |
+| `poller_group` | `Symbol` | `:default` | Bus-poller group for this robot; the network registers the group on its shared `BusPoller` and assigns it to the robot |
 
 **Dependency Types:**
 
@@ -100,7 +183,106 @@ Add a task to the pipeline with optional per-task configuration.
 |-------|-------------|
 | `:none` | No dependencies, runs first |
 | `[:task1, :task2]` | Waits for listed tasks to complete |
-| `:optional` | Only runs when explicitly activated |
+| `:optional` | Only runs when explicitly activated via `result.activate(:name)` |
+
+### parallel
+
+```ruby
+network.parallel(name = nil, depends_on: :none) { ... }
+# => self
+```
+
+Declare a named group of steps that run concurrently, then depend on the group as
+a unit. Delegates directly to `SimpleFlow::Pipeline#parallel`.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `Symbol`, `nil` | `nil` | Optional name for the group, usable in a later `depends_on:` |
+| `depends_on` | `Symbol`, `Array` | `:none` | Dependencies for the group as a whole |
+
+!!! warning "Use `step` inside the block, not `task`"
+    The block is `instance_eval`'d by `SimpleFlow::Pipeline::ParallelBlock`,
+    whose only DSL methods are `step` and `steps` — **not** `task`. This is an
+    inconsistency with the top-level `Network` DSL. Inner entries therefore also
+    bypass `Network#task`, so they are not registered in `network.robots`, get no
+    per-task `context:`/`tools:`/`memory:`, and are not assigned a poller group.
+
+    ```ruby
+    network.parallel :fetch_data, depends_on: :validate do
+      step :fetch_orders,   orders_robot
+      step :fetch_products, products_robot
+    end
+    network.task :process, processor, depends_on: :fetch_data
+    ```
+
+    Declaring the concurrent robots as ordinary `task`s that share a `depends_on:`
+    avoids all of that and is the pattern used throughout these docs.
+
+### broadcast
+
+```ruby
+network.broadcast(payload)
+# => self
+```
+
+Send a network-wide announcement. Wraps `payload` as
+`{ payload:, network:, timestamp: }`, dispatches it asynchronously to every
+handler registered with [`on_broadcast`](#on_broadcast), and also writes it to
+shared memory under `Network::BROADCAST_KEY` (`:_network_broadcast`) so robots can
+pick it up with `memory.subscribe(:_network_broadcast)`.
+
+```ruby
+network.broadcast(event: :pause, reason: "rate limit hit")
+```
+
+### on_broadcast
+
+```ruby
+network.on_broadcast { |message| ... }
+# => self
+```
+
+Register a handler for `broadcast` messages. The block receives the full envelope
+(`message[:payload]`, `message[:network]`, `message[:timestamp]`).
+
+**Raises:** `ArgumentError` if no block is given.
+
+```ruby
+network.on_broadcast do |message|
+  pause_current_work if message[:payload][:event] == :pause
+end
+```
+
+### reset_memory
+
+```ruby
+network.reset_memory
+# => self
+```
+
+Reset the network's shared memory to its initial state (`Memory#reset`). Useful
+between runs. This clears the key-value store only; it does not touch any robot's
+chat history.
+
+### on
+
+```ruby
+network.on(HandlerClass, context: nil)
+```
+
+Register a hook handler on the network's own registry (`network.hooks`). Unlike
+`robot.on`, handlers registered here **do** fire for the `:task` hook family,
+which resolves against `[RobotLab.hooks, network&.hooks]`.
+
+### to_dot
+
+```ruby
+network.to_dot  # => String, or nil
+```
+
+Graphviz DOT representation of the pipeline (`pipeline.visualize_dot`).
 
 ### add_robot
 
@@ -172,34 +354,58 @@ Hash representation of network configuration.
 ```ruby
 {
   name: "support",
-  robots: ["classifier", "billing", "technical"],
-  tasks: ["classifier", "billing", "technical"],
+  robots: ["classifier", "billing", "technical"],   # keys of network.robots
+  tasks: ["classifier", "billing", "technical"],    # task names only
   optional_tasks: [:billing, :technical],
-  config: { model: "claude-sonnet-4", temperature: 0.7 }  # if set
+  config: { model: "claude-sonnet-4", temperature: 0.7 }
 }
 ```
 
-## SimpleFlow::Result
+The hash is `.compact`ed and `config` is omitted entirely when the network's
+`RunConfig` is empty. `config` comes from `RunConfig#to_json_hash`, so the
+non-serializable fields (`on_tool_call`, `on_tool_result`, `on_content`, `bus`,
+`auto_compact`) are excluded. `robots` includes robots added with `add_robot`;
+`tasks` does not.
 
-When `run` is called, a `SimpleFlow::Result` is returned:
+## SimpleFlow::Result
 
-### Attributes
-
-```ruby
-result.value      # Final task's output (RobotResult)
-result.context    # Hash of all task results
-result.halted?    # Whether execution stopped early
-result.continued? # Whether execution continues
-```
+`Network#run` returns a `SimpleFlow::Result`. This is its **complete** public API
+(simple_flow 0.4):
+
+| Method | Description |
+|--------|-------------|
+| `value` | The final task's output (a `RobotResult`) |
+| `context` | Hash of accumulated context, including every task's result |
+| `continue?` | `true` while the pipeline is still running steps |
+| `continue(value)` | Returns a new Result carrying `value`, still continuing |
+| `halt(value)` | Returns a new Result that stops the pipeline |
+| `with_context(key, value)` | Returns a new Result with an added context entry |
+| `with_error(key, message)` | Returns a new Result with an added error — **both arguments are required** |
+| `errors` | Accumulated errors |
+| `activate(step_name)` | Marks an `:optional` step to run |
+| `activated_steps` | The set of optional steps activated so far |
+
+!!! danger "`halted?`, `continued?`, and `with_value` do not exist"
+    They raise `NoMethodError`. The predicate is `continue?` — a halted result
+    is one where `continue?` is `false`.
+
+    ```ruby
+    result = network.run(message: "Hello")
+    puts "stopped early" unless result.continue?
+    ```
 
 ### Context Structure
 
 ```ruby
 result.context[:run_params]   # Original run parameters
-result.context[:classifier]   # Classifier robot's RobotResult
-result.context[:billing]      # Billing robot's RobotResult (if activated)
+result.context[:classifier]   # RobotResult from the robot NAMED "classifier"
+result.context[:billing]      # RobotResult from the robot NAMED "billing"
 ```
 
+`Robot#call` writes its result with `result.with_context(@name.to_sym, robot_result)`,
+so context keys are **robot names**, not task names. Name each robot after its
+task to keep the two aligned.
+
 ## Builder DSL
 
 ### task
@@ -222,11 +428,17 @@ network = RobotLab.create_network(name: "support") do
        depends_on: :optional
   task :technical, technical_robot,
        context: { department: "technical" },
-       tools: [DebugTool, LogTool],
+       # Entries must match how the robot attached each tool. If technical_robot
+       # was built with local_tools: [DebugTool, LogTool] (classes), use the class
+       # names; if it attached instances, use %w[debug log] instead.
+       tools: %w[DebugTool LogTool],
        depends_on: :optional
 end
 ```
 
+`tools:` here is a **name allowlist**, exactly as on `Robot`. Attach the tool
+objects themselves with `local_tools:` when building the robot.
+
 ## Examples
 
 ### Sequential Pipeline
@@ -259,10 +471,16 @@ end
 
 ### Conditional Routing
 
+There is no `Router` class and no `Router::Args`. Conditional routing is done by
+subclassing `Robot`, overriding `#call`, and calling `result.activate(:task_name)`
+for tasks declared `depends_on: :optional`:
+
 ```ruby
 class ClassifierRobot < RobotLab::Robot
   def call(result)
-    robot_result = run(**extract_run_context(result))
+    run_context  = extract_run_context(result)
+    message      = run_context.delete(:message)   # must be positional
+    robot_result = run(message, **run_context)
 
     new_result = result
       .with_context(@name.to_sym, robot_result)
@@ -319,11 +537,15 @@ end
 | `single?` | `false` |
 
 ```ruby
-network.crew.map(&:name)  # => ["classifier", "billing", "technical"]
+network.crew.map(&:name)  # => the ROBOTS' names, not the task keys
 network.chief             # => the first robot
 network.network?          # => true
 ```
 
+`crew` returns `robots.values` — robot *instances*. So `crew.map(&:name)` yields
+`robot.name` for each, which differs from `network.robots.keys` (task names)
+unless each robot is named after its task.
+
 ## See Also
 
 - [Creating Networks Guide](../../guides/creating-networks.md)

data/docs/api/core/result.md

@@ -8,12 +8,34 @@
 result = robot.run("What is the capital of France?")
 
 result.reply              # => "The capital of France is Paris."
-result.last_text_content  # => alias for reply
-result.output             # => Array of Message objects (full turn)
-result.tool_calls         # => Array of ToolResultMessage objects
+result.last_text_content  # => reply is an alias for this
+result.output             # => [TextMessage] — see below
+result.tool_calls         # => [] in practice — see below
 ```
 
-`reply` / `last_text_content` returns the content of the last text message in `output`. This is the string you want for the vast majority of use cases.
+`last_text_content` returns the content of the last text message in `output`;
+`reply` is an alias for it. This is the string you want for the vast majority of
+use cases.
+
+!!! note "`output` is not the full turn"
+    `output` is built as `[TextMessage.new(role: "assistant", content: text)]`
+    from the **final response text only** — a one-element array, or an empty
+    array when there is no text. It never contains the user message, the tool
+    calls, or the intermediate assistant turns. Read `robot.messages` for the
+    real conversation.
+
+    The text is resolved in this order: `response.content`; then
+    `response.thinking.text` (for models that route all output through reasoning
+    content, e.g. `qwen3` on Ollama); then the most recent assistant text from
+    *the current turn only* in the chat history.
+
+!!! note "`tool_calls` is effectively always empty"
+    It is populated from the **final** assistant message, which no longer carries
+    tool calls once ruby_llm's tool loop has completed. Consequently
+    `has_tool_calls?` is also normally `false`. To observe tool activity, use the
+    `on_tool_call:` / `on_tool_result:` callbacks or the `:tool_call` hook family.
+
+There is **no** `text?` predicate and **no** `content` accessor on `RobotResult`.
 
 ## Token & Cost Tracking
 
@@ -47,77 +69,143 @@ result.duration      # => 2.34       (always set by delegate)
 result.robot_name   # => "analyst"
 result.id           # => "550e8400-e29b-..."  (UUID, unique per run)
 result.created_at   # => Time instance
-result.stop_reason  # => "end_turn", "tool_use", or nil
+result.stop_reason  # => nil — always, for results built by Robot#run
 ```
 
-## Inspecting the Full Output
+!!! warning "`stop_reason` is always `nil` here"
+    `build_result` sets it with
+    `response.respond_to?(:stop_reason) ? response.stop_reason : nil`, and
+    `RubyLLM::Message` does **not** define `stop_reason`. So every
+    `robot.run` result carries `nil`, and `export` drops the key entirely.
+    (`RobotLab::Message::VALID_STOP_REASONS` is `["tool", "stop"]`, but that
+    constant governs the message classes you construct yourself — it is not
+    what a `RobotResult` reports.)
+
+## Inspecting the Output
 
 ```ruby
 result.output.each do |message|
-  puts message.role     # :assistant, :tool, etc.
-  puts message.content  # String or Array
+  puts message.role     # "assistant"
+  puts message.content  # String
 end
 
-result.has_tool_calls?  # => true if the LLM called any tools
+result.has_tool_calls?  # => output.any?(&:tool_call?) || tool_calls.any?
 result.stopped?         # => true if execution ended naturally (not mid-tool-call)
 ```
 
+Because `stop_reason` is always `nil` on a `Robot#run` result, `stopped?`
+collapses to `!has_tool_calls?` in practice — and since `tool_calls` is
+effectively always empty, it is normally `true`.
+
 ## Persistence
 
-Export for serialization (excludes debug fields):
+Export for serialization (excludes the debug fields):
 
 ```ruby
 hash = result.export
 # {
 #   robot_name: "analyst",
+#   delegated_by: "manager",
 #   output: [...],
 #   tool_calls: [...],
 #   created_at: "2026-04-18T12:00:00Z",
 #   id: "550e8400-...",
 #   checksum: "a1b2c3...",
-#   stop_reason: "end_turn",
+#   # stop_reason is absent — it is nil, and export is .compact-ed
 #   duration: 2.34,
 #   input_tokens: 512,
 #   output_tokens: 128
 # }
 
-json = result.to_json
+json = result.to_json   # uses export
+
+hash_with_debug = result.to_h  # export + prompt/history/raw, also compacted
 
 # Reconstruct from hash
 restored = RobotLab::RobotResult.from_hash(hash)
 ```
 
-`checksum` is a SHA-256 digest of `output + tool_calls + created_at`. Use it for deduplication when persisting results.
+!!! warning "`export` is `.compact`ed"
+    Keys whose value is `nil` are dropped entirely. `delegated_by` and
+    `duration` disappear when unset, and `stop_reason` is dropped from
+    **every** `Robot#run` result because it is always `nil`. `input_tokens` and
+    `output_tokens` are additionally converted to `nil` (and therefore dropped)
+    when they are **zero**, so a provider that reports no usage yields a hash
+    with no token keys at all:
+
+    ```ruby
+    RobotLab::RobotResult.new(robot_name: "a", output: []).export
+    # => { robot_name: "a", output: [], tool_calls: [],
+    #      created_at: "...", id: "...", checksum: "..." }
+    ```
+
+    Only `robot_name`, `output`, `tool_calls`, `created_at`, `id`, and `checksum`
+    are always present. Code reading an exported hash must tolerate missing keys.
+
+`checksum` is a SHA-256 hex digest of `{ output:, tool_calls:, created_at: }`
+(with `created_at` reduced to an integer epoch). Use it for deduplication when
+persisting results.
 
 ## Debug Fields
 
-These are `nil` by default and only populated when explicitly set for debugging:
+All three are read/write and excluded from `export`/`to_json` (but included in `to_h`):
 
 ```ruby
-result.prompt   # Array<Message> — prompt sent to the LLM
-result.history  # Array<Message> — history used
-result.raw      # raw LLM response object from ruby_llm
+result.prompt   # Array<Message>, nil — nil unless you assign it
+result.history  # Array<Message>, nil — nil unless you assign it
+result.raw      # the raw ruby_llm response; Robot#run always sets this
 ```
 
+`raw` is populated by `Robot#build_result` on every run, so it is the escape
+hatch for anything RobotLab does not surface (cost, provider metadata, the
+untouched message object). `prompt` and `history` are never populated by the
+framework.
+
 ## Attribute Reference
 
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `robot_name` | String | Name of the robot that produced this result |
-| `reply` | String, nil | Last text content (alias: `last_text_content`) |
-| `output` | Array\<Message\> | All output messages from this run |
-| `tool_calls` | Array\<ToolResultMessage\> | Tool call results |
-| `input_tokens` | Integer | Tokens sent to LLM |
-| `output_tokens` | Integer | Tokens generated |
-| `duration` | Float, nil | Elapsed seconds (set by delegate/pipeline) |
-| `delegated_by` | String, nil | Delegating robot's name |
-| `id` | String | UUID |
-| `created_at` | Time | Creation timestamp |
-| `stop_reason` | String, nil | LLM stop reason |
-| `checksum` | String | SHA-256 of output content |
+| Attribute | Access | Type | Description |
+|-----------|--------|------|-------------|
+| `robot_name` | r | String | Name of the robot that produced this result |
+| `last_text_content` | r | String, nil | Content of the last text message in `output` (alias: `reply`) |
+| `output` | r | Array\<TextMessage\> | The final response text, as a one-element array (or empty) |
+| `tool_calls` | r | Array\<ToolResultMessage\> | Tool call results — effectively always empty |
+| `input_tokens` | r | Integer | Tokens sent to LLM (0 when the provider reports no usage) |
+| `output_tokens` | r | Integer | Tokens generated (0 when not reported) |
+| `id` | r | String | UUID, generated per result |
+| `created_at` | r | Time | Creation timestamp |
+| `stop_reason` | r | String, nil | Always `nil` for `Robot#run` results (the ruby_llm response has no `stop_reason`); settable only when you build a `RobotResult` yourself |
+| `duration` | rw | Float, nil | Elapsed seconds — set by `delegate` and by `Robot#call` in a pipeline; `nil` for a direct `robot.run` |
+| `delegated_by` | rw | String, nil | Delegating robot's name — set by `delegate` |
+| `prompt` | rw | Array\<Message\>, nil | Debug field, `nil` unless assigned |
+| `history` | rw | Array\<Message\>, nil | Debug field, `nil` unless assigned |
+| `raw` | rw | Object, nil | The raw ruby_llm response; set by `Robot#build_result` |
+
+Methods: `checksum`, `export`, `to_h`, `to_json`, `has_tool_calls?`, `stopped?`,
+and the class method `RobotResult.from_hash`.
+
+## Constructor
+
+```ruby
+RobotLab::RobotResult.new(
+  robot_name:,            # required
+  output:,                # required — Array<Message, Hash>
+  tool_calls: [],
+  created_at: nil,        # defaults to Time.now
+  id: nil,                # defaults to SecureRandom.uuid
+  prompt: nil,
+  history: nil,
+  raw: nil,
+  stop_reason: nil,
+  input_tokens: 0,
+  output_tokens: 0
+)
+```
+
+`output` entries must be `Message` instances or Hashes (`Message.from_hash`);
+anything else raises `ArgumentError`.
 
 ## Related
 
-- [Robot API](robot.md) — `run`, `delegate`, `compress_history`
+- [Robot API](robot.md) — [`run`](robot.md#run), [`delegate`](robot.md#delegate), [`compress_history`](robot.md#compress_history)
 - [Building Robots](../../guides/building-robots.md) — Robot construction patterns
 - [Structured Delegation](../../guides/building-robots.md#structured-delegation) — `DelegationFuture` and async fan-out