robot_lab 0.0.11 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4b2a3fafbdf3a54de3044b57597b42d86c68bd2afdad6ce866ac82483e61091
-  data.tar.gz: 5137cff56485a26fabe5ab6606b144c4c3c21c1673ecec1d2254a392e015c25c
+  metadata.gz: 3a8ae2e2cf690116950548d732987e16756870f8444c91504ea14fe039f25996
+  data.tar.gz: 115694d1449233b3a17a28e87deda8bd3d0ac204f51301aee7781156a3b2003e
 SHA512:
-  metadata.gz: 33045f27ec803094a020caee4133c1d6c65887446330c294d9a9babd56a0fe7e71979fe0d032c2421488d1dcae886ad784a78dae579ba01b2786b5f9f91c0172
-  data.tar.gz: 5554296590bfb3dea031c95090ef8a47e946ac1c7a92b3efc6924439f55df7267e0b04d385e2332ea827099c37688c4988aa908caf5bb9d2f21eabc2c50c3167
+  metadata.gz: d512eea2ce533c92b4f791c0d3527fe61805fdca2638e926c0869e0e8f5b0c9a9dc5bac0791db2e5bae8a326b46eaea31c5ffae9ba761b17d1b93b3113735087
+  data.tar.gz: 7e6025d5bbe7252e61e4d7922eea639cda523d7c197535e46400caeeec7f30e7554a015cada107eef796a47c10564d286cdb1d2d4b539a7ac51cc71975b65352

data/CHANGELOG.md

@@ -8,6 +8,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.12] - 2026-04-18
+
+### Added
+
+- **README: Context Window Compression section** — documents `robot.compress_history` with threshold tuning (`recent_turns`, `keep_threshold`, `drop_threshold`) and summarizer lambda pattern
+- **README: Convergence Detection section** — documents `RobotLab::Convergence.detected?` / `.similarity` with network router fast-path example
+- **README: Structured Delegation section** — documents `robot.delegate(to:, task:)` sync and async modes, `DelegationFuture` fan-out pattern, and timeout handling
+- **README: Ractor Parallelism section** — documents `ractor_safe true` tool macro and `parallel_mode: :ractor` network mode with link to full guide
+- **`docs/guides/building-robots.md`** — added matching sections for all four features above with expanded API detail, `DelegationFuture` method table, and convergence router example
+- **`docs/api/core/result.md`** — new API reference for `RobotResult`: attributes, token tracking, delegation metadata, persistence (`export`, `from_hash`, `checksum`), and debug fields
+- **`docs/api/errors.md`** — new error hierarchy reference covering all `RobotLab::Error` subclasses (`ConfigurationError`, `DependencyError`, `InferenceError`, `ToolLoopError`, `ToolNotFoundError`, `MCPError`, `BusError`, `RactorBoundaryError`, `ToolError`, `DelegationFuture::DelegationTimeout`) with rescue examples
+
+### Changed
+
+- Bumped version to 0.0.12
+- Updated `bigdecimal` to 4.1.2
+- Updated `protocol-http` to 0.62.2
+- Updated `protocol-websocket` to 0.21.0
+- Updated `rake` to 13.4.2
+- Updated `sqlite3` to 2.9.3
+
 ## [0.0.11] - 2026-04-14
 
 ### Added

data/README.md

