robot_lab 0.0.1 → 0.0.6

data/docs/examples/basic-chat.md

@@ -4,7 +4,7 @@ A simple conversational robot example.
 
 ## Overview
 
-This example demonstrates the minimal setup for a conversational robot that can respond to user messages.
+This example demonstrates the minimal setup for a conversational robot that can respond to user messages using `robot.run("message")`.
 
 ## Complete Example
 
@@ -15,21 +15,16 @@ This example demonstrates the minimal setup for a conversational robot that can
 require "bundler/setup"
 require "robot_lab"
 
-# Configure RobotLab
-RobotLab.configure do |config|
-  config.default_model = "claude-sonnet-4"
-end
-
 # Build a simple assistant
-assistant = RobotLab.build do
-  name "assistant"
-  description "A helpful conversational assistant"
-
-  template <<~PROMPT
+assistant = RobotLab.build(
+  name: "assistant",
+  description: "A helpful conversational assistant",
+  system_prompt: <<~PROMPT,
     You are a helpful, friendly assistant. You provide clear,
     concise answers to questions. Be conversational but informative.
   PROMPT
-end
+  model: "claude-sonnet-4"
+)
 
 # Simple REPL
 puts "Chat with the assistant (type 'quit' to exit)"
@@ -42,13 +37,11 @@ loop do
   break if input.nil? || input.downcase == "quit"
   next if input.empty?
 
-  # Create state and run
-  state = RobotLab.create_state(message: input)
-  result = assistant.run(state: state)
+  # Run the robot with the user's message
+  result = assistant.run(input)
 
   # Display response
-  response = result.output.first&.content || "No response"
-  puts "\nAssistant: #{response}"
+  puts "\nAssistant: #{result.last_text_content}"
 end
 
 puts "\nGoodbye!"
@@ -63,14 +56,11 @@ puts "\nGoodbye!"
 require "bundler/setup"
 require "robot_lab"
 
-RobotLab.configure do |config|
-  config.default_model = "claude-sonnet-4"
-end
-
-assistant = RobotLab.build do
-  name "assistant"
-  template "You are a helpful assistant."
-end
+assistant = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are a helpful assistant.",
+  model: "claude-sonnet-4"
+)
 
 puts "Chat with streaming (type 'quit' to exit)"
 puts "-" * 50
@@ -82,11 +72,9 @@ loop do
   break if input.nil? || input.downcase == "quit"
   next if input.empty?
 
-  state = RobotLab.create_state(message: input)
-
   print "\nAssistant: "
-  assistant.run(state: state) do |event|
-    print event.text if event.type == :text_delta
+  result = assistant.run(input) do |event|
+    print event.text if event.respond_to?(:text)
   end
   puts
 end
@@ -94,51 +82,61 @@ end
 puts "\nGoodbye!"
 ```
 
-## With Conversation History
+## With Template
 
 ```ruby
 #!/usr/bin/env ruby
-# examples/chat_with_memory.rb
+# examples/template_chat.rb
 
 require "bundler/setup"
 require "robot_lab"
 
-RobotLab.configure do |config|
-  config.default_model = "claude-sonnet-4"
-end
+# Build a robot using a prompt template file
+# Template: prompts/assistant.md (Markdown with YAML front matter)
+assistant = RobotLab.build(
+  name: "assistant",
+  template: :assistant,
+  context: { tone: "friendly", domain: "general" },
+  model: "claude-sonnet-4"
+)
 
-assistant = RobotLab.build do
-  name "assistant"
-  template "You are a helpful assistant with memory of our conversation."
-end
+puts "Chat with template-based assistant (type 'quit' to exit)"
+puts "-" * 50
 
-# In-memory history store
-HISTORY = {}
-
-history_config = RobotLab::History::Config.new(
-  create_thread: ->(state:, **) {
-    id = SecureRandom.uuid
-    HISTORY[id] = []
-    { id: id }
-  },
-  get: ->(thread_id:, **) {
-    HISTORY[thread_id] || []
-  },
-  append_results: ->(thread_id:, new_results:, **) {
-    HISTORY[thread_id].concat(new_results.map(&:to_h))
-  }
-)
+loop do
+  print "\nYou: "
+  input = gets&.chomp
+
+  break if input.nil? || input.downcase == "quit"
+  next if input.empty?
 
-network = RobotLab.create_network do
-  name "chat"
-  history history_config
-  add_robot assistant
+  result = assistant.run(input)
+  puts "\nAssistant: #{result.last_text_content}"
 end
 
