robot_lab 0.0.4 → 0.0.6

data/docs/api/history/config.md

@@ -1,284 +0,0 @@
-# History::Config
-
-Configuration for conversation history persistence using callback-based architecture.
-
-## Class: `RobotLab::History::Config`
-
-```ruby
-config = RobotLab::History::Config.new(
-  create_thread: ->(state:, input:, **) {
-    { session_id: SecureRandom.uuid }
-  },
-  get: ->(session_id:, **) {
-    database.find_results(session_id)
-  },
-  append_results: ->(session_id:, new_results:, **) {
-    database.insert_results(session_id, new_results)
-  }
-)
-```
-
-## Constructor
-
-```ruby
-Config.new(
-  create_thread: nil,
-  get: nil,
-  append_user_message: nil,
-  append_results: nil
-)
-```
-
-All parameters are optional Proc/lambda callbacks. The `configured?` method returns `true` only when both `create_thread` and `get` are set.
-
-**Parameters:**
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `create_thread` | `Proc`, `nil` | `nil` | Callback to create a new conversation thread |
-| `get` | `Proc`, `nil` | `nil` | Callback to retrieve history for a thread |
-| `append_user_message` | `Proc`, `nil` | `nil` | Callback to append user messages |
-| `append_results` | `Proc`, `nil` | `nil` | Callback to append robot results |
-
-## Attributes
-
-All attributes are read-write (`attr_accessor`):
-
-### create_thread
-
-```ruby
-config.create_thread  # => Proc | nil
-config.create_thread = ->(state:, input:, **) { ... }
-```
-
-### get
-
-```ruby
-config.get  # => Proc | nil
-config.get = ->(session_id:, **) { ... }
-```
-
-### append_user_message
-
-```ruby
-config.append_user_message  # => Proc | nil
-config.append_user_message = ->(session_id:, message:, **) { ... }
-```
-
-### append_results
-
-```ruby
-config.append_results  # => Proc | nil
-config.append_results = ->(session_id:, new_results:, **) { ... }
-```
-
-## Methods
-
-### configured?
-
-```ruby
-config.configured?  # => Boolean
-```
-
-Returns `true` if both `create_thread` and `get` callbacks are set.
-
-### create_thread!
-
-```ruby
-result = config.create_thread!(state:, input:, **kwargs)
-```
-
-Invoke the `create_thread` callback. Validates that the callback is configured and that the return value is a Hash containing `:session_id`.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `state` | `Object` | Current state or memory |
-| `input` | `String`, `UserMessage` | Initial user input |
-| `**kwargs` | `Hash` | Additional context passed through |
-
-**Returns:** Hash with at least `{ session_id: "..." }`.
-
-**Raises:** `HistoryError` if callback is not configured or return value is invalid.
-
-### get!
-
-```ruby
-results = config.get!(session_id:, **kwargs)
-```
-
-Invoke the `get` callback to retrieve history for a thread.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `**kwargs` | `Hash` | Additional context |
-
-**Returns:** Array of `RobotResult` (or whatever the callback returns).
-
-**Raises:** `HistoryError` if callback is not configured.
-
-### append_user_message!
-
-```ruby
-config.append_user_message!(session_id:, message:, **kwargs)
-```
-
-Invoke the `append_user_message` callback. No-op if the callback is not configured.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `message` | `UserMessage` | User message to append |
-| `**kwargs` | `Hash` | Additional context |
-
-### append_results!
-
-```ruby
-config.append_results!(session_id:, new_results:, **kwargs)
-```
-
-Invoke the `append_results` callback. No-op if the callback is not configured.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `new_results` | `Array<RobotResult>` | Results to append |
-| `**kwargs` | `Hash` | Additional context |
-
-## Callback Signatures
-
-### create_thread
-
-Called when a new conversation starts.
-
-```ruby
-create_thread: ->(state:, input:, **context) {
-  # Must return a Hash with :session_id
-  { session_id: SecureRandom.uuid }
-}
-```
-
-| Argument | Type | Description |
-|----------|------|-------------|
-| `state` | `Object` | Current robot memory or state |
-| `input` | `String`, `UserMessage` | Initial user input |
-| `**context` | `Hash` | Additional context |
-
-### get
-
-Called to retrieve existing conversation history.
-
-```ruby
-get: ->(session_id:, **context) {
-  # Return array of previous results
-  Thread.find(session_id).results
-}
-```
-
-| Argument | Type | Description |
-|----------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `**context` | `Hash` | Additional context |
-
-### append_user_message
-
-Called to record user messages in the thread.
-
-```ruby
-append_user_message: ->(session_id:, message:, **context) {
-  Thread.find(session_id).update(last_message: message.content)
-}
-```
-
-| Argument | Type | Description |
-|----------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `message` | `UserMessage` | User message |
-| `**context` | `Hash` | Additional context |
-
-### append_results
-
-Called after robot execution to persist results.
-
-```ruby
-append_results: ->(session_id:, new_results:, **context) {
-  new_results.each { |r| Thread.find(session_id).results.create(r.to_h) }
-}
-```
-
-| Argument | Type | Description |
-|----------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `new_results` | `Array<RobotResult>` | Results to append |
-| `**context` | `Hash` | Additional context |
-
-## Error Handling
-
-History operations raise `RobotLab::History::HistoryError` (a subclass of `RobotLab::Error`) when:
-
-- A required callback is not configured and the `!` method is called
-- The `create_thread` callback returns a value without `:session_id`
-
-```ruby
-begin
-  config.create_thread!(state: memory, input: "Hello")
-rescue RobotLab::History::HistoryError => e
-  puts "History error: #{e.message}"
-end
-```
-
-## Examples
-
-### Basic Config
-
-```ruby
-STORE = {}
-
-config = RobotLab::History::Config.new(
-  create_thread: ->(state:, **) {
-    id = SecureRandom.uuid
-    STORE[id] = { results: [] }
-    { session_id: id }
-  },
-  get: ->(session_id:, **) {
-    STORE.dig(session_id, :results) || []
-  },
-  append_results: ->(session_id:, new_results:, **) {
-    STORE[session_id][:results].concat(new_results.map(&:to_h))
-  }
-)
-```
-
-### With User Scoping
-
-```ruby
-config = RobotLab::History::Config.new(
-  create_thread: ->(state:, user_id:, **) {
-    thread = ConversationThread.create!(user_id: user_id)
-    { session_id: thread.session_id }
-  },
-  get: ->(session_id:, user_id:, **) {
-    ConversationThread.where(session_id: session_id, user_id: user_id)
-      .first&.results || []
-  },
-  append_results: ->(session_id:, new_results:, user_id:, **) {
-    thread = ConversationThread.find_by(session_id: session_id, user_id: user_id)
-    return unless thread
-    new_results.each { |r| thread.results.create!(r.to_h) }
-  }
-)
-```
-
-## See Also
-
-- [History Overview](index.md)
-- [ThreadManager](thread-manager.md)
-- [ActiveRecordAdapter](active-record-adapter.md)

