Module: RobotLab

Defined in:: lib/robot_lab.rb,
lib/robot_lab.rb,
lib/robot_lab/task.rb,
lib/robot_lab/tool.rb,
lib/robot_lab/error.rb,
lib/robot_lab/robot.rb,
lib/robot_lab/utils.rb,
lib/robot_lab/config.rb,
lib/robot_lab/memory.rb,
lib/robot_lab/waiter.rb,
lib/robot_lab/message.rb,
lib/robot_lab/network.rb,
lib/robot_lab/version.rb,
lib/robot_lab/ask_user.rb,
lib/robot_lab/bus_poller.rb,
lib/robot_lab/mcp/client.rb,
lib/robot_lab/mcp/server.rb,
lib/robot_lab/run_config.rb,
lib/robot_lab/agent_skill.rb,
lib/robot_lab/convergence.rb,
lib/robot_lab/script_tool.rb,
lib/robot_lab/state_proxy.rb,
lib/robot_lab/tool_config.rb,
lib/robot_lab/robot_result.rb,
lib/robot_lab/user_message.rb,
lib/robot_lab/memory_change.rb,
lib/robot_lab/robot_message.rb,
lib/robot_lab/text_analysis.rb,
lib/robot_lab/tool_manifest.rb,
lib/robot_lab/streaming/events.rb,
lib/robot_lab/delegation_future.rb,
lib/robot_lab/streaming/context.rb,
lib/robot_lab/doom_loop_detector.rb,
lib/robot_lab/history_compressor.rb,
lib/robot_lab/mcp/transports/sse.rb,
lib/robot_lab/agent_skill_catalog.rb,
lib/robot_lab/mcp/transports/base.rb,
lib/robot_lab/robot/bus_messaging.rb,
lib/robot_lab/mcp/server_discovery.rb,
lib/robot_lab/mcp/transports/stdio.rb,
lib/robot_lab/robot/history_search.rb,
lib/robot_lab/robot/mcp_management.rb,
lib/robot_lab/mcp/connection_poller.rb,
lib/robot_lab/mcp/transports/websocket.rb,
lib/robot_lab/robot/template_rendering.rb,
lib/robot_lab/robot/agent_skill_matching.rb,
lib/robot_lab/streaming/sequence_counter.rb,
lib/robot_lab/mcp/transports/streamable_http.rb

Overview

Define the module first so Zeitwerk can populate it

RobotLab is a Ruby framework for building and orchestrating multi-robot LLM workflows. It provides a modular architecture with adapters for multiple LLM providers (Anthropic, OpenAI, Gemini), MCP (Model Context Protocol) integration, streaming support, and history management.

Examples:

Basic usage with a single robot

robot = RobotLab.build(name: "assistant", template: "chat.erb")
result = robot.run("Hello, world!")

Creating a network of robots

network = RobotLab.create_network(name: "pipeline") do
  step :analyzer, analyzer, depends_on: :none
  step :writer, writer, depends_on: [:analyzer]
  step :reviewer, reviewer, depends_on: [:writer]
end
result = network.run(message: "Process this document")

Configuration

# Via environment variables (ROBOT_LAB_* prefix)
# ROBOT_LAB_DEFAULT_MODEL=gpt-4
# ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...

# Or via config files (~/.config/robot_lab/config.yml or ./config/robot_lab.yml)
# See lib/robot_lab/config/defaults.yml for all options

# Access configuration values:
RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
RobotLab.config.ruby_llm.request_timeout  #=> 120

Defined Under Namespace

Modules: Convergence, MCP, ScriptTool, Streaming, TextAnalysis, ToolConfig, Utils Classes: AgentSkill, AgentSkillCatalog, AskUser, AwaitTimeout, BusError, BusPoller, Config, ConfigurationError, DelegationFuture, DependencyError, DoomLoopDetector, Error, HistoryCompressor, InferenceError, MCPError, Memory, MemoryChange, Message, Network, RactorBoundaryError, RedisBackend, Robot, RobotMessage, RobotResult, RunConfig, StateProxy, Task, TextMessage, Tool, ToolCallMessage, ToolError, ToolLoopError, ToolManifest, ToolMessage, ToolNotFoundError, ToolResultMessage, UserMessage, Waiter

Constant Summary collapse

VERSION =

"0.2.1"

Class Method Summary collapse

