Module: RobotLab

Defined in:
lib/robot_lab.rb,
lib/robot_lab.rb,
lib/robot_lab/hook.rb,
lib/robot_lab/task.rb,
lib/robot_lab/tool.rb,
lib/robot_lab/error.rb,
lib/robot_lab/hooks.rb,
lib/robot_lab/robot.rb,
lib/robot_lab/utils.rb,
lib/robot_lab/config.rb,
lib/robot_lab/errors.rb,
lib/robot_lab/memory.rb,
lib/robot_lab/waiter.rb,
lib/robot_lab/message.rb,
lib/robot_lab/network.rb,
lib/robot_lab/sandbox.rb,
lib/robot_lab/version.rb,
lib/robot_lab/ask_user.rb,
lib/robot_lab/narrator.rb,
lib/robot_lab/runnable.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/capabilities.rb,
lib/robot_lab/hook_context.rb,
lib/robot_lab/robot/budget.rb,
lib/robot_lab/robot_result.rb,
lib/robot_lab/sandbox/null.rb,
lib/robot_lab/user_message.rb,
lib/robot_lab/budget/ledger.rb,
lib/robot_lab/hook_registry.rb,
lib/robot_lab/memory_change.rb,
lib/robot_lab/robot/hooking.rb,
lib/robot_lab/robot_message.rb,
lib/robot_lab/text_analysis.rb,
lib/robot_lab/tool_manifest.rb,
lib/robot_lab/sandbox/seatbelt.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,
sig/robot_lab.rbs

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: Budget, Convergence, Errors, Hooks, MCP, Runnable, Sandbox, ScriptTool, Streaming, TextAnalysis, ToolConfig, Utils Classes: AgentSkill, AgentSkillCatalog, AskUser, AwaitTimeout, BudgetExceeded, BusError, BusPoller, Capabilities, CompactionHookContext, Config, ConfigurationError, DelegationFuture, DependencyError, DoomLoopDetector, DotState, Error, ExtensionState, HistoryCompressor, Hook, HookContext, HookRegistry, InferenceError, LearnHookContext, LlmGenerationHookContext, MCPError, Memory, MemoryChange, Message, Narrator, Network, NetworkRunHookContext, RactorBoundaryError, RedisBackend, Robot, RobotMessage, RobotResult, RunConfig, RunHookContext, StateProxy, Task, TaskHookContext, TextMessage, Tool, ToolCallHookContext, ToolCallMessage, ToolError, ToolLoopError, ToolManifest, ToolMessage, ToolNotFoundError, ToolResultMessage, UserMessage, Waiter

Constant Summary collapse

VERSION =

Returns:

  • (String) 
"0.2.6"

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

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



230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/robot_lab.rb', line 230

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

.clear_hooks! ⇒ Object 



124
125
126
 
# File 'lib/robot_lab.rb', line 124

def clear_hooks!
  @hooks = HookRegistry.new
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



158
159
160
 
# File 'lib/robot_lab.rb', line 158

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



171
172
173
 
# File 'lib/robot_lab.rb', line 171

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



292
293
294
 
# File 'lib/robot_lab.rb', line 292

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



272
273
274
 
# File 'lib/robot_lab.rb', line 272

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

.current_hook_scope ⇒ Object 



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

def current_hook_scope
  Thread.current[:robot_lab_hook_scope]
end

.extension(name) ⇒ Object

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

Parameters:

  • name (Symbol) —

    extension identifier



105
106
107
 
# File 'lib/robot_lab.rb', line 105

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) 


98
99
100
 
# File 'lib/robot_lab.rb', line 98

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

.hooks ⇒ Object 



116
117
118
 
# File 'lib/robot_lab.rb', line 116

def hooks
  @hooks ||= HookRegistry.new
end

.loaded_extensions ⇒ Array<Symbol>

Returns the list of registered extension names.

Returns:

  • (Array<Symbol>) 


112
113
114
 
# File 'lib/robot_lab.rb', line 112

def loaded_extensions
  @extensions.keys
end

.on(handler_class, context: nil) ⇒ Object 



120
121
122
 
# File 'lib/robot_lab.rb', line 120

def on(handler_class, context: nil)
  hooks.on(handler_class, context: context)
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



91
92
93
 
# File 'lib/robot_lab.rb', line 91

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



181
182
183
184
 
# File 'lib/robot_lab.rb', line 181

def reload_config!
  @config = nil
  config
end

.render_template(name, **context) ⇒ String

Render a named prompt template to a String using the configured template library (the prompts_dir from config / ROBOT_LAB_TEMPLATE_PATH). Front matter parameters are supplied as keyword arguments.

Unlike #build (which renders a template as a robot's system prompt), this returns the plain text, so callers can use it as a task, a message, or a grading rubric.

Examples:

RobotLab.render_template(:objective, topic: "commit messages")

Parameters:

  • name (Symbol, String) —

    template id (filename without extension)

  • context (Hash) —

    values for the template's parameters

Returns:

  • (String) —

    the rendered prompt text



200
201
202
 
# File 'lib/robot_lab.rb', line 200

def render_template(name, **context)
  PM.parse(name.to_sym).to_s(**context)
end

.with_hook_scope(registries, per_run_hooks) ⇒ Object 



128
129
130
131
132
133
134
135
136
137
 
# File 'lib/robot_lab.rb', line 128

def with_hook_scope(registries, per_run_hooks)
  previous = Thread.current[:robot_lab_hook_scope]
  Thread.current[:robot_lab_hook_scope] = {
    registries: registries,
    per_run_hooks: per_run_hooks
  }
  yield
ensure
  Thread.current[:robot_lab_hook_scope] = previous
end