data/docs/api/history/index.md

@@ -1,128 +0,0 @@
-# History
-
-Conversation persistence and thread management.
-
-## Overview
-
-The history system enables persistent conversations by storing and retrieving conversation threads and results. It uses a callback-based architecture where you provide lambda/proc implementations for thread creation, retrieval, and result storage.
-
-```ruby
-config = RobotLab::History::Config.new(
-  create_thread: ->(state:, input:, **) {
-    { session_id: SecureRandom.uuid }
-  },
-  get: ->(session_id:, **) {
-    STORE[session_id] || []
-  },
-  append_results: ->(session_id:, new_results:, **) {
-    STORE[session_id] ||= []
-    STORE[session_id].concat(new_results)
-  }
-)
-```
-
-## Components
-
-| Component | Description |
-|-----------|-------------|
-| [Config](config.md) | History configuration with persistence callbacks |
-| [ThreadManager](thread-manager.md) | Thread lifecycle management |
-| [ActiveRecordAdapter](active-record-adapter.md) | Rails ActiveRecord integration |
-
-## Quick Start
-
-### Basic Configuration
-
-```ruby
-STORE = {}
-
-history = RobotLab::History::Config.new(
-  create_thread: ->(state:, input:, **) {
-    id = SecureRandom.uuid
-    STORE[id] = []
-    { session_id: id }
-  },
-  get: ->(session_id:, **) {
-    STORE[session_id] || []
-  },
-  append_results: ->(session_id:, new_results:, **) {
-    STORE[session_id].concat(new_results)
-  }
-)
-```
-
-### With ActiveRecord
-
-```ruby
-adapter = RobotLab::History::ActiveRecordAdapter.new(
-  thread_model: RobotLabThread,
-  result_model: RobotLabResult
-)
-
-config = adapter.to_config
-```
-
-## Callbacks
-
-| Callback | Required | Purpose |
-|----------|----------|---------|
-| `create_thread` | Yes (for `configured?`) | Create a new conversation thread |
-| `get` | Yes (for `configured?`) | Retrieve existing thread history |
-| `append_user_message` | No | Record user messages |
-| `append_results` | No | Persist robot results |
-
-## Thread Lifecycle
-
-1. **Create** -- When a new conversation starts, `create_thread` is called. It must return a Hash with a `:session_id` key.
-2. **Retrieve** -- On subsequent messages, `get` is called with the `session_id` to load previous results.
-3. **Append** -- After each robot execution, `append_results` is called with the new `RobotResult` objects.
-4. **User Messages** -- Optionally, `append_user_message` records each user input.
-
-## Examples
-
-### In-Memory Store
-
-```ruby
-THREADS = {}
-
-history = RobotLab::History::Config.new(
-  create_thread: ->(state:, **) {
-    id = SecureRandom.uuid
-    THREADS[id] = []
-    { session_id: id }
-  },
-  get: ->(session_id:, **) {
-    THREADS[session_id] || []
-  },
-  append_results: ->(session_id:, new_results:, **) {
-    THREADS[session_id].concat(new_results)
-  }
-)
-```
-
-### Redis Store
-
-```ruby
-history = RobotLab::History::Config.new(
-  create_thread: ->(state:, **) {
-    id = SecureRandom.uuid
-    Redis.current.set("thread:#{id}", [].to_json)
-    { session_id: id }
-  },
-  get: ->(session_id:, **) {
-    data = Redis.current.get("thread:#{session_id}")
-    data ? JSON.parse(data) : []
-  },
-  append_results: ->(session_id:, new_results:, **) {
-    existing = JSON.parse(Redis.current.get("thread:#{session_id}") || "[]")
-    existing.concat(new_results.map(&:to_h))
-    Redis.current.set("thread:#{session_id}", existing.to_json)
-  }
-)
-```
-
-## See Also
-
-- [Config](config.md)
-- [ThreadManager](thread-manager.md)
-- [ActiveRecordAdapter](active-record-adapter.md)