@@ -700,6 +700,136 @@ reviewer.learnings          # => ["This codebase prefers map/collect..."]
 reviewer.learn("new fact")  # deduplicates before storing
 ```
 
+## Context Window Compression
+
+`robot.compress_history` prunes old conversation turns using TF-IDF cosine similarity, keeping only turns that are relevant to the most recent context. System messages and tool call/result pairs are always preserved.
+
+```ruby
+# Basic compression: protect the 3 most recent turns, drop unrelated old turns
+robot.compress_history
+
+# Tune the thresholds
+robot.compress_history(
+  recent_turns:   5,    # protect this many recent user+assistant pairs
+  keep_threshold: 0.6,  # turns scoring >= this are kept verbatim
+  drop_threshold: 0.2   # turns scoring < this are dropped
+)
+
+# Summarize medium-relevance turns instead of dropping them
+summarizer_bot = RobotLab.build(name: "summarizer", system_prompt: "Summarize concisely.")
+robot.compress_history(
+  summarizer: ->(text) { summarizer_bot.run("One sentence: #{text}").reply }
+)
+```
+
+Requires the optional `classifier` gem (`~> 2.3`). Add it to your Gemfile:
+
+```ruby
+gem "classifier", "~> 2.3"
+```
+
+## Convergence Detection
+
+`RobotLab::Convergence` detects when two independent agents have reached the same conclusion using TF-IDF cosine similarity. Use it as a router fast-path to skip an expensive reconciler LLM call when verifiers already agree.
+
+```ruby
+# Check similarity directly
+score = RobotLab::Convergence.similarity(result_a.reply, result_b.reply)
+# => 0.92
+
+# Boolean check against a threshold (default: 0.85)
+RobotLab::Convergence.detected?(result_a.reply, result_b.reply)
+# => true
+
+# Use a custom threshold
+RobotLab::Convergence.detected?(text_a, text_b, threshold: 0.75)
+```
+
+A common pattern is wiring convergence into a network router to skip reconciliation:
+
+```ruby
+router = ->(args) do
+  a = args.context[:verifier_a]&.reply.to_s
+  b = args.context[:verifier_b]&.reply.to_s
+  RobotLab::Convergence.detected?(a, b) ? nil : ["reconciler"]
+end
+
+network = RobotLab.create_network(name: "verify", router: router) do
+  # ...
+end
+```
+
+Requires the `classifier` gem (`~> 2.3`).
+
+## Structured Delegation
+
+`robot.delegate(to:, task:)` dispatches work to another robot and returns the result, with duration and token metadata attached. Pass `async: true` for non-blocking fan-out.
+
+```ruby
+analyst  = RobotLab.build(name: "analyst",  system_prompt: "Analyze data.")
+writer   = RobotLab.build(name: "writer",   system_prompt: "Write reports.")
+manager  = RobotLab.build(name: "manager",  system_prompt: "Coordinate work.")
+
+# Synchronous delegation — blocks until done
+result = manager.delegate(to: analyst, task: "Analyze Q3 sales data")
+puts result.reply
+puts "%.2fs, %d tokens" % [result.duration, result.output_tokens]
+
+# Asynchronous fan-out — returns immediately
+f1 = manager.delegate(to: analyst, task: "Analyze Q3 sales", async: true)
+f2 = manager.delegate(to: writer,  task: "Draft Q3 summary", async: true)
+
+# Do other work here while both run in parallel...
+
+analysis = f1.value           # blocks until resolved
+summary  = f2.value           # blocks until resolved
+
+# With a timeout
+result = f1.value(timeout: 30)  # raises DelegationFuture::DelegationTimeout if too slow
+```
+
+`DelegationFuture` attributes:
+
+```ruby
+future.resolved?      # => true/false (non-blocking poll)
+future.robot_name     # => "analyst"
+future.delegated_by   # => "manager"
+```
+
+## Ractor Parallelism
+
+RobotLab supports true CPU parallelism via Ruby Ractors — isolated execution contexts that bypass the GVL. Two modes are available:
+
+**CPU-bound tools** — mark a tool `ractor_safe true` and RobotLab automatically routes its calls through a global `RactorWorkerPool` instead of running inline:
+
+```ruby
+class TranscribeAudio < RubyLLM::Tool
+  ractor_safe true
+  description "Transcribe an audio file"
+  param :path, type: :string, desc: "Path to audio file"
+
+  def execute(path:)
+    AudioTranscriber.run(path)  # pure computation, no shared mutable state
+  end
+end
+```
+
+**Parallel robot networks** — pass `parallel_mode: :ractor` when creating a network to dispatch independent robots across hardware threads simultaneously:
+
+```ruby
+network = RobotLab.create_network(name: "analysis", parallel_mode: :ractor) do
+  task :fetch,     fetcher_robot,    depends_on: :none
+  task :sentiment, sentiment_robot,  depends_on: [:fetch]
+  task :entities,  entity_robot,     depends_on: [:fetch]   # runs in parallel with sentiment
+  task :summarize, summary_robot,    depends_on: [:sentiment, :entities]
+end
+
+results = network.run(message: "Analyze customer feedback")
+# => { "fetch" => "...", "sentiment" => "positive", "entities" => "...", "summarize" => "..." }
+```
+
+See the [Ractor Parallelism guide](https://madbomber.github.io/robot_lab/guides/ractor-parallelism) for constraints, the frozen-data contract, and `RactorMemoryProxy` for shared state.
+
 ## Rails Integration
 
 ```bash

