robot_lab 0.2.6 → 0.2.8

data/Rakefile

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rake/testtask"
+# Quality gates (quality, rubocop_check, flog_check, flay_check,
+# archspec_check, ...), doc *serving*, and the gem lifecycle (build, install,
+# release) live in asgard — see .loki and the shared dev/*.loki files it
+# imports. This Rakefile keeps the tasks asgard delegates to (tests,
+# integration, examples, docs:build).
 
-RUBOCOP_ENV = { "RUBOCOP_CACHE_ROOT" => "tmp/rubocop_cache" }.freeze
+require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -36,100 +39,6 @@ Rake::TestTask.new(:integration) do |t|
   t.ruby_opts << "-rtest_helper"
 end
 
-desc "Check code complexity with Flog (warn ≥20, fail ≥50)"
-task :flog_check do
-  require 'flog'
-
-  # Target to work toward; methods above this are warned but don't fail the gate.
-  METHOD_WARN = 20.0
-  # Current baseline floor — established from first run. Reduce incrementally.
-  METHOD_FAIL = 50.0
-
-  flogger = Flog.new(all: true)
-  flogger.flog(*Dir.glob('lib/**/*.rb'))
-
-  warnings  = []
-  failures  = []
-
-  flogger.each_by_score do |method, score|
-    next if method.end_with?('#none')  # skip file-level non-method code
-    if score > METHOD_FAIL
-      failures  << "#{'%.1f' % score}: #{method}"
-    elsif score > METHOD_WARN
-      warnings  << "#{'%.1f' % score}: #{method}"
-    end
-  end
-
-  unless warnings.empty?
-    puts "\nFlog warnings (#{METHOD_WARN}–#{METHOD_FAIL}) — target for future refactoring:"
-    warnings.each { |v| puts "  #{v}" }
-  end
-
-  if failures.empty?
-    puts "\nFlog: no methods exceed the failure threshold (≥#{METHOD_FAIL})"
-  else
-    puts "\nFlog failures (≥#{METHOD_FAIL}) — must be refactored:"
-    failures.each { |v| puts "  #{v}" }
-    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{METHOD_FAIL}"
-  end
-end
-
-desc "Check for structural code duplication with Flay (mass >= 50)"
-task :flay_check do
-  require 'flay'
-
-  mass_threshold = 50
-
-  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
-  flay.process(*Dir.glob('lib/**/*.rb'))
-  flay.analyze
-
-  if flay.hashes.empty?
-    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
-  else
-    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
-    flay.report
-    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
-  end
-end
-
-desc "Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay"
-task :quality do
-  results = {}
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Gate: Tests + Coverage"
-  puts '=' * 60
-  results[:tests] = system("bundle exec rake test") ? :pass : :fail
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Gate: RuboCop"
-  puts '=' * 60
-  results[:rubocop] = system(RUBOCOP_ENV, "bundle exec rubocop") ? :pass : :fail
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Gate: Flog Complexity"
-  puts '=' * 60
-  results[:flog] = system("bundle exec rake flog_check") ? :pass : :fail
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Gate: Flay Duplication"
-  puts '=' * 60
-  results[:flay] = system("bundle exec rake flay_check") ? :pass : :fail
-
-  puts "\n#{'=' * 60}"
-  puts "Quality Summary"
-  puts '=' * 60
-  results.each do |gate, status|
-    icon = status == :pass ? 'PASS' : 'FAIL'
-    puts "  [#{icon}] #{gate}"
-  end
-  puts '=' * 60
-
-  abort "\nQuality gate failed" if results.values.any?(:fail)
-  puts "\nAll quality gates passed."
-end
-
 namespace :examples do
   # Map of subdirectory-based demos to their entry point scripts
   SUBDIR_ENTRY_POINTS = {
@@ -277,22 +186,8 @@ namespace :docs 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/_typos.toml

@@ -0,0 +1,21 @@
+# False-positive suppressions for the typos quality gate (asgard).
+# Everything here was reviewed by hand — see git history for context.
+
+[files]
+extend-exclude = [
+  # Example transcripts / articles: prose quotes real names ("Damon Clark")
+  # and SQL-ish plurals ("SELECTs") that typos mis-parses.
+  "examples/ruboruby.md",
+  "examples/25_history_search/conversation.jsonl",
+]
+
+[default.extend-identifiers]
+# Robot names in lib/robot_lab/names.rb
+BATs     = "BATs"
+Damon    = "Damon"
+Mata_Nui = "Mata_Nui"
+Pris     = "Pris"
+S1MONE   = "S1MONE"
+# Test-local variable names
+ba  = "ba"   # b→a similarity (convergence_test.rb)
+thr = "thr"  # thread handle (connection_poller_test.rb)

data/docs/api/core/index.md

@@ -10,16 +10,28 @@ classDiagram
         +name: String
         +description: String
         +model: String
-        +template: String
-        +tools: Array~Tool~
-        +run(message) Message
+        +template: Symbol
+        +local_tools: Array~Tool~
+        +mcp_tools: Array~Tool~
+        +tools_config: Symbol_or_Array
+        +run(message) RobotResult
+    }
+
+    class RobotResult {
+        +robot_name: String
+        +reply: String
+        +output: Array~TextMessage~
+        +input_tokens: Integer
+        +output_tokens: Integer
+        +export() Hash
     }
 
     class Network {
         +name: String
         +robots: Hash
         +config: RunConfig
-        +run(message)
+        +memory: Memory
+        +run(message) SimpleFlow_Result
     }
 
     class RunConfig {
@@ -32,8 +44,9 @@ classDiagram
     class Tool {
         +name: String
         +description: String
-        +parameters: Hash
-        +handler: Proc
+        +robot: Robot
+        +mcp: String
+        +call(args)
     }
 
     class Memory {
@@ -60,22 +73,28 @@ classDiagram
     Robot --> RunConfig : uses
     Robot --> Tool : has
     Robot --> Memory : uses
+    Robot ..> RobotResult : returns
     Network --> Memory : uses
     Robot ..> RobotMessage : sends/receives
+    Memory --> StateProxy : data
 ```
 
 ## Classes
 
 | Class | Purpose |
 |-------|---------|
-| [Robot](robot.md) | LLM agent with personality, tools, and model configuration |
-| [Network](network.md) | Container for robots with routing and orchestration |
-| RunConfig | Shared configuration for LLM, tools, callbacks, and infrastructure |
-| [Tool](tool.md) | Callable function with parameters and handler |
+| [Robot](robot.md) | LLM agent with templates, tools, memory, and model configuration |
+| [RobotResult](result.md) | Value object returned by `Robot#run` |
+| [Network](network.md) | Container for robots with DAG orchestration |
+| [RunConfig](robot.md#runconfig) | Shared configuration for LLM, tools, callbacks, and infrastructure |
+| [Tool](tool.md) | Callable function with parameters and an `execute` method |
 | [AskUser](tool.md#built-in-askuser) | Built-in tool for terminal-based user interaction |
 | [Memory](memory.md) | Reactive key-value store for sharing data |
+| [StateProxy](state.md) | Hash/method-access wrapper returned by `memory.data` |
 | RobotMessage | Typed envelope for bus-based inter-robot communication |
-| `RobotLab::Runnable` | Shared interface (`crew`, `chief`, `run`) implemented by both `Robot` and `Network` — see [Runnable Protocol](../../architecture/core-concepts.md#runnable-protocol) |
+| `RobotLab::Runnable` | Shared interface (`crew`, `chief`, `robot_count`, `network?`, `single?`) implemented by both `Robot` and `Network` — see [Runnable Protocol](../../architecture/core-concepts.md#runnable-protocol) |
+
+There is no `RobotLab::State` class and no `RobotLab::NetworkRun` class.
 
 ## Quick Examples
 
@@ -89,18 +108,25 @@ robot = RobotLab.build(
   local_tools: [greet_tool]
 )
 
-result = robot.run("Hello!")
+result = robot.run("Hello!")              # no tools sent — run() defaults to tools: :none
+result = robot.run("Hello!", tools: :inherit)  # sends greet_tool
+result.reply                              # => String
 ```
 
+`Robot#run` returns a [`RobotLab::RobotResult`](result.md), not a `Message`.
+
 ### Network
 
+The builder DSL method is `task` (there is no `step`):
+
 ```ruby
 network = RobotLab.create_network(name: "my_network") do
-  step :analyzer, analyzer_robot, depends_on: :none
-  step :writer, writer_robot, depends_on: [:analyzer]
+  task :analyzer, analyzer_robot, depends_on: :none
+  task :writer, writer_robot, depends_on: [:analyzer]
 end
 
-result = network.run(message: "Process this")
+result = network.run(message: "Process this")  # => SimpleFlow::Result
+result.value                                   # => RobotResult of the last task
 ```
 
 ### Memory

data/docs/api/core/memory.md

@@ -83,14 +83,33 @@ Retrieve one or more values, optionally waiting until they exist.
 
 **Parameters:**
 
-| Name | Type | Description |
-|------|------|-------------|
-| `keys` | `Symbol`, `String` | One or more keys to retrieve |
-| `wait` | `Boolean`, `Numeric` | `false`: immediate, `true`: block, `Numeric`: timeout |
-
-**Returns:** Single value for one key, `Hash` for multiple keys.
-
-**Raises:** `AwaitTimeout` if timeout expires.
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `*keys` | `Symbol`, `String` | — | One or more keys to retrieve; flattened and symbolized |
+| `wait` | `Boolean`, `Numeric` | `false` | `false`: return immediately (nil if missing). `true`: block indefinitely. `Numeric`: block up to that many seconds |
+
+**Returns:** the single value for one key, a `Hash` keyed by symbol for multiple keys.
+
+**Raises:** `RobotLab::AwaitTimeout` — `"Timeout waiting for :<key> after <N> seconds"`.
+
+!!! warning "Blocking semantics"
+    - On expiry `get` **raises `RobotLab::AwaitTimeout`**; it does not return nil.
+      Rescue it if a missing value is acceptable.
+    - With multiple keys the timeout is applied **per missing key**, not to the
+      call as a whole. `get(:a, :b, :c, wait: 60)` can block for up to 180
+      seconds if all three are missing.
+    - `wait: true` blocks with no deadline and can hang forever. Prefer a numeric
+      timeout in production.
+    - Waiting is implemented with a pipe (`Waiter`, using `IO#wait_readable`), so
+      a blocked reader does not spin.
+
+    ```ruby
+    value = begin
+      memory.get(:sentiment, wait: 30)
+    rescue RobotLab::AwaitTimeout
+      nil
+    end
+    ```
 
 ### key?
 
@@ -114,7 +133,16 @@ Remove a key. Cannot delete reserved keys.
 memory.keys  # => Array<Symbol>
 ```
 
-Get all non-reserved keys.
+All keys **excluding** the reserved ones.
+
+### all_keys
+
+```ruby
+memory.all_keys  # => Array<Symbol>
+```
+
+All keys **including** the reserved ones (`:data`, `:results`, `:messages`,
+`:session_id`, `:cache`).
 
 ### clear
 
@@ -130,7 +158,14 @@ Clear all non-reserved keys.
 memory.reset
 ```
 
-Reset memory to initial state (clears everything including reserved keys, preserves cache).
+Reset memory to its initial state: clears the backend, restores `:data` to `{}`,
+`:results` and `:messages` to `[]`, `:session_id` to `nil`, and re-installs the
+existing cache object. The `StateProxy` returned by `data` is discarded and
+rebuilt on next access.
+
+This resets the **key-value store only**. It has nothing to do with a robot's
+chat history — use `robot.clear_messages(keep_system: true)` for that. The two
+are independent.
 
 ### subscribe
 
@@ -141,20 +176,41 @@ end
 ```
 
 Subscribe to changes on one or more keys. Callback receives a `MemoryChange` object.
+Returns a subscription ID for [`unsubscribe`](#unsubscribe).
+
+**Raises:** `ArgumentError` if no block is given.
+
+Only [`set`](#set) notifies subscribers. Writing a reserved key
+(`memory[:data] = ...`, `session_id=`, `append_result`) bypasses notification
+entirely, as does mutating `memory.data`.
 
-**MemoryChange attributes:**
+Callbacks are dispatched through `Async { }`. **Outside a running reactor the
+callback runs synchronously on the writer's thread**, so a slow subscriber blocks
+the `set` that triggered it.
+
+**`RobotLab::MemoryChange` attributes:**
 
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `key` | `Symbol` | The changed key |
 | `value` | `Object` | New value |
-| `previous` | `Object` | Previous value |
-| `writer` | `String, nil` | Name of robot that wrote |
+| `previous` | `Object, nil` | Previous value |
+| `writer` | `String, nil` | `memory.current_writer` at the time of the write — set to the robot's name for the duration of each `run` |
 | `network_name` | `String, nil` | Network name |
 | `timestamp` | `Time` | When the change occurred |
-| `created?` | `Boolean` | Previous was nil |
-| `updated?` | `Boolean` | Previous was not nil |
-| `deleted?` | `Boolean` | New value is nil |
+| `correlation_id` | `String, nil` | Optional tracing ID |
+
+**Predicates** — note that each tests *both* sides, so all three are false when
+`previous` and `value` are both nil, and all three are false for a nil→nil write:
+
+| Predicate | Exact definition |
+|-----------|------------------|
+| `created?` | `previous.nil? && !value.nil?` |
+| `updated?` | `!previous.nil? && !value.nil?` |
+| `deleted?` | `value.nil? && !previous.nil?` |
+
+Also available: `to_h` (`.compact`ed, `timestamp` rendered as ISO-8601),
+`to_json`, and `MemoryChange.from_hash`.
 
 ### subscribe_pattern
 
@@ -164,7 +220,8 @@ sub_id = memory.subscribe_pattern("analysis:*") do |change|
 end
 ```
 
-Subscribe to keys matching a glob pattern (`*` and `?` supported).
+Subscribe to keys matching a glob pattern (`*` and `?` supported). Returns a
+subscription ID. **Raises:** `ArgumentError` if no block is given.
 
 ### unsubscribe
 
@@ -172,15 +229,131 @@ Subscribe to keys matching a glob pattern (`*` and `?` supported).
 memory.unsubscribe(sub_id)  # => Boolean
 ```
 
-Remove a subscription by its ID.
+Remove a subscription by its ID (works for both `subscribe` and
+`subscribe_pattern`). Returns `true` when something was removed.
+
+### unsubscribe_keys
+
+```ruby
+memory.unsubscribe_keys(:status, :progress)  # => self
+```
+
+Drop **all** key subscriptions for the named keys at once, without needing their
+IDs. Pattern subscriptions are unaffected.
+
+### subscribed?
+
+```ruby
+memory.subscribed?(:status)  # => Boolean
+```
+
+Whether any subscriber — key-based or pattern-based — would be notified for `key`.
 
 ### merge!
 
 ```ruby
-memory.merge!(key1: "value1", key2: "value2")
+memory.merge!(key1: "value1", key2: "value2")  # => self
+```
+
+Merge multiple key-value pairs into memory. Each pair is assigned through `[]=`,
+so non-reserved keys go through the reactive `set` path and do notify subscribers.
+
+## Results and History
+
+### append_result
+
+```ruby
+memory.append_result(robot_result)  # => self
+```
+
+Push a `RobotResult` onto the accumulated `:results` array. Bypasses subscriber
+notification.
+
+### set_results
+
+```ruby
+memory.set_results(array_of_results)  # => self
+```
+
+Replace the whole `:results` array (used when loading from persistence).
+
+### results_from
+
+```ruby
+memory.results_from(5)  # => Array<RobotResult>
 ```
 
-Merge multiple key-value pairs into memory.
+Results from the given index onward — for incremental saves. Returns `[]` when
+the index is past the end.
+
+### format_history
+
+```ruby
+memory.format_history(formatter: nil)  # => Array<Message>
+```
+
+`messages` followed by every result flat-mapped through `formatter`. Pass a
+`Proc` for `formatter:` to control how a `RobotResult` becomes messages; the
+default formatter is used when omitted.
+
+## Backend
+
+### redis?
+
+```ruby
+memory.redis?  # => Boolean
+```
+
+Whether this memory is backed by Redis rather than the in-process Hash. The
+`backend: :auto` default tries Redis and falls back to a Hash; `backend: :hash`
+forces the Hash.
+
+### network_name
+
+```ruby
+memory.network_name  # => String, nil
+```
+
+The network this memory belongs to, set once at construction and read-only
+thereafter. `Network` creates its shared memory as `Memory.new(network_name: name)`;
+a standalone robot's inherent memory has `nil`. It is copied onto every
+`MemoryChange` so a subscriber can tell which network a write came from, and it is
+preserved by `clone`/`dup` — but **not** by `from_hash`.
+
+### current_writer / current_writer=
+
+```ruby
+memory.current_writer          # => String, nil
+memory.current_writer = "bot"
+```
+
+The name attributed to writes, surfaced as `MemoryChange#writer`. `Robot#run`
+sets this to the robot's name for the duration of the run and restores the
+previous value in an `ensure` block, so nested and concurrent runs attribute
+correctly.
+
+## Document Store
+
+These four methods require the **`robot_lab-document_store`** extension gem. Without
+it every one of them raises
+`RobotLab::DependencyError: document storage requires the robot_lab-document_store gem.`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `store_document(key, text)` | `self` | Embed `text` and store it under `key` |
+| `search_documents(query, limit: 5)` | `Array<Hash>` | Hits sorted by score descending; each hash has `:key`, `:text`, `:score` |
+| `document_keys` | `Array<Symbol>` | Keys of all stored documents |
+| `delete_document(key)` | `self` | Remove a document |
+
+```ruby
+memory.store_document(:readme, File.read("README.md"))
+memory.search_documents("how to configure redis", limit: 3).each do |hit|
+  puts "#{hit[:key]} (#{hit[:score].round(3)})"
+end
+```
+
+Documents live in a separate store, not in the key-value backend — they do not
+appear in `keys`, `all_keys`, or `to_h`.
 
 ## Reserved Key Accessors
 
@@ -193,7 +366,9 @@ memory.data.user_id            # Method access
 memory.data[:status] = "active"
 ```
 
-Runtime data accessed through `StateProxy` for method-style access.
+Runtime data accessed through a [`StateProxy`](state.md) for method-style access.
+Writes made through the proxy are **not** reactive — they bypass `set`, so they
+wake no blocking readers and notify no subscribers.
 
 ### results
 
@@ -221,10 +396,22 @@ memory.session_id = "abc"  # Set session identifier
 ### cache
 
 ```ruby
-memory.cache  # => RubyLLM::SemanticCache
+memory.cache  # => RubyLLM::SemanticCache (the module itself), or nil
 ```
 
-Semantic cache module (read-only after initialization).
+Read-only after initialization — assigning it raises
+`ArgumentError: Cannot reassign cache - it is initialized automatically`.
+
+!!! warning "`cache` is `nil` when caching is disabled"
+    The value stored is the `RubyLLM::SemanticCache` **module**, not an instance.
+    When constructed with `enable_cache: false` it is `nil`, so
+    `memory.cache.fetch(...)` raises `NoMethodError`. Guard on
+    `memory.cache` before use, or leave `enable_cache` at its `true` default.
+
+    ```ruby
+    RobotLab::Memory.new.cache                      # => RubyLLM::SemanticCache
+    RobotLab::Memory.new(enable_cache: false).cache # => nil
+    ```
 
 ## Serialization
 
@@ -235,27 +422,50 @@ memory.to_h
 # => { data: {...}, results: [...], messages: [...], session_id: "...", custom: {...} }
 ```
 
+Keys: `data` (from the `StateProxy`), `results` (each via `RobotResult#export`),
+`messages` (each via `to_h`), `session_id`, and `custom` (every non-reserved key).
+`cache` is never serialized.
+
+!!! warning "`to_h` is `.compact`ed"
+    Nil values are dropped, so `session_id` disappears entirely when unset:
+
+    ```ruby
+    RobotLab::Memory.new.to_h
+    # => { data: {}, results: [], messages: [], custom: {} }   -- no :session_id
+    ```
+
+    Consumers must tolerate the missing key. `custom` is always present (it is
+    `{}` rather than nil when there are no custom keys).
+
 ### to_json
 
 ```ruby
 memory.to_json  # => String
 ```
 
+Serializes `to_h`.
+
 ### from_hash
 
 ```ruby
-memory = Memory.from_hash(hash)
+memory = RobotLab::Memory.from_hash(hash)
 ```
 
-Reconstruct memory from a hash.
+Reconstructs `data`, `results`, `messages`, and `session_id`, then re-applies
+every entry from `custom`. A fresh cache is created; subscriptions, backend
+choice, and `network_name` are **not** restored.
 
-### clone
+### clone / dup
 
 ```ruby
 new_memory = memory.clone
+new_memory = memory.dup     # alias for clone
 ```
 
-Deep copy with fresh subscriptions (cache and network_name preserved).
+Deep copy of `data` plus copies of `results`, `messages`, `session_id`, and all
+non-reserved keys. The `enable_cache` setting and `network_name` are preserved.
+Subscriptions are **not** copied — the clone starts with none. Copying custom
+keys uses the internal non-reactive setter, so no notifications fire.
 
 ## Examples
 
@@ -297,11 +507,18 @@ network.memory.set(:sentiment, { score: 0.8, confidence: 0.95 })
 
 # In robot B (reader, may run concurrently)
 result = network.memory.get(:sentiment, wait: true)   # Block indefinitely
-result = network.memory.get(:sentiment, wait: 30)     # Block up to 30s
+result = network.memory.get(:sentiment, wait: 30)     # Block up to 30s, then raise
 
-# Multiple keys with timeout
+# Multiple keys — the timeout applies PER MISSING KEY, so this can block 180s
 results = network.memory.get(:sentiment, :entities, :keywords, wait: 60)
 # => { sentiment: {...}, entities: [...], keywords: [...] }
+
+# Treat a timeout as "not available"
+sentiment = begin
+  network.memory.get(:sentiment, wait: 30)
+rescue RobotLab::AwaitTimeout
+  nil
+end
 ```
 
 ### Reactive Subscriptions
@@ -357,4 +574,5 @@ memory = Memory.from_hash(data)
 ## See Also
 
 - [Memory Guide](../../guides/memory.md)
+- [StateProxy](state.md) — the wrapper returned by `memory.data`
 - [State Management Architecture](../../architecture/state-management.md)