robot_lab 0.0.7 → 0.0.9

data/docs/concepts.md

@@ -12,7 +12,10 @@ Each robot has:
 - **Template**: A `.md` file with YAML front matter managed by prompt_manager, referenced by symbol
 - **System Prompt**: Inline instructions (can be used alone or combined with a template)
 - **Model**: The LLM model to use (defaults to `RobotLab.config.ruby_llm.model`)
-- **Local Tools**: `RubyLLM::Tool` subclasses or `RobotLab::Tool` instances
+- **Provider**: Optional LLM provider for local models (Ollama, GPUStack, etc.)
+- **Skills**: Composable template behaviors prepended before the main template
+- **Local Tools**: `RubyLLM::Tool` subclasses or `RobotLab::Tool` instances (with automatic error handling)
+- **Streaming**: Real-time content via stored `on_content` callback or per-call block
 - **Memory**: Persistent key-value store across runs
 
 ```ruby
@@ -137,7 +140,9 @@ result.continued? # Whether execution continues
 
 ## Tool
 
-**Tools** give robots the ability to interact with external systems. There are two patterns for defining tools:
+**Tools** give robots the ability to interact with external systems. `RobotLab::Tool` extends `RubyLLM::Tool` with graceful error handling — if `execute` raises a `StandardError`, the error is caught and returned as a plain-text string (`"Error (tool_name): message"`) so the LLM can reason about it. Critical tools can opt out with `self.raise_on_error = true`.
+
+There are two patterns for defining tools:
 
 ### RubyLLM::Tool Subclass (Preferred)
 
@@ -191,12 +196,15 @@ tool = RobotLab::Tool.create(
 result = robot.run("Hello!")
 
 result.last_text_content  # => "Hi there!" (String or nil)
+result.reply              # => alias for last_text_content
 result.output             # => [TextMessage, ...] array of output messages
 result.tool_calls         # => [] array of tool call results
 result.robot_name         # => "assistant"
 result.stop_reason        # => "end_turn" or nil
 result.has_tool_calls?    # => false
 result.checksum           # => "a1b2c3d4..." (for dedup)
+result.duration           # => Float or nil (elapsed seconds, set in pipeline execution)
+result.raw                # => raw LLM response object
 ```
 
 ## Memory
@@ -446,7 +454,7 @@ Templates support two categories of front matter keys:
 
 **LLM Config:** `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` — applied to the robot's chat configuration.
 
-**Robot Extras:** `robot_name`, `description`, `tools`, `mcp` — applied to the robot's identity and capabilities. These make templates self-contained: reading the `.md` file tells you everything about the robot.
+**Robot Extras:** `robot_name`, `description`, `tools`, `mcp`, `skills` — applied to the robot's identity and capabilities. These make templates self-contained: reading the `.md` file tells you everything about the robot.
 
 ```markdown
 ---

data/docs/examples/index.md

@@ -29,7 +29,7 @@ These examples show how to use RobotLab for common scenarios, from simple chatbo
 ### Advanced Examples
 
 - [Streaming Responses](basic-chat.md#with-streaming)
-- [Persistent Conversations](basic-chat.md#with-conversation-history)
+- [Persistent Conversations](basic-chat.md#with-memory)
 - [MCP Integration](mcp-server.md)
 - [Message Bus Communication](#message-bus)
 - [Spawning Robots](#spawning-robots)

data/docs/examples/rails-application.md

@@ -88,7 +88,7 @@ RobotLab.config.logger  #=> Rails.logger
 
 ### Rails Engine and Railtie
 
-RobotLab provides both a Rails Engine (`RobotLab::Rails::Engine`) and a Railtie (`RobotLab::Rails::Railtie`). These are loaded automatically when Rails is detected. The Engine isolates the RobotLab namespace and adds `app/robots` and `app/tools` to the autoload paths. The Railtie loads rake tasks and generators.
+RobotLab provides both a Rails Engine (`RobotLab::RailsIntegration::Engine`) and a Railtie (`RobotLab::RailsIntegration::Railtie`). These are loaded automatically when Rails is detected. The Engine isolates the RobotLab namespace and adds `app/robots` and `app/tools` to the autoload paths. The Railtie loads rake tasks and generators.
 
 ## Models
 

data/docs/guides/building-robots.md

@@ -50,6 +50,21 @@ robot = RobotLab.build(
 )
 ```
 
