robot_lab 0.2.8 → 0.3.1

data/docs/getting-started/installation.md

@@ -1,200 +0,0 @@
-# Installation
-
-This guide covers installing RobotLab in your Ruby project.
-
-## Requirements
-
-- **Ruby**: 3.2 or higher
-- **Bundler**: 2.0 or higher (recommended)
-
-## Install via Bundler
-
-Add RobotLab to your `Gemfile`:
-
-```ruby
-gem "robot_lab"
-```
-
-Then install:
-
-```bash
-bundle install
-```
-
-## Install via RubyGems
-
-Or install directly:
-
-```bash
-gem install robot_lab
-```
-
-## Dependencies
-
-RobotLab automatically installs these core dependencies:
-
-| Gem | Purpose |
-|-----|---------|
-| `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.4) | Pipeline workflow execution for networks |
-| `myway_config` (~> 0.1) | Layered configuration (defaults, env vars, config files) |
-| `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 |
-
-> [!NOTE]
-> `async-http` and `async-websocket` are hard runtime dependencies, not optional
-> extras — they install with the gem whether or not you use MCP.
-
-### Optional Dependencies
-
-Several features are gated behind gems the core gem does **not** install. Add
-whichever you need to your own `Gemfile`:
-
-| 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` |
-
-```ruby
-# Gemfile
-gem "classifier", "~> 2.3"
-gem "robot_lab-document_store"
-gem "redis"
-gem "robot_lab-ractor"
-```
-
-> [!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
-
-Create a test file to verify everything works:
-
-```ruby
-# test_robot_lab.rb
-require "robot_lab"
-
-puts "RobotLab version: #{RobotLab::VERSION}"
-puts "Installation successful!"
-```
-
-Run it:
-
-```bash
-ruby test_robot_lab.rb
-# => RobotLab version: 0.2.6
-# => Installation successful!
-```
-
-## Rails Installation
-
-> [!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.
-
-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.
-
-For generators, an `ActiveJob` base class, and Turbo Stream broadcasting, add the
-extension gem:
-
-```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:
-
-=== "Anthropic (Recommended)"
-
-    ```bash
-    export ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY="sk-ant-..."
-    ```
-
-=== "OpenAI"
-
-    ```bash
-    export ROBOT_LAB_RUBY_LLM__OPENAI_API_KEY="sk-..."
-    ```
-
-=== "Google Gemini"
-
-    ```bash
-    export ROBOT_LAB_RUBY_LLM__GEMINI_API_KEY="..."
-    ```
-
-!!! tip "Using dotenv"
-    For development, consider using the [dotenv](https://github.com/bkeepers/dotenv) gem to manage environment variables:
-
-    ```ruby
-    # Gemfile
-    gem "dotenv", groups: [:development, :test]
-    ```
-
-    ```bash
-    # .env
-    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
-
-If you encounter SSL or network errors:
-
-```bash
-# Update RubyGems
-gem update --system
-
-# Try installing with verbose output
-gem install robot_lab --verbose
-```
-
-### Missing Dependencies
-
-If you see a `LoadError` (or a `RobotLab::DependencyError`) naming a gem RobotLab
-does not depend on, add it yourself:
-
-```bash
-# e.g. compress_history / Convergence need the classifier gem
-bundle add classifier
-```
-
-### API Key Issues
-
-If you see authentication errors:
-
-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
-
-## Next Steps
-
-Now that RobotLab is installed:
-
-- [:octicons-arrow-right-24: Quick Start](quick-start.md) - Build your first robot
-- [:octicons-arrow-right-24: Configuration](configuration.md) - Configure defaults

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

@@ -1,293 +0,0 @@
-# Quick Start
-
-Build your first RobotLab application in 5 minutes.
-
-## Step 1: Set Up API Keys
-
-RobotLab reads configuration from environment variables automatically. Set your API key before running any code:
-
-```bash
-export ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY="sk-ant-..."
-```
-
-Or create a config file at `./config/robot_lab.yml`:
-
-```yaml
-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
-
-Build a simple assistant robot using keyword arguments:
-
-```ruby
-require "robot_lab"
-
-assistant = RobotLab.build(
-  name: "assistant",
-  system_prompt: "You are a helpful AI assistant. You provide clear, accurate, and concise answers."
-)
-```
-
-## Step 3: Run It
-
-Send a message and get a response:
-
-```ruby
-result = assistant.run("What is Ruby on Rails?")
-
-puts result.last_text_content
-```
-
-The `run` method takes a positional string message and returns a `RobotResult`. Use `last_text_content` to extract the response text.
-
-## Complete Example
-
-Here is everything together in one file:
-
-```ruby title="hello_robot.rb"
-require "robot_lab"
-
-# Build a robot with an inline system prompt
-assistant = RobotLab.build(
-  name: "assistant",
-  system_prompt: "You are a helpful AI assistant. Be concise and friendly."
-)
-
-# Run the robot with a message
-result = assistant.run("Hello! What can you help me with?")
-
-# Print the response
-puts result.last_text_content
-```
-
-Run it:
-
-```bash
-ruby hello_robot.rb
-```
-
-## Using Templates
-
-Instead of inline prompts, you can use template files managed by `prompt_manager`. Templates are `.md` files with YAML front matter:
-
-```markdown title="prompts/helper.md"
----
-description: A helpful assistant
-parameters:
-  company_name: null
----
-You are a helpful assistant for <%= company_name %>.
-Be concise and friendly in your responses.
-```
-
-Create the robot with a template reference and context:
-
-```ruby
-robot = RobotLab.build(
-  name: "helper",
-  template: :helper,
-  context: { company_name: "Acme Corp" }
-)
-
-result = robot.run("What services do you offer?")
-puts result.last_text_content
-```
-
-Templates are loaded from the `prompts/` directory by default (or `app/prompts/` in Rails). You can change this in your config.
-
-## Adding a Tool
-
-Give your robot custom capabilities by defining a `RubyLLM::Tool` subclass:
-
-```ruby title="hello_tools.rb"
-require "robot_lab"
-
-class CurrentTime < RubyLLM::Tool
-  description "Get the current date and time"
-
-  param :timezone,
-        type: "string",
-        desc: "Timezone name (e.g., 'UTC', 'US/Eastern')",
-        required: false
-
-  def execute(timezone: "UTC")
-    Time.now.getlocal(timezone_offset(timezone)).strftime("%Y-%m-%d %H:%M:%S %Z")
-  rescue => e
-    Time.now.utc.strftime("%Y-%m-%d %H:%M:%S UTC")
-  end
-
-  private
-
-  def timezone_offset(tz)
-    case tz
-    when "UTC" then "+00:00"
-    when "US/Eastern" then "-05:00"
-    when "US/Pacific" then "-08:00"
-    else "+00:00"
-    end
-  end
-end
-
-# Pass tools via the local_tools: parameter
-assistant = RobotLab.build(
-  name: "time_bot",
-  system_prompt: "You are a helpful assistant. Use the current_time tool when users ask about the time.",
-  local_tools: [CurrentTime]
-)
-
-# 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:
-
-```ruby
-robot = RobotLab.build(name: "writer")
-
-result = robot
-  .with_instructions("You are a creative fiction writer.")
-  .with_temperature(0.9)
-  .with_model("claude-sonnet-4")
-  .run("Write a haiku about programming.")
-
-puts result.last_text_content
-```
-
-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
-
-Create a pipeline of robots using `RobotLab.create_network`. Networks use `SimpleFlow::Pipeline` under the hood with `task` definitions and dependency tracking:
-
-```ruby title="hello_network.rb"
-require "robot_lab"
-
-# Build specialized robots
-analyst = RobotLab.build(
-  name: "analyst",
-  system_prompt: <<~PROMPT
-    You are a text analyst. Analyze the given text and provide a brief
-    summary of its key themes and sentiment. Be concise -- 2-3 sentences max.
-  PROMPT
-)
-
-writer = RobotLab.build(
-  name: "writer",
-  system_prompt: <<~PROMPT
-    You are a professional copywriter. Based on the analysis you receive,
-    write a short, engaging summary suitable for a newsletter. Keep it
-    to one paragraph.
-  PROMPT
-)
-
-# Create a sequential pipeline
-network = RobotLab.create_network(name: "content_pipeline") do
-  task :analyst, analyst, depends_on: :none
-  task :writer, writer, depends_on: [:analyst]
-end
-
-# Run the network
-result = network.run(
-  message: "Ruby 3.4 was released with significant performance improvements..."
-)
-
-# The final result is from the last robot in the pipeline
-if result.value.is_a?(RobotLab::RobotResult)
-  puts result.value.last_text_content
-end
-
-# 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:
-
-| Dependency | Meaning |
-|-----------|---------|
-| `depends_on: :none` | Entry point -- runs first with no dependencies |
-| `depends_on: [:task_name]` | Runs after the named task(s) complete |
-| `depends_on: :optional` | Only runs if explicitly activated by a preceding task |
-
-Tasks with non-overlapping dependencies can execute in parallel automatically.
-
-## What's Next?
-
-You have built your first RobotLab application. Here is where to go next:
-
-<div class="grid cards" markdown>
-
--   [:octicons-gear-24: **Configuration**](configuration.md)
-
-    Learn all configuration options
-
--   [:octicons-cpu-24: **Building Robots**](../guides/building-robots.md)
-
-    Deep dive into robot creation
-
--   [:octicons-tools-24: **Using Tools**](../guides/using-tools.md)
-
-    Give robots custom capabilities
-
--   [:octicons-git-branch-24: **Creating Networks**](../guides/creating-networks.md)
-
-    Advanced network patterns
-
-</div>