.build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil, config: nil) ⇒ Robot

Factory method to create a new Robot instance.
.config ⇒ Config

Returns the Config object (MywayConfig-based).
.configure {|Config| ... } ⇒ Config

Yields the Config object for block-style configuration.
.create_memory(data: {}, enable_cache: true) ⇒ Memory

Factory method to create a new Memory object.
.create_network(name:, concurrency: :auto, config: nil) { ... } ⇒ Network

Factory method to create a new Network of robots.
.extension(name) ⇒ Object

Returns the module registered for the named extension, or nil.
.extension_loaded?(name) ⇒ Boolean

Returns true if the named extension gem has been loaded.
.loaded_extensions ⇒ Array<Symbol>

Returns the list of registered extension names.
.register_extension(name, mod) ⇒ Object

Registers an extension gem so core can detect it without depending on it.
.reload_config! ⇒ Config

Reload configuration from all sources.

Class Method Details

.build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil, config: nil) ⇒ `Robot`

Factory method to create a new Robot instance.

Examples:

Bare robot (no template or prompt)

robot = RobotLab.build
robot.with_instructions("You are helpful.").run("Hello!")

Robot with template

robot = RobotLab.build(
  name: "assistant",
  template: :assistant,
  context: { tone: "friendly" }
)

Robot with inline system prompt

robot = RobotLab.build(
  name: "helper",
  system_prompt: "You are a helpful assistant."
)

Parameters:

name (String, nil) (defaults to: "robot") —

the unique identifier for the robot (auto-generated if nil)
template (Symbol, nil) (defaults to: nil) —

the prompt_manager template for the robot’s prompt
system_prompt (String, nil) (defaults to: nil) —

inline system prompt (can be used alone or with template)
context (Hash) (defaults to: {}) —

variables to pass to the template
enable_cache (Boolean) (defaults to: true) —

whether to enable semantic caching (default: true)
options (Hash) —

additional options passed to Robot.new

Returns:

(Robot) —

a new Robot instance

# File 'lib/robot_lab.rb', line 181

def build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil,
          config: nil, **)
  Robot.new(
    name: name,
    template: template,
    system_prompt: system_prompt,
    context: context,
    enable_cache: enable_cache,
    bus: bus,
    skills: skills,
    config: config,
    **
  )
end

.config ⇒ `Config`

Returns the Config object (MywayConfig-based).

Configuration is automatically loaded from:

Bundled defaults (lib/robot_lab/config/defaults.yml)
Environment-specific overrides (development, test, production)
XDG config files (~/.config/robot_lab/config.yml)
Project config (./config/robot_lab.yml)
Environment variables (ROBOT_LAB_*)

Examples:

RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
RobotLab.config.ruby_llm.request_timeout  #=> 120
RobotLab.config.development?              #=> true

Returns:

(Config) —

the config instance



127
128
129

# File 'lib/robot_lab.rb', line 127

def config
  @config ||= Config.new.tap(&:after_load)
end

.configure {|Config| ... } ⇒ `Config`

Yields the Config object for block-style configuration.

Examples:

RobotLab.configure do |c|
  c.default_model = "claude-sonnet-4"
end

Yields:

(Config) —

the config instance

Returns:

(Config) —

the config instance



140
141
142

# File 'lib/robot_lab.rb', line 140

def configure
  yield config
end

.create_memory(data: {}, enable_cache: true) ⇒ `Memory`

Factory method to create a new Memory object.

Examples:

Basic memory

memory = RobotLab.create_memory(data: { user_id: 123 })

Memory with custom values

memory = RobotLab.create_memory(data: { category: nil })
memory[:session_id] = "abc123"

Memory with caching disabled

memory = RobotLab.create_memory(data: {}, enable_cache: false)

Parameters:

data (Hash) (defaults to: {}) —

initial runtime data
enable_cache (Boolean) (defaults to: true) —

whether to enable semantic caching (default: true)
options (Hash) —

additional options passed to Memory.new

Returns:

(Memory) —

a new Memory instance



243
244
245

# File 'lib/robot_lab.rb', line 243

def create_memory(data: {}, enable_cache: true, **)
  Memory.new(data: data, enable_cache: enable_cache, **)
end

.create_network(name:, concurrency: :auto, config: nil) { ... } ⇒ `Network`

Factory method to create a new Network of robots.

