robot_lab 0.0.1 → 0.0.4

data/docs/getting-started/configuration.md

@@ -1,226 +1,339 @@
 # Configuration
 
-RobotLab provides flexible configuration options at global, network, and robot levels.
+RobotLab uses a layered configuration system powered by [MywayConfig](https://github.com/MadBomber/myway_config). Configuration is loaded automatically from multiple sources with no block-style `configure` method required.
 
-## Global Configuration
+## How Configuration Works
 
-Configure RobotLab globally using the `configure` block:
+Configuration values are loaded in priority order (lowest to highest):
 
-```ruby
-RobotLab.configure do |config|
-  # LLM Provider API Keys
-  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
-  config.openai_api_key = ENV["OPENAI_API_KEY"]
-  config.gemini_api_key = ENV["GEMINI_API_KEY"]
+1. **Bundled defaults** -- `lib/robot_lab/config/defaults.yml` (shipped with the gem)
+2. **Environment-specific overrides** -- `development`, `test`, or `production` sections in defaults.yml
+3. **User config file** -- `~/.config/robot_lab/config.yml`
+4. **Project config file** -- `./config/robot_lab.yml`
+5. **Environment variables** -- `ROBOT_LAB_*` prefix
+6. **Runtime attributes** -- e.g., `RobotLab.config.logger = ...`
+
+Higher-priority sources override lower-priority ones. You only need to set the values you want to change.
+
+## Accessing Configuration
+
+Use `RobotLab.config` to access the configuration object:
 
-  # Default settings
-  config.default_provider = :anthropic
-  config.default_model = "claude-sonnet-4"
+```ruby
+# Access nested values with dot notation
+RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+RobotLab.config.ruby_llm.anthropic_api_key #=> "sk-ant-..."
+RobotLab.config.ruby_llm.request_timeout  #=> 120
+RobotLab.config.max_iterations             #=> 10
+RobotLab.config.streaming_enabled          #=> true
+
+# Check the environment
+RobotLab.config.development?  #=> true/false
+```
 
-  # Execution limits
-  config.max_iterations = 10        # Max robots per network run
-  config.max_tool_iterations = 10   # Max tool calls per robot run
+!!! warning "No configure block"
+    RobotLab does **not** use a `RobotLab.configure do |config| ... end` pattern. All configuration comes from config files, environment variables, or direct assignment on `RobotLab.config`.
 
-  # Streaming
-  config.streaming_enabled = true
+## Environment Variables
 
-  # Logging
-  config.logger = Logger.new($stdout)
+Environment variables use the `ROBOT_LAB_` prefix. Use double underscores (`__`) for nested values:
 
-  # Template path for prompt files
-  config.template_path = "prompts"
-end
+```bash
+# Top-level settings
+export ROBOT_LAB_MAX_ITERATIONS=20
+export ROBOT_LAB_STREAMING_ENABLED=false
+
+# Nested ruby_llm settings (note the double underscore)
+export ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
+export ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+export ROBOT_LAB_RUBY_LLM__OPENAI_API_KEY=sk-...
+export ROBOT_LAB_RUBY_LLM__GEMINI_API_KEY=...
+export ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT=180
+export ROBOT_LAB_RUBY_LLM__MAX_RETRIES=5
 ```
 
-## Configuration Options
+The double underscore convention maps to nested YAML structure:
 
-### API Keys
+```
+ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY  -->  ruby_llm.anthropic_api_key
+ROBOT_LAB_RUBY_LLM__MODEL              -->  ruby_llm.model
+ROBOT_LAB_MAX_ITERATIONS               -->  max_iterations
+```
 
-| Option | Description |
-|--------|-------------|
-| `anthropic_api_key` | Anthropic Claude API key |
-| `openai_api_key` | OpenAI API key |
-| `gemini_api_key` | Google Gemini API key |
-| `bedrock_api_key` | AWS Bedrock API key |
-| `openrouter_api_key` | OpenRouter API key |
+## Config Files
 
-### Defaults
+### Project Config
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `default_provider` | `:anthropic` | Default LLM provider |
-| `default_model` | `"claude-sonnet-4"` | Default model |
-| `max_iterations` | `10` | Max robots per network run |
-| `max_tool_iterations` | `10` | Max tool calls per robot |
-| `streaming_enabled` | `true` | Enable streaming by default |
+Create `./config/robot_lab.yml` in your project root:
 
-### Templates
+```yaml title="config/robot_lab.yml"
+defaults:
+  ruby_llm:
+    anthropic_api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
+    model: claude-sonnet-4
+    request_timeout: 120
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `template_path` | `"prompts"` (or `"app/prompts"` in Rails) | Directory for prompt templates |
+  max_iterations: 15
+  template_path: prompts
 
-### Global MCP & Tools
+development:
+  ruby_llm:
+    log_level: :debug
 
-```ruby
-RobotLab.configure do |config|
-  # Global MCP servers available to all networks
-  config.mcp = [
-    { name: "github", transport: { type: "stdio", command: "github-mcp" } }
-  ]
-
-  # Global tool whitelist
-  config.tools = %w[search_code create_issue]
-end
+test:
+  max_iterations: 3
+  streaming_enabled: false
+  ruby_llm:
+    model: claude-haiku-3-5
+    request_timeout: 30
+    max_retries: 1
+
+production:
+  max_iterations: 20
+  ruby_llm:
+    request_timeout: 180
+    max_retries: 5
+    log_level: :warn
 ```
 
-## Network-Level Configuration
+!!! tip "ERB support"
+    Config files support ERB templating, so you can reference environment variables with `<%= ENV['...'] %>`. This is useful for keeping secrets out of config files while still using YAML structure.
 
-Override global settings at the network level:
+### User Config
 
-```ruby
-network = RobotLab.create_network do
-  name "my_network"
+Create `~/.config/robot_lab/config.yml` for personal defaults that apply across all your projects:
 
-  # Override default model for this network
-  default_model "claude-sonnet-4"
+```yaml title="~/.config/robot_lab/config.yml"
+defaults:
+  ruby_llm:
+    anthropic_api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
+    model: claude-sonnet-4
+```
 
-  # Network-specific MCP servers
-  mcp [
-    { name: "filesystem", transport: { type: "stdio", command: "mcp-fs" } }
-  ]
+## Configuration Reference
 
-  # Network-specific tool whitelist
-  tools %w[read_file write_file]
+### Core Settings
 
-  # Or inherit from global
-  mcp :inherit
-  tools :inherit
-end
+| Key | Default | Description |
+|-----|---------|-------------|
+| `max_iterations` | `10` | Maximum robots per network run |
+| `max_tool_iterations` | `10` | Maximum tool calls per robot run |
+| `streaming_enabled` | `true` | Enable streaming by default |
+| `template_path` | `null` (auto-detected) | Directory for prompt templates |
+| `mcp` | `:none` | Global MCP server configuration |
+| `tools` | `:none` | Global tool whitelist |
+
+### RubyLLM Settings (`ruby_llm:` section)
+
+All settings under the `ruby_llm:` key are applied to `RubyLLM.configure` automatically on startup.
+
+#### Provider API Keys
+
+| Key | Description |
+|-----|-------------|
+| `ruby_llm.anthropic_api_key` | Anthropic Claude API key |
+| `ruby_llm.openai_api_key` | OpenAI API key |
+| `ruby_llm.gemini_api_key` | Google Gemini API key |
+| `ruby_llm.deepseek_api_key` | DeepSeek API key |
+| `ruby_llm.mistral_api_key` | Mistral API key |
+| `ruby_llm.openrouter_api_key` | OpenRouter API key |
+| `ruby_llm.bedrock_api_key` | AWS Bedrock access key |
+| `ruby_llm.bedrock_secret_key` | AWS Bedrock secret key |
+| `ruby_llm.bedrock_region` | AWS Bedrock region |
+| `ruby_llm.xai_api_key` | xAI (Grok) API key |
+
+#### Model Defaults
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `ruby_llm.provider` | `:anthropic` | Default LLM provider |
+| `ruby_llm.model` | `claude-sonnet-4` | Default model for robots |
+| `ruby_llm.default_model` | `null` | RubyLLM default model override |
+| `ruby_llm.default_embedding_model` | `null` | Default embedding model |
+| `ruby_llm.default_image_model` | `null` | Default image model |
+
+#### Connection Settings
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `ruby_llm.request_timeout` | `120` | Request timeout in seconds |
+| `ruby_llm.max_retries` | `3` | Maximum retry attempts |
+| `ruby_llm.retry_interval` | `1` | Seconds between retries |
+| `ruby_llm.retry_backoff_factor` | `2` | Exponential backoff factor |
+| `ruby_llm.http_proxy` | `null` | HTTP proxy URL |
+
+#### Provider Endpoints (self-hosted models)
+
+| Key | Description |
+|-----|-------------|
+| `ruby_llm.openai_api_base` | Custom OpenAI-compatible endpoint |
+| `ruby_llm.gemini_api_base` | Custom Gemini endpoint |
+| `ruby_llm.ollama_api_base` | Ollama endpoint (e.g., `http://localhost:11434`) |
+| `ruby_llm.gpustack_api_base` | GPUStack endpoint |
+
+#### Logging
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `ruby_llm.log_file` | `null` | Path to log file |
+| `ruby_llm.log_level` | `:info` | Log level (`:debug`, `:info`, `:warn`, `:error`) |
+| `ruby_llm.log_stream_debug` | `false` | Log streaming debug output |
+
+### Chat Configuration (`chat:` section)
+
+Default chat parameters applied to all robots unless overridden:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `chat.with_temperature` | `0.7` | Controls randomness (0.0-2.0) |
+| `chat.with_params.top_p` | `null` | Nucleus sampling threshold |
+| `chat.with_params.top_k` | `null` | Top-k sampling |
+| `chat.with_params.max_tokens` | `null` | Maximum tokens in response |
+| `chat.with_params.presence_penalty` | `null` | Presence penalty (-2.0 to 2.0) |
+| `chat.with_params.frequency_penalty` | `null` | Frequency penalty (-2.0 to 2.0) |
+| `chat.with_params.stop` | `null` | Stop sequences |
+
+## Runtime-Only Attributes
+
+Some attributes can only be set at runtime, not through config files:
+
+```ruby
+# Logger (defaults to Rails.logger in Rails, or Logger.new($stdout) otherwise)
+RobotLab.config.logger = Logger.new(nil)        # silence logging
+RobotLab.config.logger = Logger.new("robot.log") # log to file
 ```
 
-## Robot-Level Configuration
+## Reloading Configuration
 
-Configure individual robots:
+To reload configuration from all sources:
 
 ```ruby
-robot = RobotLab.build do
-  name "specialist"
-
-  # Robot-specific model
-  model "claude-sonnet-4"
-
-  # Robot-specific MCP (overrides network)
-  mcp :inherit  # Use network's MCP servers
-  # or
-  mcp :none     # No MCP servers for this robot
-  # or
-  mcp [...]     # Specific servers
-
-  # Robot-specific tools
-  tools :inherit  # Use network's tools
-end
+RobotLab.reload_config!
 ```
 
-## Configuration Hierarchy
+This clears the cached config and reloads from all sources on next access.
 
-Configuration cascades from global to network to robot:
+## Environment-Specific Configuration
 
-```
-Global (RobotLab.configure)
-  └── Network (create_network)
-        └── Robot (build)
-              └── Runtime (robot.run)
-```
+The `defaults.yml` shipped with RobotLab includes environment-specific overrides:
 
-Each level can:
+=== "Development"
 
-- `:inherit` - Use parent level's configuration
-- `:none` or `nil` or `[]` - No items allowed
-- `[items]` - Specific items only
+    ```yaml
+    development:
+      ruby_llm:
+        log_level: :debug
+    ```
 
-## Rails Configuration
+=== "Test"
 
-In Rails, configure in an initializer:
+    ```yaml
+    test:
+      max_iterations: 3
+      streaming_enabled: false
+      ruby_llm:
+        model: claude-haiku-3-5
+        request_timeout: 30
+        max_retries: 1
+        log_level: :warn
+    ```
 
-```ruby title="config/initializers/robot_lab.rb"
-RobotLab.configure do |config|
-  # Use Rails credentials
-  config.anthropic_api_key = Rails.application.credentials.anthropic_api_key
+=== "Production"
 
-  # Use Rails logger
-  config.logger = Rails.logger
+    ```yaml
+    production:
+      streaming_enabled: false
+      max_iterations: 20
+      ruby_llm:
+        request_timeout: 180
+        max_retries: 5
+        log_level: :warn
+    ```
 
-  # Template path is automatically set to app/prompts
-end
-```
+The current environment is determined automatically (via `RAILS_ENV`, `RACK_ENV`, or defaults to `development`).
+
+## Rails Integration
 
-Or use `config/application.rb`:
+In Rails, RobotLab is configured automatically via its Railtie. The logger defaults to `Rails.logger`, and templates default to `app/prompts/`.
 
-```ruby title="config/application.rb"
-module MyApp
-  class Application < Rails::Application
-    config.robot_lab.default_model = "claude-sonnet-4"
-    config.robot_lab.default_provider = :anthropic
-  end
-end
+Create a project config file for Rails-specific settings:
+
+```yaml title="config/robot_lab.yml"
+defaults:
+  ruby_llm:
+    anthropic_api_key: <%= Rails.application.credentials.anthropic_api_key %>
+    model: claude-sonnet-4
+
+  template_path: null  # auto-detects app/prompts in Rails
+
+production:
+  ruby_llm:
+    request_timeout: 180
+    max_retries: 5
 ```
 
-## Environment-Specific Configuration
+You can also use Rails credentials:
 
-```ruby title="config/initializers/robot_lab.rb"
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
-
-  case Rails.env
-  when "development"
-    config.logger = Logger.new($stdout, level: :debug)
-    config.default_model = "claude-haiku-3"  # Faster/cheaper for dev
-  when "test"
-    config.streaming_enabled = false
-  when "production"
-    config.logger = Rails.logger
-    config.default_model = "claude-sonnet-4"
-  end
-end
+```bash
+rails credentials:edit
 ```
 
-## Using Environment Variables
+```yaml
+# config/credentials.yml.enc
+anthropic_api_key: sk-ant-...
+openai_api_key: sk-...
+```
 
-Recommended environment variables:
+Then reference them in your config file with ERB:
 
-```bash
-# Required - at least one provider
-ANTHROPIC_API_KEY=sk-ant-...
-OPENAI_API_KEY=sk-...
-GEMINI_API_KEY=...
-
-# Optional - override defaults
-ROBOT_LAB_DEFAULT_MODEL=claude-sonnet-4
-ROBOT_LAB_DEFAULT_PROVIDER=anthropic
-ROBOT_LAB_MAX_ITERATIONS=20
+```yaml title="config/robot_lab.yml"
+defaults:
+  ruby_llm:
+    anthropic_api_key: <%= Rails.application.credentials.anthropic_api_key %>
 ```
 
-Load them in configuration:
+## Robot-Level Configuration
+
+Individual robots can override the global model and other settings:
 
 ```ruby
-RobotLab.configure do |config|
-  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
-  config.default_model = ENV.fetch("ROBOT_LAB_DEFAULT_MODEL", "claude-sonnet-4")
-  config.max_iterations = ENV.fetch("ROBOT_LAB_MAX_ITERATIONS", 10).to_i
-end
+# Override model for a specific robot
+robot = RobotLab.build(
+  name: "fast_bot",
+  system_prompt: "You are a quick responder.",
+  model: "claude-haiku-3-5",
+  temperature: 0.3,
+  max_tokens: 500
+)
+
+# Or use chaining at runtime
+robot.with_temperature(0.9).with_max_tokens(2000).run("Tell me a story.")
 ```
 
-## Accessing Configuration
+## Hierarchical MCP and Tools
 
-```ruby
-# Get current configuration
-config = RobotLab.configuration
+MCP servers and tools use a hierarchical configuration: `runtime > robot > network > global`. Each level can specify:
 
-# Check settings
-config.default_model      # => "claude-sonnet-4"
-config.default_provider   # => :anthropic
-config.streaming_enabled  # => true
+- `:inherit` -- Use the parent level's configuration
+- `:none` -- No MCP servers or tools at this level
+- An explicit array -- Specific servers or tools
+
+```ruby
+# Robot inheriting network MCP config
+robot = RobotLab.build(
+  name: "agent",
+  system_prompt: "You are helpful.",
+  mcp: :inherit,
+  tools: :inherit
+)
+
+# Robot with no MCP, specific tools
+robot = RobotLab.build(
+  name: "calculator",
+  system_prompt: "You solve math problems.",
+  mcp: :none,
+  local_tools: [Calculator]
+)
 ```
 
 ## Next Steps

data/docs/getting-started/index.md

@@ -15,7 +15,7 @@ In this section, you'll learn how to:
 
 Before you begin, make sure you have:
 
-- **Ruby 3.1+** installed
+- **Ruby 3.2+** installed
 - An **API key** from at least one LLM provider:
     - [Anthropic](https://console.anthropic.com/) (recommended)
     - [OpenAI](https://platform.openai.com/)

data/docs/getting-started/installation.md

@@ -4,7 +4,7 @@ This guide covers installing RobotLab in your Ruby project.
 
 ## Requirements
 
-- **Ruby**: 3.1 or higher
+- **Ruby**: 3.2 or higher
 - **Bundler**: 2.0 or higher (recommended)
 
 ## Install via Bundler
@@ -31,13 +31,19 @@ gem install robot_lab
 
 ## Dependencies
 
-RobotLab automatically installs these dependencies:
+RobotLab automatically installs these core dependencies:
 
 | Gem | Purpose |
 |-----|---------|
-| `ruby_llm` | LLM provider integrations |
-| `ruby_llm-template` | Template rendering for prompts |
-| `simple_flow` | Workflow execution |
+| `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 |
+| `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 |
+| `zeitwerk` (~> 2.6) | Autoloading and eager loading |
+| `async` (~> 2.0) | Fiber-based concurrency |
 
 ### Optional Dependencies
 
@@ -78,7 +84,7 @@ Run it:
 
 ```bash
 ruby test_robot_lab.rb
-# => RobotLab version: 0.0.1
+# => RobotLab version: 0.1.0
 # => Installation successful!
 ```
 
@@ -107,24 +113,24 @@ rails db:migrate
 
 ## Environment Setup
 
-Before using RobotLab, set up your API keys as environment variables:
+RobotLab uses a layered configuration system (see [Configuration](configuration.md) for full details). The simplest way to get started is with environment variables:
 
 === "Anthropic (Recommended)"
 
     ```bash
-    export ANTHROPIC_API_KEY="sk-ant-..."
+    export ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY="sk-ant-..."
     ```
 
 === "OpenAI"
 
     ```bash
-    export OPENAI_API_KEY="sk-..."
+    export ROBOT_LAB_RUBY_LLM__OPENAI_API_KEY="sk-..."
     ```
 
 === "Google Gemini"
 
     ```bash
-    export GEMINI_API_KEY="..."
+    export ROBOT_LAB_RUBY_LLM__GEMINI_API_KEY="..."
     ```
 
 !!! tip "Using dotenv"
@@ -132,14 +138,17 @@ Before using RobotLab, set up your API keys as environment variables:
 
     ```ruby
     # Gemfile
-    gem "dotenv-rails", groups: [:development, :test]
+    gem "dotenv", groups: [:development, :test]
     ```
 
     ```bash
     # .env
-    ANTHROPIC_API_KEY=sk-ant-...
+    ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
     ```
 
+!!! info "Direct provider env vars"
+    RubyLLM also reads provider-specific environment variables directly (e.g., `ANTHROPIC_API_KEY`). If you already have those set, they will be picked up automatically. The `ROBOT_LAB_RUBY_LLM__*` prefix gives you explicit control through RobotLab's config layer.
+
 ## Troubleshooting
 
 ### Gem Installation Fails
@@ -167,7 +176,7 @@ bundle add async-websocket
 
 If you see authentication errors:
 
-1. Verify your API key is set: `echo $ANTHROPIC_API_KEY`
+1. Verify your API key is set: `echo $ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY`
 2. Check the key is valid in your provider's console
 3. Ensure you're using the correct environment variable name