+puts "\nGoodbye!"
+```
+
+## With Memory
+
+```ruby
+#!/usr/bin/env ruby
+# examples/chat_with_memory.rb
+
+require "bundler/setup"
+require "robot_lab"
+
+assistant = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are a helpful assistant. Use the user's name when you know it.",
+  model: "claude-sonnet-4"
+)
+
 puts "Chat with memory (type 'quit' to exit)"
 puts "-" * 50
 
-thread_id = nil
+# Store user info in the robot's inherent memory
+assistant.memory[:user_name] = "Alice"
 
 loop do
   print "\nYou: "
@@ -147,20 +145,34 @@ loop do
   break if input.nil? || input.downcase == "quit"
   next if input.empty?
 
-  message = thread_id ?
-    RobotLab::UserMessage.new(input, thread_id: thread_id) :
-    input
+  # The robot's persistent @chat maintains conversation history automatically
+  result = assistant.run(input)
+  puts "\nAssistant: #{result.last_text_content}"
+end
+
+puts "\nGoodbye!"
+```
 
-  state = RobotLab.create_state(message: message)
-  result = network.run(state: state)
+## Bare Robot with Chaining
 
-  thread_id ||= result.state.thread_id
+```ruby
+#!/usr/bin/env ruby
+# examples/bare_robot.rb
 
-  response = result.last_result&.output&.first&.content || "No response"
-  puts "\nAssistant: #{response}"
-end
+require "bundler/setup"
+require "robot_lab"
 
-puts "\nGoodbye!"
+# Build a bare robot with no template or prompt
+robot = RobotLab.build(name: "bot")
+
+# Configure via chaining
+result = robot
+  .with_model("claude-sonnet-4")
+  .with_temperature(0.7)
+  .with_instructions("You are a pirate. Respond in pirate speak.")
+  .run("What is the weather like today?")
+
+puts result.last_text_content
 ```
 
 ## Running
@@ -174,20 +186,20 @@ ruby examples/basic_chat.rb
 
 # Run with streaming
 ruby examples/streaming_chat.rb
-
-# Run with memory
-ruby examples/chat_with_memory.rb
 ```
 
 ## Key Concepts
 
-1. **Robot Building**: Use `RobotLab.build` with a template
-2. **State Creation**: Use `RobotLab.create_state` with a message
-3. **Execution**: Call `robot.run(state: state)`
-4. **Response**: Access via `result.output.first.content`
+1. **Robot Building**: Use `RobotLab.build(name:, system_prompt:)` or `RobotLab.build(name:, template:)` to create a robot
+2. **Execution**: Call `robot.run("message")` to send a message and get a response
+3. **Response**: Access the text via `result.last_text_content`
+4. **Streaming**: Pass a block to `robot.run("message") { |event| ... }`
+5. **Memory**: Access inherent memory via `robot.memory[:key]`
+6. **Chaining**: Configure with `with_*` methods that return `self`
+7. **Conversation History**: The persistent `@chat` maintains history across multiple `run` calls
 
 ## See Also
 
 - [Building Robots Guide](../guides/building-robots.md)
 - [Streaming Guide](../guides/streaming.md)
-- [History Guide](../guides/history.md)
+- [Robot API Reference](../api/core/robot.md)

data/docs/examples/index.md

@@ -15,6 +15,8 @@ These examples show how to use RobotLab for common scenarios, from simple chatbo
 | [Tool Usage](tool-usage.md) | External API integration |
 | [MCP Server](mcp-server.md) | Creating an MCP tool server |
 | [Rails Application](rails-application.md) | Full Rails integration |