data/docs/api/history/thread-manager.md

@@ -1,194 +0,0 @@
-# History::ThreadManager
-
-Manages conversation thread lifecycle using a `History::Config` for persistence.
-
-## Class: `RobotLab::History::ThreadManager`
-
-```ruby
-config = RobotLab::History::Config.new(...)
-manager = RobotLab::History::ThreadManager.new(config)
-
-session_id = manager.create_thread(state: memory, input: "Hello")
-history = manager.get_history(session_id)
-```
-
-## Constructor
-
-```ruby
-ThreadManager.new(config)
-```
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `config` | `Config` | History configuration with persistence callbacks |
-
-## Attributes
-
-### config
-
-```ruby
-manager.config  # => RobotLab::History::Config
-```
-
-The history configuration object.
-
-## Methods
-
-### create_thread
-
-```ruby
-session_id = manager.create_thread(state:, input:)
-```
-
-Create a new conversation thread. Delegates to `config.create_thread!` and returns the `session_id` from the result hash.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `state` | `Object` | Current robot memory or state |
-| `input` | `String`, `UserMessage` | Initial user input |
-
-**Returns:** `String` -- the session ID for the new thread.
-
-### get_history
-
-```ruby
-results = manager.get_history(session_id)
-```
-
-Retrieve conversation history for a thread. Delegates to `config.get!`.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-
-**Returns:** `Array<RobotResult>` -- history of results for the thread.
-
-### append_user_message
-
-```ruby
-manager.append_user_message(session_id:, message:)
-```
-
-Append a user message to the thread. Delegates to `config.append_user_message!`.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `message` | `UserMessage` | User message to append |
-
-### append_results
-
-```ruby
-manager.append_results(session_id:, results:)
-```
-
-Append robot results to the thread. Delegates to `config.append_results!`.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `results` | `Array<RobotResult>` | Results to append |
-
-### load_state
-
-```ruby
-state = manager.load_state(session_id:, state:)
-```
-
-Load history from a thread into a state/memory object. Retrieves the history, sets the `session_id` on the state, and calls `append_result` for each historical result.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `state` | `Object` | State or Memory object to populate |
-
-**Returns:** The state object with loaded history.
-
-### save_state
-
-```ruby
-manager.save_state(session_id:, state:, since_index: 0)
-```
-
-Save new results from a state object to the thread. Extracts results from `state.results` starting at `since_index` and appends them.
-
-**Parameters:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `session_id` | `String` | Thread identifier |
-| `state` | `Object` | State object with results |
-| `since_index` | `Integer` | Save results from this index (default: 0) |
-
-## Examples
-
-### Basic Usage
-
-```ruby
-config = RobotLab::History::Config.new(
-  create_thread: ->(state:, input:, **) { { session_id: SecureRandom.uuid } },
-  get: ->(session_id:, **) { STORE[session_id] || [] },
-  append_results: ->(session_id:, new_results:, **) {
-    STORE[session_id] ||= []
-    STORE[session_id].concat(new_results)
-  }
-)
-
-manager = RobotLab::History::ThreadManager.new(config)
-
-# Start a new conversation
-session_id = manager.create_thread(state: memory, input: "Hello")
-
-# Run a robot and save results
-result = robot.run("Hello")
-manager.append_results(session_id: session_id, results: [result])
-
-# Later, retrieve history
-history = manager.get_history(session_id)
-```
-
-### Loading History into Memory
-
-```ruby
-manager = RobotLab::History::ThreadManager.new(config)
-
-# Create a memory object and load previous conversation
-memory = RobotLab::Memory.new
-manager.load_state(session_id: existing_session_id, state: memory)
-
-# Memory now contains previous results and session_id
-```
-
-### Saving Incremental Results
-
-```ruby
-# Save only new results (since the last save point)
-initial_count = memory.results.length
-
-result = robot.run("Follow-up question")
-memory.append_result(result)
-
-manager.save_state(
-  session_id: session_id,
-  state: memory,
-  since_index: initial_count
-)
-```
-
-## See Also
-
-- [History Overview](index.md)
-- [Config](config.md)
-- [ActiveRecordAdapter](active-record-adapter.md)