Examples:

Sequential pipeline

network = RobotLab.create_network(name: "pipeline") do
  step :first, robot1, depends_on: :none
  step :second, robot2, depends_on: [:first]
end

With optional routing

network = RobotLab.create_network(name: "support") do
  step :classifier, classifier, depends_on: :none
  step :billing, billing_robot, depends_on: :optional
  step :technical, technical_robot, depends_on: :optional
end

Parallel execution

network = RobotLab.create_network(name: "analysis") do
  step :fetch, fetcher, depends_on: :none
  step :sentiment, sentiment_bot, depends_on: [:fetch]
  step :entities, entity_bot, depends_on: [:fetch]
  step :merge, merger, depends_on: [:sentiment, :entities]
end

Parameters:

name (String) —

the unique identifier for the network
concurrency (Symbol) (defaults to: :auto) —

concurrency model (:auto, :threads, :async)

Yields:

Block for defining pipeline steps

Returns:

(Network) —

a new Network instance



223
224
225

# File 'lib/robot_lab.rb', line 223

def create_network(name:, concurrency: :auto, config: nil, &)
  Network.new(name: name, concurrency: concurrency, config: config, &)
end

.extension(name) ⇒ `Object`

Returns the module registered for the named extension, or nil.

Parameters:

name (Symbol) —

extension identifier



101
102
103

# File 'lib/robot_lab.rb', line 101

def extension(name)
  @extensions[name]
end

.extension_loaded?(name) ⇒ `Boolean`

Returns true if the named extension gem has been loaded.

Parameters:

name (Symbol) —

extension identifier

Returns:

(Boolean)



94
95
96

# File 'lib/robot_lab.rb', line 94

def extension_loaded?(name)
  @extensions.key?(name)
end

.loaded_extensions ⇒ `Array<Symbol>`

Returns the list of registered extension names.

Returns:

(Array<Symbol>)



108
109
110

# File 'lib/robot_lab.rb', line 108

def loaded_extensions
  @extensions.keys
end

.register_extension(name, mod) ⇒ `Object`

Registers an extension gem so core can detect it without depending on it.

Extension gems call this at load time to announce themselves. Core uses extension_loaded? to guard optional behavior instead of defined?/respond_to?.

Parameters:

name (Symbol) —

identifier for the extension (e.g. :durable, :ractor)
mod (Module, Object) —

the extension’s primary module or a sentinel value



87
88
89

# File 'lib/robot_lab.rb', line 87

def register_extension(name, mod)
  @extensions[name] = mod
end

.reload_config! ⇒ `Config`

Reload configuration from all sources.

Clears the cached Config instance, forcing it to be reloaded on next access.

Returns:

(Config) —

the new config instance

# File 'lib/robot_lab.rb', line 150

def reload_config!
  @config = nil
  config
end

Module: RobotLab

Overview

Examples:

Basic usage with a single robot

Creating a network of robots

Configuration

Defined Under Namespace

Constant Summary collapse

Class Method Summary collapse

Class Method Details

.build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil, config: nil) ⇒ Robot

Examples:

Bare robot (no template or prompt)

Robot with template

Robot with inline system prompt

.config ⇒ Config

Examples:

.configure {|Config| ... } ⇒ Config

Examples:

.create_memory(data: {}, enable_cache: true) ⇒ Memory

Examples:

Basic memory

Memory with custom values

Memory with caching disabled

.create_network(name:, concurrency: :auto, config: nil) { ... } ⇒ Network

Examples:

Sequential pipeline

With optional routing

Parallel execution

.extension(name) ⇒ Object

.extension_loaded?(name) ⇒ Boolean

.loaded_extensions ⇒ Array<Symbol>

.register_extension(name, mod) ⇒ Object

.reload_config! ⇒ Config

.build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, skills: nil, config: nil) ⇒ `Robot`

.config ⇒ `Config`

.configure {|Config| ... } ⇒ `Config`

.create_memory(data: {}, enable_cache: true) ⇒ `Memory`

.create_network(name:, concurrency: :auto, config: nil) { ... } ⇒ `Network`

.extension(name) ⇒ `Object`

.extension_loaded?(name) ⇒ `Boolean`

.loaded_extensions ⇒ `Array<Symbol>`

.register_extension(name, mod) ⇒ `Object`

.reload_config! ⇒ `Config`