+| [Message Bus](#message-bus) | Bidirectional robot communication with convergence |
+| [Spawning Robots](#spawning-robots) | Dynamic specialist creation at runtime |
 
 ## Quick Links
 
@@ -29,80 +31,117 @@ These examples show how to use RobotLab for common scenarios, from simple chatbo
 - [Streaming Responses](basic-chat.md#with-streaming)
 - [Persistent Conversations](basic-chat.md#with-conversation-history)
 - [MCP Integration](mcp-server.md)
+- [Message Bus Communication](#message-bus)
+- [Spawning Robots](#spawning-robots)
 
 ## Hello World
 
 ```ruby
 require "robot_lab"
 
-RobotLab.configure do |config|
-  config.default_model = "claude-sonnet-4"
-end
+# Configuration is handled automatically via MywayConfig.
+# Set API keys via environment variables:
+#   ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+# Or via config files (~/.config/robot_lab/config.yml)
 
-robot = RobotLab.build do
-  name "greeter"
-  template "You are a friendly greeter. Say hello warmly."
-end
+robot = RobotLab.build(
+  name: "greeter",
+  system_prompt: "You are a friendly greeter. Say hello warmly."
+)
 
-state = RobotLab.create_state(message: "Hi there!")
-result = robot.run(state: state)
+result = robot.run("Hi there!")
 
-puts result.output.first.content
+puts result.last_text_content
 ```
 
 ## Robot with Tools
 
 ```ruby
-robot = RobotLab.build do
-  name "calculator"
-  template "You help with calculations."
-
-  tool :calculate do
-    description "Perform a calculation"
-    parameter :expression, type: :string, required: true
-    handler { |expression:, **_| eval(expression).to_s }
+class CalculatorTool < RubyLLM::Tool
+  description "Perform a calculation"
+
+  param :expression, type: :string, desc: "Math expression to evaluate"
+
+  def execute(expression:)
+    eval(expression).to_s
   end
 end
 
-state = RobotLab.create_state(message: "What's 25 * 4?")
-result = robot.run(state: state)
+robot = RobotLab.build(
+  name: "calculator",
+  system_prompt: "You help with calculations.",
+  local_tools: [CalculatorTool]
+)
+
+result = robot.run("What's 25 * 4?")
+puts result.last_text_content
 ```
 
 ## Network with Routing
 
 ```ruby
-classifier = RobotLab.build do
-  name "classifier"
-  template "Classify: BILLING, TECHNICAL, or GENERAL"
+classifier = RobotLab.build(
+  name: "classifier",
+  system_prompt: "Classify the request as BILLING or TECHNICAL. Respond with only the category."
+)
+
+billing = RobotLab.build(
+  name: "billing",
+  system_prompt: "You handle billing questions."
+)
+
+tech = RobotLab.build(
+  name: "tech",
+  system_prompt: "You handle technical issues."
+)
+
+network = RobotLab.create_network(name: "support") do
+  task :classifier, classifier, depends_on: :none
+  task :billing, billing, depends_on: :optional
+  task :tech, tech, depends_on: :optional
 end
 
-billing = RobotLab.build do
-  name "billing"
-  template "You handle billing questions."
-end
+result = network.run(message: "I was charged twice for my subscription")
 
-tech = RobotLab.build do
-  name "tech"
-  template "You handle technical issues."
-end
+# Access individual robot results via context
+classifier_result = result.context[:classifier]
+puts classifier_result.last_text_content
+```
 
-network = RobotLab.create_network do
-  name "support"
-  add_robot classifier
-  add_robot billing
-  add_robot tech
-
-  router ->(args) {
-    case args.call_count
-    when 0 then :classifier
-    when 1
-      category = args.last_result&.output&.first&.content&.strip
-      category == "BILLING" ? :billing : :tech
-    end
-  }
-end
+## Chaining Configuration
+
+Robots support `with_*` methods that return `self` for chaining:
+
+```ruby
+robot = RobotLab.build(name: "assistant")
+  .with_instructions("You are a helpful coding assistant.")
+  .with_temperature(0.3)
+  .with_model("gpt-4o")
+
+result = robot.run("Explain Ruby blocks.")
+puts result.last_text_content
+```
+
+## Using Templates
+
+Templates are `.md` files with optional YAML front matter, managed by prompt_manager:
 
-result = network.run(state: state)
+```ruby
+# Template file: prompts/support.md
+# ---
+# model: claude-sonnet-4
+# temperature: 0.5
+# ---
+# You are a support assistant for {{ company_name }}.
+
+robot = RobotLab.build(
+  name: "support",
+  template: :support,
+  context: { company_name: "Acme Corp" }
+)
+
+result = robot.run("How do I reset my password?")
+puts result.last_text_content
 ```
 
 ## Running Examples
@@ -122,6 +161,142 @@ result = network.run(state: state)
    ruby examples/basic_chat.rb
    ```
 
+Or use the provided rake tasks:
+
+```bash
+bundle exec rake examples:all          # Run all examples
+bundle exec rake examples:run[1]       # Run specific example by number
+```
+
+## Message Bus
+
+Robots can communicate bidirectionally via a message bus, enabling convergence loops and negotiation patterns. This example demonstrates a comedy critic tasking a comedian to generate jokes until one passes:
+
+```ruby
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+require "robot_lab"
+
+MAX_ATTEMPTS = 5
+
+class Comedian < RobotLab::Robot
+  TEMP_START = 0.2
+  TEMP_STEP  = 0.2
+
+  def initialize(bus:)
+    super(name: "bob", template: :comedian, bus: bus, temperature: TEMP_START)
+    @attempts = 0
+    on_message do |message|
+      @attempts += 1
+      temp = [TEMP_START + TEMP_STEP * (@attempts - 1), 1.0].min
+      with_temperature(temp)
+      joke = run(message.content.to_s).last_text_content.strip
+      send_reply(to: message.from.to_sym, content: joke, in_reply_to: message.key)
+    end
+  end
+
+  attr_reader :attempts
+end
+
+class ComedyCritic < RobotLab::Robot
+  def initialize(bus:)
+    super(name: "alice", template: :comedy_critic, bus: bus)
+    @accepted = false
+    on_message do |message|
+      verdict = run("Evaluate this joke:\n\n#{message.content}").last_text_content.strip
+      @accepted = verdict.start_with?("FUNNY")
+      send_message(to: :bob, content: "Not funny enough. Try again.") unless @accepted
+    end
+  end
+
+  attr_reader :accepted
+end
+
+bus   = TypedBus::MessageBus.new
+bob   = Comedian.new(bus: bus)
+alice = ComedyCritic.new(bus: bus)
+
+alice.send_message(to: :bob, content: "Tell me a funny robot joke.")
+puts "Attempts: #{bob.attempts} / #{MAX_ATTEMPTS}"
+puts "Accepted: #{alice.accepted}"
+```
+
+Key patterns demonstrated:
+
+- **Robot subclasses** with templates for prompt management
+- **Auto-ack** via 1-arg `on_message` blocks
+- **`send_reply(to:, content:, in_reply_to:)`** for correlated responses
+- **Temperature ramping** (0.2 &rarr; 1.0) for increasing creativity
+- **Convergence loop** that terminates when the critic approves
+
+Run: `bundle exec ruby examples/12_message_bus.rb`
+
+## Spawning Robots
+
+Robots can create new specialist robots at runtime using `spawn`. A dispatcher receives questions, decides what kind of specialist is needed, and spawns one on the fly. The bus is created lazily — no explicit setup required:
+
+```ruby
+ENV['ROBOT_LAB_TEMPLATE_PATH'] ||= File.join(__dir__, "prompts")
+require "robot_lab"
+
+QUESTIONS = [
+  "Why did the Roman Empire fall?",
+  "Write a haiku about recursion.",
+  "What is the square root of 144?",
+].freeze
+
+class Dispatcher < RobotLab::Robot
+  attr_reader :spawned
+
+  def initialize(bus: nil)
+    super(name: "dispatcher", template: :dispatcher, bus: bus)
+    @spawned = {}
+    @pending = {}
+
+    on_message do |message|
+      puts "  Dispatcher  <- :#{message.from} replied"
+      puts "               | #{message.content.to_s.lines.first&.strip}"
+      @pending.delete(message.from)
+    end
+  end
+
+  def dispatch(question)
+    plan = run(question).last_text_content.strip
+    role, instruction = plan.split("\n", 2)
+    role = role.strip.downcase.gsub(/\s+/, "_")
+    instruction = instruction&.strip || "You are a helpful #{role}."
+
+    specialist = @spawned[role] ||= spawn(
+      name: role,
+      system_prompt: instruction
+    )
+
+    @pending[role] = question
+
+    specialist.send_message(to: :dispatcher, content:
+      specialist.run(question).last_text_content.strip
+    )
+  end
+end
+
+dispatcher = Dispatcher.new
+
+QUESTIONS.each_with_index do |question, i|
+  puts "\nQuestion #{i + 1}: #{question}"
+  dispatcher.dispatch(question)
+end
+
+puts "\nSpecialists spawned: #{dispatcher.spawned.keys.join(', ')}"
+```
+
+Key patterns demonstrated:
+
+- **`spawn`** for dynamic robot creation (bus created lazily)
+- **`on_message`** for reply handling
+- **LLM-driven delegation** — the dispatcher asks its LLM what specialist to create
+- **Specialist reuse** — spawned robots are cached and reused across questions
+
+Run: `bundle exec ruby examples/13_spawn.rb`
+
 ## See Also
 
 - [Getting Started](../getting-started/index.md)