+### Provider
+
+For local LLM providers (Ollama, GPUStack, LM Studio, etc.), use the `provider:` parameter. This tells RubyLLM to skip model validation and connect directly:
+
+```ruby
+robot = RobotLab.build(
+  name: "local_bot",
+  model: "llama3.2",
+  provider: :ollama,
+  system_prompt: "You are a helpful assistant."
+)
+```
+
+When `provider:` is set, `assume_model_exists: true` is automatically applied. The provider is available via `robot.provider`.
+
 ### System Prompt
 
 An inline string that defines the robot's personality and behavior:
@@ -125,6 +140,7 @@ The following YAML front matter keys are applied to the robot's chat automatical
 | `description` | Human-readable description of the robot |
 | `tools` | Array of tool class names (resolved via `Object.const_get`) |
 | `mcp` | Array of MCP server configurations |
+| `skills` | Array of skill template symbols to prepend (see [Composable Skills](#composable-skills)) |
 
 Constructor-provided values always take precedence over frontmatter values.
 
@@ -221,6 +237,173 @@ robot = RobotLab.build(
 )
 ```
 
+## Composable Skills
+
+Skills let you compose robot behaviors from reusable templates without creating a dedicated template for every combination. A skill is just a regular template whose prompt body gets prepended before the main template's body.
+
+### Why Skills?
+
+Consider a support agent that needs to:
+
+- Ask clarifying questions before acting
+- Detect customer sentiment
+- Respond in structured JSON
+
+Without skills, you'd create a single monolithic template or copy-paste shared instructions across templates. With skills, each behavior is a standalone template that can be mixed into any robot.
+
+### Defining a Skill
+
+A skill is a standard `.md` template file. There is no special syntax — any template can be used as a skill:
+
+```markdown title="prompts/clarifier.md"
+---
+description: Ask clarifying questions before acting
+---
+Before answering, consider whether the user's request is ambiguous.
+If so, ask one focused clarifying question before proceeding.
+```
+
+```markdown title="prompts/json_responder.md"
+---
+description: Respond in structured JSON
+temperature: 0.2
+---
+Always respond with valid JSON. Use this structure:
+{"answer": "...", "confidence": 0.0-1.0, "sources": [...]}
+```
+
+### Using Skills via Constructor
+
+Pass `skills:` as a symbol or array of symbols:
+
+```ruby
+# Single skill
+robot = RobotLab.build(
+  name: "bot",
+  template: :support,
+  skills: :clarifier
+)
+
+# Multiple skills
+robot = RobotLab.build(
+  name: "bot",
+  template: :support,
+  skills: [:clarifier, :json_responder],
+  context: { company: "Acme Corp" }
+)
+```
+
+The resulting system prompt is composed in order: clarifier body, then json_responder body, then the main support template body.
+
+### Using Skills via Front Matter
+
+Templates can declare skills directly in their front matter:
+
+```markdown title="prompts/smart_support.md"
+---
+description: Support agent with built-in skills
+skills:
+  - clarifier
+  - json_responder
+parameters:
+  company: null
+---
+You are a support agent for <%= company %>.
+Help customers with their inquiries.
+```
+
+```ruby
+# Skills are loaded from front matter automatically
+robot = RobotLab.build(
+  template: :smart_support,
+  context: { company: "Acme Corp" }
+)
+```
+
+Constructor `skills:` and front matter `skills:` are combined — constructor skills are processed first, then front matter skills.
+
+### Nested Skills
+
+Skills can reference other skills, enabling layered composition:
+
+```markdown title="prompts/safety.md"
+---
+description: Safety guidelines
+skills:
+  - content_filter
+  - pii_redactor
+---
+Follow all safety guidelines when responding.
+```
+
+Nested skills are expanded depth-first. For the example above, the prompt order would be: content_filter, pii_redactor, safety, then the main template.
+
+### Cycle Detection
+
+If skills form a cycle (A references B, B references A), RobotLab detects it automatically, logs a warning, and skips the duplicate. This prevents infinite loops.
+
+### Config Cascade
+
+Skills can include LLM configuration in their front matter. Config cascades in processing order — later values override earlier ones:
+
+```markdown title="prompts/creative_mode.md"
+---
+description: Enable creative responses
+temperature: 0.9
+top_p: 0.95
+---
+Be creative and imaginative in your responses.
+```
+
+```ruby
+robot = RobotLab.build(
+  name: "writer",
+  template: :article_writer,
+  skills: [:creative_mode]
+)
+# temperature is 0.9 from the skill (unless the main template or constructor overrides it)
+```
+
+The precedence order (highest wins):
+
+1. Constructor kwargs (`temperature: 0.3`)
+2. Main template front matter
+3. Later skills override earlier skills
+4. First skill in the list
+
+### Skills Without a Main Template
+
+Skills work without a main template — useful for quick composition:
+
+```ruby
+robot = RobotLab.build(
+  name: "safe_bot",
+  skills: [:safety, :json_responder],
+  system_prompt: "You answer questions about our product."
+)
+```
+
+### Shared Context
+
+All skills and the main template render with the same `context:` hash. Define parameters in each skill's front matter and pass values through the shared context:
+
+```markdown title="prompts/branded.md"
+---
+description: Brand-aware responses
+parameters:
+  company_name: null
+---
+You represent <%= company_name %>. Always maintain brand voice.
+```
+
+```ruby
+robot = RobotLab.build(
+  template: :support,
+  skills: [:branded],
+  context: { company_name: "Acme Corp" }  # shared with all skills
+)
+```
+
 ## Adding Tools
 
 Give robots capabilities via the `local_tools:` parameter. Tools can be `RubyLLM::Tool` subclasses or `RobotLab::Tool` instances:
@@ -311,10 +494,13 @@ The `run` method returns a `RobotResult` with:
 
 ```ruby
 result.last_text_content  # => "Hi there! How can I help?"
+result.reply              # => alias for last_text_content
 result.output             # => Array of output messages
 result.tool_calls         # => Array of tool call results
 result.robot_name         # => "assistant"
 result.stop_reason        # => stop reason from the LLM
+result.duration           # => Float (elapsed seconds, set in pipeline execution)
+result.raw                # => raw LLM response object
 ```
 
 ### With Runtime Memory
@@ -340,18 +526,54 @@ puts result.value.last_text_content
 
 ### With Streaming
 
-Stream responses in real-time by registering callbacks before calling `run`:
+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) object — use `chunk.content` for the text delta. Chunks also carry `model_id`, `tool_calls`, `thinking`, and token usage on the final chunk. See the [Streaming API reference](../api/core/robot.md#streaming) for the full chunk interface.
+
+**Stored callback** — wired at build time, fires on every `run()`:
 
 ```ruby
-robot.on_new_message do |message|
-  print message.content if message.content
-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
+```
 
-robot.on_tool_call do |tool_call|
-  puts "\nCalling tool: #{tool_call.name}"
-end
+**Per-call block** — passed to `run()`:
+
+```ruby
+robot.run("Tell me a story") { |chunk| print chunk.content }
+```
+
+**Both together** — stored fires first, then the block:
+
+```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 config level and inherited by robots:
+
+```ruby
+config = RobotLab::RunConfig.new(
+  on_content: ->(chunk) { broadcast(chunk.content) }
+)
+robot = RobotLab.build(name: "bot", system_prompt: "...", config: config)
+```
 
-result = robot.run("Tell me a story")
+You can also monitor tool activity via callbacks:
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "...",
+  on_tool_call: ->(tool_call) { puts "Calling: #{tool_call.name}" },
+  on_tool_result: ->(result) { puts "Result: #{result}" }
+)
 ```
 
 ## Robot Patterns
@@ -556,7 +778,19 @@ robot = RobotLab.build(
 )
 ```
 
-### 2. Use Templates for Reusable Prompts
+### 2. Compose Behaviors with Skills
+
+Instead of creating monolithic templates, break behaviors into composable skills:
+
+```ruby
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  skills: [:clarifier, :safety, :json_responder]
+)
+```
+
+### 3. Use Templates for Reusable Prompts
 
 Templates keep prompts in version-controlled files and allow parameterization:
 
@@ -568,9 +802,9 @@ robot = RobotLab.build(
 )
 ```
 
-### 3. Handle Tool Errors Gracefully
+### 4. Handle Tool Errors Gracefully
 
-See [Using Tools: Error Handling](using-tools.md#error-handling) for patterns.
+`RobotLab::Tool` automatically catches exceptions and returns plain-text errors to the LLM. For domain-specific error handling, catch known exceptions in `execute` and return structured data. See [Using Tools: Error Handling](using-tools.md#error-handling) for details.
 
 ## Next Steps
 

data/docs/guides/creating-networks.md

@@ -291,6 +291,24 @@ network = RobotLab.create_network(name: "multi_analysis") do
 end
 ```
 
+### Pipeline Error Resilience
+
+When a robot raises an exception during pipeline execution, the error is caught and wrapped in a `RobotResult` with the error message as content. This ensures one failing robot does not crash the entire network:
+
+```ruby
+# If billing_robot raises an error, the network continues
+# The error is available in the result context:
+result = network.run(message: "Process this")
+billing_result = result.context[:billing]
+
+if billing_result&.last_text_content&.start_with?("Error:")
+  puts "Billing failed: #{billing_result.last_text_content}"
+  puts "Took: #{billing_result.duration}s"
+end
+```
+
+Each robot's `RobotResult` includes a `duration` field (elapsed seconds) that is set automatically during pipeline execution, even for errored results.
+
 ### Conditional Continuation
 
 A robot can halt execution early:

data/docs/guides/mcp-integration.md

@@ -101,6 +101,26 @@ Global (RobotLab.config.mcp)
       -> Runtime (robot.run("msg", mcp: [...]))
 ```
 
+## Timeout Configuration
+
+All transports support a configurable request timeout. The default is 15 seconds. Set a custom timeout at the server level:
+
+```ruby
+robot = RobotLab.build(
+  name: "patient_bot",
+  system_prompt: "You help with slow operations.",
+  mcp: [
+    {
+      name: "heavy_server",
+      transport: { type: "stdio", command: "heavy-mcp-server" },
+      timeout: 60  # seconds
+    }
+  ]
+)
+```
+
+Values >= 1000 are auto-converted from milliseconds to seconds. The minimum timeout is 1 second.
+
 ## Transport Types
 
 ### Stdio Transport
@@ -290,6 +310,50 @@ client.list_resources       # => Array of resource definitions
 client.disconnect
 ```
 
+## Connection Resilience
+
+### Eager Connection
+
+By default, MCP connections are lazy — established on the first `run()` call. Use `connect_mcp!` to connect early:
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You help with tasks.",
+  mcp: [
+    { name: "github", transport: { type: "stdio", command: "mcp-server-github" } },
+    { name: "filesystem", transport: { type: "stdio", command: "mcp-server-fs" } }
+  ]
+)
+
+robot.connect_mcp!
+
+# Check which servers failed
+if robot.failed_mcp_server_names.any?
+  puts "Failed to connect: #{robot.failed_mcp_server_names.join(', ')}"
+end
+```
+
+### Automatic Retry
+
+Failed MCP servers are automatically retried on subsequent `run()` calls. If a server was down when the robot first connected, it will be retried transparently:
+
+```ruby
+robot.run("First message")       # github connects, filesystem fails
+# ... filesystem comes back up ...
+robot.run("Second message")      # filesystem retried and connects
+```
+
+### Injecting External MCP Clients
+
+Host applications that manage MCP connections externally can inject pre-connected clients into a robot:
+
+```ruby
+robot.inject_mcp!(clients: my_clients, tools: my_tools)
+```
+
+This skips the normal connection process and marks the robot as MCP-initialized.
+
 ## Error Handling
 
 ### Connection Errors
@@ -302,8 +366,16 @@ rescue RobotLab::MCPError => e
 end
 ```
 
-!!! tip
-    MCP connection failures are logged as warnings but do not raise errors by default. The robot will continue without MCP tools if a server is unreachable.
+MCP connection failures are logged as warnings but do not raise errors by default. The robot will continue without MCP tools if a server is unreachable. One failing server does not prevent other servers from connecting.
+
+### Timeout Errors
+
+Stdio transports wrap all blocking I/O with a configurable timeout. If a server does not respond within the timeout period, an `MCPError` is raised with a descriptive message:
+
+```ruby
+# Server that takes too long will raise:
+# RobotLab::MCPError: MCP server 'heavy-server' did not respond within 15s
+```
 
 ## Disconnecting