robot_lab 0.0.1 → 0.0.6

data/Rakefile

@@ -45,23 +45,93 @@ task :rubocop_fix do
 end
 
 namespace :examples do
+  # Map of subdirectory-based demos to their entry point scripts
+  SUBDIR_ENTRY_POINTS = {
+    "14_rusty_circuit" => "open_mic.rb",
+    "15_memory_network_and_bus" => "editorial_pipeline.rb",
+    "16_writers_room" => "writers_room.rb"
+  }.freeze
+
   desc "Run all examples"
   task :all do
+    # Single-file examples
     Dir.glob("examples/*.rb").sort.each do |example|
       puts "\n#{'=' * 60}"
       puts "Running: #{example}"
       puts '=' * 60
       ruby example
     end
+
+    # Subdirectory-based demos
+    SUBDIR_ENTRY_POINTS.each do |dir, entry|
+      path = "examples/#{dir}/#{entry}"
+      next unless File.exist?(path)
+
+      puts "\n#{'=' * 60}"
+      puts "Running: #{path}"
+      puts '=' * 60
+      ruby path
+    end
   end
 
   desc "Run a specific example by number (e.g., rake examples:run[1])"
   task :run, [:num] do |_t, args|
-    example = Dir.glob("examples/#{args[:num].rjust(2, '0')}_*.rb").first
+    padded = args[:num].rjust(2, '0')
+
+    # Try single-file example first
+    example = Dir.glob("examples/#{padded}_*.rb").first
     if example
       ruby example
+      next
+    end
+
+    # Try subdirectory-based demo
+    dir = Dir.glob("examples/#{padded}_*/").first
+    if dir
+      dir_name = File.basename(dir)
+      entry = SUBDIR_ENTRY_POINTS[dir_name]
+      if entry && File.exist?(File.join(dir, entry))
+        ruby File.join(dir, entry)
+      else
+        puts "Example #{args[:num]} directory found (#{dir_name}) but no entry point configured"
+      end
     else
       puts "Example #{args[:num]} not found"
     end
   end
 end
+
+namespace :docs do
+  desc "Build all documentation (YARD and MkDocs)"
+  task build: %i[yard mkdocs]
+
+  desc "Clean generated documentation"
+  task :clean do
+    rm_rf "doc"
+    rm_rf "site"
+  end
+
+  desc "Build YARD API documentation"
+  task :yard do
+    sh "yard doc"
+  end
+
+  namespace :yard do
+    desc "Serve YARD documentation locally"
+    task :serve do
+      sh "yard server --reload"
+    end
+  end
+
+  desc "Build MkDocs documentation"
+  task :mkdocs do
+    sh "mkdocs build"
+  end
+
+  namespace :mkdocs do
+    desc "Serve MkDocs documentation locally"
+    task :serve do
+      sh "mkdocs serve"
+    end
+  end
+end

data/docs/api/core/index.md

@@ -12,21 +12,21 @@ classDiagram
         +model: String
         +template: String
         +tools: Array~Tool~
-        +run(state, network)
+        +run(message) Message
     }
 
     class Network {
         +name: String
         +robots: Hash
-        +router: Proc
-        +run(state)
+        +config: RunConfig
+        +run(message)
     }
 
-    class State {
-        +data: StateProxy
-        +results: Array
-        +messages: Array
-        +memory: Memory
+    class RunConfig {
+        +model: String
+        +temperature: Float
+        +merge(other) RunConfig
+        +apply_to(chat)
     }
 
     class Tool {
@@ -37,16 +37,31 @@ classDiagram
     }
 
     class Memory {
-        +remember(key, value)
-        +recall(key)
-        +forget(key)
-        +scoped(namespace)
+        +set(key, value)
+        +get(key)
+        +delete(key)
+        +data: StateProxy
+        +results: Array
+        +messages: Array
+        +session_id: String
+    }
+
+    class RobotMessage {
+        +id: Integer
+        +from: String
+        +content: String
+        +in_reply_to: String
+        +key()
+        +reply?()
     }
 
     Network --> Robot : contains
+    Network --> RunConfig : uses
+    Robot --> RunConfig : uses
     Robot --> Tool : has
-    State --> Memory : has
-    Network --> State : uses
+    Robot --> Memory : uses
+    Network --> Memory : uses
+    Robot ..> RobotMessage : sends/receives
 ```
 
 ## Classes
@@ -55,59 +70,51 @@ classDiagram
 |-------|---------|
 | [Robot](robot.md) | LLM agent with personality, tools, and model configuration |
 | [Network](network.md) | Container for robots with routing and orchestration |
-| [State](state.md) | Conversation state with data, results, and memory |
+| RunConfig | Shared configuration for LLM, tools, callbacks, and infrastructure |
 | [Tool](tool.md) | Callable function with parameters and handler |
-| [Memory](memory.md) | Namespaced key-value store for sharing data |
+| [AskUser](tool.md#built-in-askuser) | Built-in tool for terminal-based user interaction |
+| [Memory](memory.md) | Reactive key-value store for sharing data |
+| RobotMessage | Typed envelope for bus-based inter-robot communication |
 
 ## Quick Examples
 
 ### Robot
 
 ```ruby
-robot = RobotLab.build do
-  name "assistant"
-  model "claude-sonnet-4"
-  template "You are helpful."
-
-  tool :greet do
-    parameter :name, type: :string
-    handler { |name:, **_| "Hello, #{name}!" }
-  end
-end
+robot = RobotLab.build(
+  name: "assistant",
+  model: "claude-sonnet-4",
+  system_prompt: "You are helpful.",
+  local_tools: [greet_tool]
+)
+
+result = robot.run("Hello!")
 ```
 
 ### Network
 
 ```ruby
-network = RobotLab.create_network do
-  name "my_network"
-  add_robot robot
-  router ->(args) { args.call_count.zero? ? :assistant : nil }
+network = RobotLab.create_network(name: "my_network") do
+  step :analyzer, analyzer_robot, depends_on: :none
+  step :writer, writer_robot, depends_on: [:analyzer]
 end
+
+result = network.run(message: "Process this")
 ```
 
-### State
+### Memory
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Hello",
-  data: { user_id: "123" }
-)
+memory = RobotLab.create_memory(data: { user_id: "123" })
+memory.set(:category, "billing")
+memory.get(:category)  # => "billing"
 ```
 
 ### Tool
 
 ```ruby
-tool = RobotLab::Tool.new(
+tool = RobotLab::Tool.create(
   name: "get_time",
-  description: "Get current time",
-  handler: ->(**, _) { Time.now.to_s }
-)
-```
-
-### Memory
-
-```ruby
-state.memory.remember("key", "value")
-value = state.memory.recall("key")
+  description: "Get current time"
+) { |**_| Time.now.to_s }
 ```