robot_lab 0.0.1 → 0.0.4

data/docs/api/history/config.md

@@ -1,14 +1,20 @@
 # History::Config
 
-Configuration for conversation persistence.
+Configuration for conversation history persistence using callback-based architecture.
 
 ## Class: `RobotLab::History::Config`
 
 ```ruby
-config = History::Config.new(
-  create_thread: create_proc,
-  get: get_proc,
-  append_results: append_proc
+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)
+  }
 )
 ```
 
@@ -16,101 +22,217 @@ config = History::Config.new(
 
 ```ruby
 Config.new(
-  create_thread:,
-  get:,
-  append_results:
+  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 | Description |
-|------|------|-------------|
-| `create_thread` | `Proc` | Creates a new thread |
-| `get` | `Proc` | Retrieves thread history |
-| `append_results` | `Proc` | Appends results to thread |
+| 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
 
-## Callbacks
+All attributes are read-write (`attr_accessor`):
 
 ### create_thread
 
-Called when a new conversation starts without a thread_id.
+```ruby
+config.create_thread  # => Proc | nil
+config.create_thread = ->(state:, input:, **) { ... }
+```
+
+### get
 
 ```ruby
-create_thread: ->(state:, input:, **context) {
-  # Create and return thread info
-  { id: SecureRandom.uuid }
-}
+config.get  # => Proc | nil
+config.get = ->(session_id:, **) { ... }
 ```
 
-**Arguments:**
+### 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` | `State` | Current state |
-| `input` | `String` | User input |
-| `**context` | `Hash` | Additional context |
+| `state` | `Object` | Current state or memory |
+| `input` | `String`, `UserMessage` | Initial user input |
+| `**kwargs` | `Hash` | Additional context passed through |
 
-**Returns:** Hash with `:id` key.
+**Returns:** Hash with at least `{ session_id: "..." }`.
 
-### get
+**Raises:** `HistoryError` if callback is not configured or return value is invalid.
 
-Called to retrieve existing conversation history.
+### get!
 
 ```ruby
-get: ->(thread_id:, **context) {
-  # Return array of previous results
-  Thread.find(thread_id).results
-}
+results = config.get!(session_id:, **kwargs)
 ```
 
-**Arguments:**
+Invoke the `get` callback to retrieve history for a thread.
+
+**Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `thread_id` | `String` | Thread identifier |
-| `**context` | `Hash` | Additional context |
+| `session_id` | `String` | Thread identifier |
+| `**kwargs` | `Hash` | Additional context |
 
-**Returns:** Array of `RobotResult` or hashes.
+**Returns:** Array of `RobotResult` (or whatever the callback returns).
 
-### append_results
+**Raises:** `HistoryError` if callback is not configured.
 
-Called after each network run to persist new results.
+### append_user_message!
 
 ```ruby
-append_results: ->(thread_id:, new_results:, **context) {
-  # Persist the new results
-  thread = Thread.find(thread_id)
-  new_results.each { |r| thread.results.create(r.to_h) }
-}
+config.append_user_message!(session_id:, message:, **kwargs)
 ```
 
-**Arguments:**
+Invoke the `append_user_message` callback. No-op if the callback is not configured.
+
+**Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `thread_id` | `String` | Thread identifier |
+| `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 |
-| `**context` | `Hash` | Additional context |
+| `**kwargs` | `Hash` | Additional context |
 
-## Attributes
+## Callback Signatures
 
 ### create_thread
 
+Called when a new conversation starts.
+
 ```ruby
-config.create_thread  # => Proc
+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
-config.get  # => Proc
+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
-config.append_results  # => Proc
+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
@@ -120,66 +242,37 @@ config.append_results  # => Proc
 ```ruby
 STORE = {}
 
-config = History::Config.new(
+config = RobotLab::History::Config.new(
   create_thread: ->(state:, **) {
     id = SecureRandom.uuid
     STORE[id] = { results: [] }
-    { id: id }
+    { session_id: id }
   },
-
-  get: ->(thread_id:, **) {
-    STORE.dig(thread_id, :results) || []
+  get: ->(session_id:, **) {
+    STORE.dig(session_id, :results) || []
   },
-
-  append_results: ->(thread_id:, new_results:, **) {
-    STORE[thread_id][:results].concat(new_results.map(&:to_h))
+  append_results: ->(session_id:, new_results:, **) {
+    STORE[session_id][:results].concat(new_results.map(&:to_h))
   }
 )
 ```
 
-### With Context
+### With User Scoping
 
 ```ruby
-config = History::Config.new(
+config = RobotLab::History::Config.new(
   create_thread: ->(state:, user_id:, **) {
-    Thread.create(user_id: user_id, started_at: Time.current)
+    thread = ConversationThread.create!(user_id: user_id)
+    { session_id: thread.session_id }
   },
-
-  get: ->(thread_id:, user_id:, **) {
-    Thread.where(id: thread_id, user_id: user_id).first&.results || []
+  get: ->(session_id:, user_id:, **) {
+    ConversationThread.where(session_id: session_id, user_id: user_id)
+      .first&.results || []
   },
-
-  append_results: ->(thread_id:, new_results:, user_id:, **) {
-    thread = Thread.find_by(id: thread_id, user_id: user_id)
+  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) }
-  }
-)
-
-# Pass context when running
-network.run(state: state, user_id: current_user.id)
-```
-
-### With Validation
-
-```ruby
-config = History::Config.new(
-  create_thread: ->(state:, **) {
-    raise "Invalid state" unless state.data[:user_id]
-    Thread.create(user_id: state.data[:user_id])
-  },
-
-  get: ->(thread_id:, **) {
-    thread = Thread.find_by(id: thread_id)
-    raise "Thread not found" unless thread
-    thread.results
-  },
-
-  append_results: ->(thread_id:, new_results:, **) {
-    thread = Thread.find(thread_id)
-    Thread.transaction do
-      new_results.each { |r| thread.results.create!(r.to_h) }
-    end
+    new_results.each { |r| thread.results.create!(r.to_h) }
   }
 )
 ```

data/docs/api/history/index.md

@@ -4,47 +4,49 @@ Conversation persistence and thread management.
 
 ## Overview
 
-The history system enables persistent conversations by storing and retrieving conversation threads and results.
+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
-network = RobotLab.create_network do
-  name "persistent_chat"
-
-  history History::Config.new(
-    create_thread: ->(state:, **) { Thread.create(id: SecureRandom.uuid) },
-    get: ->(thread_id:, **) { Thread.find(thread_id).results },
-    append_results: ->(thread_id:, new_results:, **) {
-      Thread.find(thread_id).results.concat(new_results)
-    }
-  )
-
-  add_robot assistant
-end
+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 |
+| [Config](config.md) | History configuration with persistence callbacks |
 | [ThreadManager](thread-manager.md) | Thread lifecycle management |
-| [ActiveRecordAdapter](active-record-adapter.md) | Rails integration |
+| [ActiveRecordAdapter](active-record-adapter.md) | Rails ActiveRecord integration |
 
 ## Quick Start
 
 ### Basic Configuration
 
 ```ruby
-history = History::Config.new(
+STORE = {}
+
+history = RobotLab::History::Config.new(
   create_thread: ->(state:, input:, **) {
-    { id: SecureRandom.uuid }
+    id = SecureRandom.uuid
+    STORE[id] = []
+    { session_id: id }
   },
-  get: ->(thread_id:, **) {
-    STORE[thread_id] || []
+  get: ->(session_id:, **) {
+    STORE[session_id] || []
   },
-  append_results: ->(thread_id:, new_results:, **) {
-    STORE[thread_id] ||= []
-    STORE[thread_id].concat(new_results)
+  append_results: ->(session_id:, new_results:, **) {
+    STORE[session_id].concat(new_results)
   }
 )
 ```
@@ -52,36 +54,29 @@ history = History::Config.new(
 ### With ActiveRecord
 
 ```ruby
-history = History::ActiveRecordAdapter.new(
-  thread_model: ConversationThread,
-  result_model: ConversationResult
-).to_config
+adapter = RobotLab::History::ActiveRecordAdapter.new(
+  thread_model: RobotLabThread,
+  result_model: RobotLabResult
+)
+
+config = adapter.to_config
 ```
 
 ## Callbacks
 
-| Callback | Purpose |
-|----------|---------|
-| `create_thread` | Create new conversation thread |
-| `get` | Retrieve existing thread history |
-| `append_results` | Add results to thread |
+| 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
 
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant N as Network
-    participant H as History
-
-    U->>N: Run with new message
-    N->>H: get(thread_id)
-    H-->>N: Previous results
-    N->>N: Execute robots
-    N->>H: append_results(new_results)
-    H-->>N: Saved
-    N-->>U: Result with thread_id
-```
+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
 
@@ -90,17 +85,17 @@ sequenceDiagram
 ```ruby
 THREADS = {}
 
-history = History::Config.new(
+history = RobotLab::History::Config.new(
   create_thread: ->(state:, **) {
     id = SecureRandom.uuid
     THREADS[id] = []
-    { id: id }
+    { session_id: id }
   },
-  get: ->(thread_id:, **) {
-    THREADS[thread_id] || []
+  get: ->(session_id:, **) {
+    THREADS[session_id] || []
   },
-  append_results: ->(thread_id:, new_results:, **) {
-    THREADS[thread_id].concat(new_results)
+  append_results: ->(session_id:, new_results:, **) {
+    THREADS[session_id].concat(new_results)
   }
 )
 ```
@@ -108,25 +103,26 @@ history = History::Config.new(
 ### Redis Store
 
 ```ruby
-history = History::Config.new(
+history = RobotLab::History::Config.new(
   create_thread: ->(state:, **) {
     id = SecureRandom.uuid
     Redis.current.set("thread:#{id}", [].to_json)
-    { id: id }
+    { session_id: id }
   },
-  get: ->(thread_id:, **) {
-    data = Redis.current.get("thread:#{thread_id}")
+  get: ->(session_id:, **) {
+    data = Redis.current.get("thread:#{session_id}")
     data ? JSON.parse(data) : []
   },
-  append_results: ->(thread_id:, new_results:, **) {
-    existing = JSON.parse(Redis.current.get("thread:#{thread_id}") || "[]")
+  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:#{thread_id}", existing.to_json)
+    Redis.current.set("thread:#{session_id}", existing.to_json)
   }
 )
 ```
 
 ## See Also
 
-- [History Guide](../../guides/history.md)
-- [State](../core/state.md)
+- [Config](config.md)
+- [ThreadManager](thread-manager.md)
+- [ActiveRecordAdapter](active-record-adapter.md)