data/docs/api/core/result.md

@@ -0,0 +1,123 @@
+# RobotResult
+
+`RobotResult` is returned by every `robot.run()` call. It carries the LLM output, tool call results, token usage, timing, and delegation metadata for that execution.
+
+## Accessing the Response
+
+```ruby
+result = robot.run("What is the capital of France?")
+
+result.reply              # => "The capital of France is Paris."
+result.last_text_content  # => alias for reply
+result.output             # => Array of Message objects (full turn)
+result.tool_calls         # => Array of ToolResultMessage objects
+```
+
+`reply` / `last_text_content` returns the content of the last text message in `output`. This is the string you want for the vast majority of use cases.
+
+## Token & Cost Tracking
+
+```ruby
+result.input_tokens   # => Integer — tokens sent to the LLM this run
+result.output_tokens  # => Integer — tokens generated this run
+```
+
+Token counts are zero for providers that do not return usage data.
+
+## Timing
+
+`duration` is set when the result travels through a network pipeline or a `delegate` call. It is `nil` when calling `robot.run()` directly.
+
+```ruby
+result.duration  # => Float (elapsed seconds) or nil
+```
+
+## Delegation Metadata
+
+When a result comes back through `robot.delegate(to:, task:)`, two additional fields are populated:
+
+```ruby
+result.delegated_by  # => "manager"  (the robot that issued the delegation)
+result.duration      # => 2.34       (always set by delegate)
+```
+
+## Identity & Status
+
+```ruby
+result.robot_name   # => "analyst"
+result.id           # => "550e8400-e29b-..."  (UUID, unique per run)
+result.created_at   # => Time instance
+result.stop_reason  # => "end_turn", "tool_use", or nil
+```
+
+## Inspecting the Full Output
+
+```ruby
+result.output.each do |message|
+  puts message.role     # :assistant, :tool, etc.
+  puts message.content  # String or Array
+end
+
+result.has_tool_calls?  # => true if the LLM called any tools
+result.stopped?         # => true if execution ended naturally (not mid-tool-call)
+```
+
+## Persistence
+
+Export for serialization (excludes debug fields):
+
+```ruby
+hash = result.export
+# {
+#   robot_name: "analyst",
+#   output: [...],
+#   tool_calls: [...],
+#   created_at: "2026-04-18T12:00:00Z",
+#   id: "550e8400-...",
+#   checksum: "a1b2c3...",
+#   stop_reason: "end_turn",
+#   duration: 2.34,
+#   input_tokens: 512,
+#   output_tokens: 128
+# }
+
+json = result.to_json
+
+# Reconstruct from hash
+restored = RobotLab::RobotResult.from_hash(hash)
+```
+
+`checksum` is a SHA-256 digest of `output + tool_calls + created_at`. Use it for deduplication when persisting results.
+
+## Debug Fields
+
+These are `nil` by default and only populated when explicitly set for debugging:
+
+```ruby
+result.prompt   # Array<Message> — prompt sent to the LLM
+result.history  # Array<Message> — history used
+result.raw      # raw LLM response object from ruby_llm
+```
+
+## Attribute Reference
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `robot_name` | String | Name of the robot that produced this result |
+| `reply` | String, nil | Last text content (alias: `last_text_content`) |
+| `output` | Array\<Message\> | All output messages from this run |
+| `tool_calls` | Array\<ToolResultMessage\> | Tool call results |
+| `input_tokens` | Integer | Tokens sent to LLM |
+| `output_tokens` | Integer | Tokens generated |
+| `duration` | Float, nil | Elapsed seconds (set by delegate/pipeline) |
+| `delegated_by` | String, nil | Delegating robot's name |
+| `id` | String | UUID |
+| `created_at` | Time | Creation timestamp |
+| `stop_reason` | String, nil | LLM stop reason |
+| `checksum` | String | SHA-256 of output content |
+
+## Related
+
+- [Robot API](robot.md) — `run`, `delegate`, `compress_history`
+- [Building Robots](../../guides/building-robots.md) — Robot construction patterns
+- [Structured Delegation](../../guides/building-robots.md#structured-delegation) — `DelegationFuture` and async fan-out

data/docs/api/errors.md

@@ -0,0 +1,185 @@
+# Error Reference
+
+All RobotLab exceptions inherit from `RobotLab::Error`, which inherits from `StandardError`. Rescue `RobotLab::Error` to catch any framework exception in one clause, or rescue specific subclasses for targeted handling.
+
+## Hierarchy
+
+```
+StandardError
+└── RobotLab::Error
+    ├── RobotLab::ConfigurationError
+    │   └── RobotLab::DependencyError
+    ├── RobotLab::InferenceError
+    │   └── RobotLab::ToolLoopError
+    ├── RobotLab::ToolNotFoundError
+    ├── RobotLab::MCPError
+    ├── RobotLab::BusError
+    ├── RobotLab::RactorBoundaryError
+    └── RobotLab::ToolError
+```
+
+Additionally, `DelegationFuture` defines its own scoped error:
+
+```
+StandardError
+└── RobotLab::Error
+    └── RobotLab::DelegationFuture::DelegationTimeout
+```
+
+---
+
+## RobotLab::Error
+
+Base class for all RobotLab errors. Rescue this to catch any framework exception.
+
+```ruby
+begin
+  robot.run("hello")
+rescue RobotLab::Error => e
+  puts "RobotLab error: #{e.message}"
+end
+```
+
+---
+
+## RobotLab::ConfigurationError
+
+Raised when configuration is invalid or missing required values.
+
+```ruby
+# Example: missing API key, invalid template path
+rescue RobotLab::ConfigurationError => e
+  puts "Bad config: #{e.message}"
+end
+```
+
+---
+
+## RobotLab::DependencyError < ConfigurationError
+
+Raised when a required optional gem dependency is not installed.
+
+```ruby
+# Triggered by: Convergence, HistoryCompressor when 'classifier' gem is absent
+rescue RobotLab::DependencyError => e
+  puts e.message  # "Add gem 'classifier', '~> 2.3' to your Gemfile"
+end
+```
+
+---
+
+## RobotLab::InferenceError
+
+Raised when LLM inference fails (API errors, timeouts, rate limits).
+
+```ruby
+rescue RobotLab::InferenceError => e
+  puts "LLM call failed: #{e.message}"
+end
+```
+
+---
+
+## RobotLab::ToolLoopError < InferenceError
+
+Raised when a robot's tool call count exceeds `max_tool_rounds:`. The chat history will contain a dangling `tool_use` block with no matching `tool_result`; call `robot.clear_messages` before reusing the robot.
+
+```ruby
+robot = RobotLab.build(
+  name: "runner",
+  system_prompt: "Execute every step.",
+  local_tools: [StepTool],
+  max_tool_rounds: 10
+)
+
+begin
+  robot.run("Run all steps.")
+rescue RobotLab::ToolLoopError => e
+  puts e.message  # "Tool call limit of 10 exceeded"
+  robot.clear_messages  # required before reuse
+end
+```
+
+---
+
+## RobotLab::ToolNotFoundError
+
+Raised when a tool name is referenced but cannot be found in the `ToolManifest`.
+
+---
+
+## RobotLab::MCPError
+
+Raised when MCP server communication fails (connection refused, timeout, protocol error).
+
+```ruby
+rescue RobotLab::MCPError => e
+  puts "MCP failed: #{e.message}"
+end
+```
+
+---
+
+## RobotLab::BusError
+
+Raised when message bus communication fails (no bus configured, channel not found).
+
+```ruby
+rescue RobotLab::BusError => e
+  puts "Bus error: #{e.message}"
+end
+```
+
+---
+
+## RobotLab::RactorBoundaryError
+
+Raised when a value cannot be made Ractor-shareable before crossing a Ractor boundary (e.g., a live `IO` object, a `Proc`, or an object with mutable state).
+
+```ruby
+begin
+  RobotLab::RactorBoundary.freeze_deep({ io: StringIO.new })
+rescue RobotLab::RactorBoundaryError => e
+  puts e.message  # "Cannot make value Ractor-shareable: ..."
+end
+```
+
+Raised proactively by `RactorWorkerPool#submit` and `RactorMemoryProxy#set` before any Ractor is involved.
+
+---
+
+## RobotLab::ToolError
+
+Raised when a tool fails during execution inside a Ractor worker (the pool unwraps `RactorJobError` and re-raises as `ToolError`).
+
+```ruby
+begin
+  pool.submit("MyTool", { input: "bad" })
+rescue RobotLab::ToolError => e
+  puts e.message  # "Tool 'MyTool' failed in Ractor: ..."
+end
+```
+
+---
+
+## RobotLab::DelegationFuture::DelegationTimeout
+
+Raised by `DelegationFuture#value(timeout: N)` when the delegated task does not complete within `N` seconds.
+
+```ruby
+future = manager.delegate(to: analyst, task: "...", async: true)
+
+begin
+  result = future.value(timeout: 10)
+rescue RobotLab::DelegationFuture::DelegationTimeout => e
+  puts e.message  # "Delegation to 'analyst' timed out after 10s"
+end
+```
+
+---
+
+## Related
+
+- [Building Robots](../guides/building-robots.md) — Tool loop circuit breaker, delegation
+- [Ractor Parallelism](../guides/ractor-parallelism.md) — Ractor boundary and tool errors
+- [MCP Integration](../guides/mcp-integration.md) — MCP connection errors

data/docs/guides/building-robots.md

@@ -736,6 +736,131 @@ bot = RobotLab.build(name: "latecomer", system_prompt: "Hello.")
 bot.with_bus(existing_bus)  # now connected and can send/receive messages
 ```
 
+## Context Window Compression
+
+Long-running robots accumulate conversation history that can grow to fill the context window. `compress_history` prunes old turns using TF-IDF cosine similarity against the most recent context, keeping turns that are still relevant and discarding or summarizing those that aren't.
+
+```ruby
+# Default settings: protect 3 most-recent turn pairs, drop anything below 0.2
+robot.compress_history
+
+# Tune all thresholds
+robot.compress_history(
+  recent_turns:   5,    # number of recent user+assistant pairs to always keep
+  keep_threshold: 0.6,  # turns with score >= this are kept verbatim (default 0.6)
+  drop_threshold: 0.2   # turns with score < this are dropped (default 0.2)
+)
+```
+
+Medium-relevance turns (between thresholds) are dropped by default. Pass a `summarizer:` callable to replace them with a one-sentence summary instead:
+
+```ruby
+summarizer = RobotLab.build(name: "summarizer", system_prompt: "Summarize concisely in one sentence.")
+
+robot.compress_history(
+  summarizer: ->(text) { summarizer.run("Summarize: #{text}").reply }
+)
+```
+
+**What is always preserved regardless of score:**
+- System messages
+- Tool call/result message pairs (dropping half would corrupt the conversation)
+- The most recent `recent_turns` user+assistant pairs
+
+Requires the `classifier` gem (`~> 2.3`):
+
+```ruby
+gem "classifier", "~> 2.3"
+```
+
+## Convergence Detection
+
+`RobotLab::Convergence` uses TF-IDF cosine similarity to detect when two independent agents have reached the same conclusion. The primary use case is a network router that skips an expensive reconciler robot when two verifiers already agree.
+
+```ruby
+# Check the similarity score directly (returns Float 0.0..1.0)
+score = RobotLab::Convergence.similarity(result_a.reply, result_b.reply)
+
+# Boolean convergence check (default threshold: 0.85)
+RobotLab::Convergence.detected?(result_a.reply, result_b.reply)
+
+# Custom threshold
+RobotLab::Convergence.detected?(text_a, text_b, threshold: 0.75)
+```
+
+Wire it into a network router for the reconciler fast-path:
+
+```ruby
+verifier_a = RobotLab.build(name: "verifier_a", system_prompt: "Verify the answer.")
+verifier_b = RobotLab.build(name: "verifier_b", system_prompt: "Independently verify the answer.")
+reconciler = RobotLab.build(name: "reconciler", system_prompt: "Reconcile conflicting answers.")
+
+router = lambda do |args|
+  a = args.context[:verifier_a]&.reply.to_s
+  b = args.context[:verifier_b]&.reply.to_s
+
+  # Skip reconciler when verifiers agree
+  RobotLab::Convergence.detected?(a, b) ? nil : ["reconciler"]
+end
+
+network = RobotLab.create_network(name: "verify", router: router) do
+  # ...
+end
+```
+
+Requires the `classifier` gem (`~> 2.3`).
+
+## Structured Delegation
+
+A robot can delegate a task to another robot using `delegate(to:, task:)`. The result is a `RobotResult` annotated with `delegated_by`, `duration`, and token counts.
+
+### Synchronous Delegation
+
+The default: blocks the calling robot until the delegatee finishes.
+
+```ruby
+analyst = RobotLab.build(name: "analyst", system_prompt: "Analyze data.")
+manager = RobotLab.build(name: "manager", system_prompt: "Coordinate work.")
+
+result = manager.delegate(to: analyst, task: "Summarize the Q3 report.")
+puts result.reply
+puts "Completed in %.2fs using %d tokens" % [result.duration, result.output_tokens]
+puts result.delegated_by  # => "manager"
+```
+
+### Asynchronous Delegation (Fan-out)
+
+Pass `async: true` to get a `DelegationFuture` back immediately. Call `.value` to block for the result when you need it.
+
+```ruby
+writer  = RobotLab.build(name: "writer",  system_prompt: "Write clearly.")
+analyst = RobotLab.build(name: "analyst", system_prompt: "Analyze data.")
+manager = RobotLab.build(name: "manager", system_prompt: "Coordinate.")
+
+# Fan out — both start immediately
+f1 = manager.delegate(to: analyst, task: "Analyze Q3 numbers", async: true)
+f2 = manager.delegate(to: writer,  task: "Draft the intro paragraph", async: true)
+
+# ... do other work here ...
+
+# Collect results (blocks if not yet done)
+analysis = f1.value
+draft    = f2.value
+
+# With a timeout (raises DelegationFuture::DelegationTimeout)
+result = f1.value(timeout: 30)
+```
+
+`DelegationFuture` API:
+
+| Method | Description |
+|--------|-------------|
+| `resolved?` | Non-blocking poll — true if completed or errored |
+| `value(timeout: nil)` | Block until done; re-raises any error from the delegatee |
+| `wait` | Alias for `value` |
+| `robot_name` | Name of the robot that was delegated to |
+| `delegated_by` | Name of the robot that created this future |
+
 ## Configuration
 
 RobotLab uses `MywayConfig` for configuration. Access the config object directly -- there is no `RobotLab.configure` block:

data/lib/robot_lab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RobotLab
-  VERSION = "0.0.11"
+  VERSION = "0.0.12"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.12
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -244,9 +244,11 @@ files:
 - docs/api/core/index.md
 - docs/api/core/memory.md
 - docs/api/core/network.md
+- docs/api/core/result.md
 - docs/api/core/robot.md
 - docs/api/core/state.md
 - docs/api/core/tool.md
+- docs/api/errors.md
 - docs/api/index.md
 - docs/api/mcp/client.md
 - docs/api/mcp/index.md