robot_lab 0.0.1

data/docs/api/history/active-record-adapter.md

@@ -0,0 +1,195 @@
+# ActiveRecordAdapter
+
+Rails ActiveRecord integration for conversation persistence.
+
+## Class: `RobotLab::History::ActiveRecordAdapter`
+
+```ruby
+adapter = History::ActiveRecordAdapter.new(
+  thread_model: ConversationThread,
+  result_model: ConversationResult
+)
+
+config = adapter.to_config
+```
+
+## Constructor
+
+```ruby
+ActiveRecordAdapter.new(
+  thread_model:,
+  result_model:,
+  thread_factory: nil,
+  result_factory: nil
+)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `thread_model` | `Class` | ActiveRecord model for threads |
+| `result_model` | `Class` | ActiveRecord model for results |
+| `thread_factory` | `Proc`, `nil` | Custom thread creation |
+| `result_factory` | `Proc`, `nil` | Custom result creation |
+
+## Methods
+
+### to_config
+
+```ruby
+config = adapter.to_config
+```
+
+Convert to `History::Config` for use with networks.
+
+## Model Requirements
+
+### Thread Model
+
+```ruby
+# db/migrate/xxx_create_conversation_threads.rb
+create_table :conversation_threads do |t|
+  t.string :external_id, null: false, index: { unique: true }
+  t.jsonb :metadata, default: {}
+  t.timestamps
+end
+
+# app/models/conversation_thread.rb
+class ConversationThread < ApplicationRecord
+  has_many :results, class_name: "ConversationResult",
+           foreign_key: :thread_id, dependent: :destroy
+end
+```
+
+### Result Model
+
+```ruby
+# db/migrate/xxx_create_conversation_results.rb
+create_table :conversation_results do |t|
+  t.references :thread, foreign_key: { to_table: :conversation_threads }
+  t.string :robot_name
+  t.jsonb :input, default: {}
+  t.jsonb :output, default: []
+  t.jsonb :tool_calls, default: []
+  t.jsonb :metadata, default: {}
+  t.integer :position
+  t.timestamps
+end
+
+# app/models/conversation_result.rb
+class ConversationResult < ApplicationRecord
+  belongs_to :thread, class_name: "ConversationThread"
+
+  def to_robot_result
+    RobotLab::RobotResult.from_hash(attributes)
+  end
+end
+```
+
+## Examples
+
+### Basic Setup
+
+```ruby
+adapter = History::ActiveRecordAdapter.new(
+  thread_model: ConversationThread,
+  result_model: ConversationResult
+)
+
+network = RobotLab.create_network do
+  name "chat"
+  history adapter.to_config
+  add_robot assistant
+end
+```
+
+### With Custom Factory
+
+```ruby
+adapter = History::ActiveRecordAdapter.new(
+  thread_model: ConversationThread,
+  result_model: ConversationResult,
+  thread_factory: ->(state:, input:, **context) {
+    ConversationThread.create!(
+      external_id: SecureRandom.uuid,
+      user_id: context[:user_id],
+      title: input.truncate(100),
+      metadata: { source: context[:source] }
+    )
+  }
+)
+```
+
+### With User Scoping
+
+```ruby
+class ScopedAdapter
+  def initialize(thread_model:, result_model:)
+    @thread_model = thread_model
+    @result_model = result_model
+  end
+
+  def to_config
+    History::Config.new(
+      create_thread: method(:create_thread),
+      get: method(:get),
+      append_results: method(:append_results)
+    )
+  end
+
+  private
+
+  def create_thread(state:, input:, user_id:, **)
+    @thread_model.create!(
+      external_id: SecureRandom.uuid,
+      user_id: user_id,
+      title: input.truncate(100)
+    )
+  end
+
+  def get(thread_id:, user_id:, **)
+    thread = @thread_model.find_by(external_id: thread_id, user_id: user_id)
+    return [] unless thread
+    thread.results.order(:position).map(&:to_robot_result)
+  end
+
+  def append_results(thread_id:, new_results:, user_id:, **)
+    thread = @thread_model.find_by!(external_id: thread_id, user_id: user_id)
+    position = thread.results.maximum(:position) || 0
+
+    @result_model.transaction do
+      new_results.each_with_index do |result, i|
+        thread.results.create!(
+          robot_name: result.robot_name,
+          input: result.input.to_h,
+          output: result.output.map(&:to_h),
+          tool_calls: result.tool_calls.map(&:to_h),
+          position: position + i + 1
+        )
+      end
+    end
+  end
+end
+```
+
+### Rails Generator
+
+Use the Rails generator to create models:
+
+```bash
+rails generate robot_lab:history
+```
+
+This creates:
+
+- `ConversationThread` model
+- `ConversationResult` model
+- Database migrations
+- Initializer configuration
+
+## See Also
+
+- [History Overview](index.md)
+- [Config](config.md)
+- [Rails Integration Guide](../../guides/rails-integration.md)

data/docs/api/history/config.md

@@ -0,0 +1,191 @@
+# History::Config
+
+Configuration for conversation persistence.
+
+## Class: `RobotLab::History::Config`
+
+```ruby
+config = History::Config.new(
+  create_thread: create_proc,
+  get: get_proc,
+  append_results: append_proc
+)
+```
+
+## Constructor
+
+```ruby
+Config.new(
+  create_thread:,
+  get:,
+  append_results:
+)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `create_thread` | `Proc` | Creates a new thread |
+| `get` | `Proc` | Retrieves thread history |
+| `append_results` | `Proc` | Appends results to thread |
+
+## Callbacks
+
+### create_thread
+
+Called when a new conversation starts without a thread_id.
+
+```ruby
+create_thread: ->(state:, input:, **context) {
+  # Create and return thread info
+  { id: SecureRandom.uuid }
+}
+```
+
+**Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `state` | `State` | Current state |
+| `input` | `String` | User input |
+| `**context` | `Hash` | Additional context |
+
+**Returns:** Hash with `:id` key.
+
+### get
+
+Called to retrieve existing conversation history.
+
+```ruby
+get: ->(thread_id:, **context) {
+  # Return array of previous results
+  Thread.find(thread_id).results
+}
+```
+
+**Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `thread_id` | `String` | Thread identifier |
+| `**context` | `Hash` | Additional context |
+
+**Returns:** Array of `RobotResult` or hashes.
+
+### append_results
+
+Called after each network run to persist new results.
+
+```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) }
+}
+```
+
+**Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `thread_id` | `String` | Thread identifier |
+| `new_results` | `Array<RobotResult>` | Results to append |
+| `**context` | `Hash` | Additional context |
+
+## Attributes
+
+### create_thread
+
+```ruby
+config.create_thread  # => Proc
+```
+
+### get
+
+```ruby
+config.get  # => Proc
+```
+
+### append_results
+
+```ruby
+config.append_results  # => Proc
+```
+
+## Examples
+
+### Basic Config
+
+```ruby
+STORE = {}
+
+config = History::Config.new(
+  create_thread: ->(state:, **) {
+    id = SecureRandom.uuid
+    STORE[id] = { results: [] }
+    { id: id }
+  },
+
+  get: ->(thread_id:, **) {
+    STORE.dig(thread_id, :results) || []
+  },
+
+  append_results: ->(thread_id:, new_results:, **) {
+    STORE[thread_id][:results].concat(new_results.map(&:to_h))
+  }
+)
+```
+
+### With Context
+
+```ruby
+config = History::Config.new(
+  create_thread: ->(state:, user_id:, **) {
+    Thread.create(user_id: user_id, started_at: Time.current)
+  },
+
+  get: ->(thread_id:, user_id:, **) {
+    Thread.where(id: thread_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)
+    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
+  }
+)
+```
+
+## See Also
+
+- [History Overview](index.md)
+- [ThreadManager](thread-manager.md)
+- [ActiveRecordAdapter](active-record-adapter.md)

data/docs/api/history/index.md

@@ -0,0 +1,132 @@
+# History
+
+Conversation persistence and thread management.
+
+## Overview
+
+The history system enables persistent conversations by storing and retrieving conversation threads and results.
+
+```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
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| [Config](config.md) | History configuration |
+| [ThreadManager](thread-manager.md) | Thread lifecycle management |
+| [ActiveRecordAdapter](active-record-adapter.md) | Rails integration |
+
+## Quick Start
+
+### Basic Configuration
+
+```ruby
+history = History::Config.new(
+  create_thread: ->(state:, input:, **) {
+    { id: SecureRandom.uuid }
+  },
+  get: ->(thread_id:, **) {
+    STORE[thread_id] || []
+  },
+  append_results: ->(thread_id:, new_results:, **) {
+    STORE[thread_id] ||= []
+    STORE[thread_id].concat(new_results)
+  }
+)
+```
+
+### With ActiveRecord
+
+```ruby
+history = History::ActiveRecordAdapter.new(
+  thread_model: ConversationThread,
+  result_model: ConversationResult
+).to_config
+```
+
+## Callbacks
+
+| Callback | Purpose |
+|----------|---------|
+| `create_thread` | Create new conversation thread |
+| `get` | Retrieve existing thread history |
+| `append_results` | Add results to thread |
+
+## 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
+```
+
+## Examples
+
+### In-Memory Store
+
+```ruby
+THREADS = {}
+
+history = History::Config.new(
+  create_thread: ->(state:, **) {
+    id = SecureRandom.uuid
+    THREADS[id] = []
+    { id: id }
+  },
+  get: ->(thread_id:, **) {
+    THREADS[thread_id] || []
+  },
+  append_results: ->(thread_id:, new_results:, **) {
+    THREADS[thread_id].concat(new_results)
+  }
+)
+```
+
+### Redis Store
+
+```ruby
+history = History::Config.new(
+  create_thread: ->(state:, **) {
+    id = SecureRandom.uuid
+    Redis.current.set("thread:#{id}", [].to_json)
+    { id: id }
+  },
+  get: ->(thread_id:, **) {
+    data = Redis.current.get("thread:#{thread_id}")
+    data ? JSON.parse(data) : []
+  },
+  append_results: ->(thread_id:, new_results:, **) {
+    existing = JSON.parse(Redis.current.get("thread:#{thread_id}") || "[]")
+    existing.concat(new_results.map(&:to_h))
+    Redis.current.set("thread:#{thread_id}", existing.to_json)
+  }
+)
+```
+
+## See Also
+
+- [History Guide](../../guides/history.md)
+- [State](../core/state.md)

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

@@ -0,0 +1,144 @@
+# ThreadManager
+
+Manages conversation thread lifecycle.
+
+## Class: `RobotLab::History::ThreadManager`
+
+```ruby
+manager = History::ThreadManager.new(config: history_config)
+```
+
+## Constructor
+
+```ruby
+ThreadManager.new(config:)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `config` | `Config` | History configuration |
+
+## Methods
+
+### create_thread
+
+```ruby
+thread_info = manager.create_thread(state: state, input: input, **context)
+```
+
+Create a new conversation thread.
+
+**Returns:** Hash with `:id` and optional metadata.
+
+### get_history
+
+```ruby
+results = manager.get_history(thread_id: id, **context)
+```
+
+Retrieve conversation history.
+
+**Returns:** Array of `RobotResult`.
+
+### append_results
+
+```ruby
+manager.append_results(thread_id: id, new_results: results, **context)
+```
+
+Add results to a thread.
+
+### ensure_thread
+
+```ruby
+thread_id = manager.ensure_thread(state: state, input: input, **context)
+```
+
+Create thread if state doesn't have one, or return existing.
+
+### load_history
+
+```ruby
+state = manager.load_history(state: state, **context)
+```
+
+Load history into state if thread_id exists.
+
+## Examples
+
+### Basic Usage
+
+```ruby
+config = History::Config.new(...)
+manager = History::ThreadManager.new(config: config)
+
+# Start new conversation
+state = RobotLab.create_state(message: "Hello")
+thread_id = manager.ensure_thread(state: state, input: "Hello")
+state.thread_id = thread_id
+
+# Run and save
+result = network.run(state: state)
+manager.append_results(thread_id: thread_id, new_results: result.new_results)
+
+# Continue conversation
+state2 = RobotLab.create_state(message: "Follow up")
+state2.thread_id = thread_id
+state2 = manager.load_history(state: state2)
+# state2 now has previous results
+```
+
+### In Network
+
+```ruby
+# ThreadManager is used internally by Network
+network = RobotLab.create_network do
+  history config
+  add_robot assistant
+end
+
+# First message - thread created automatically
+result1 = network.run(state: state1)
+thread_id = result1.state.thread_id
+
+# Continue - history loaded automatically
+state2 = RobotLab.create_state(
+  message: UserMessage.new("Continue", thread_id: thread_id)
+)
+result2 = network.run(state: state2)
+```
+
+### Custom Thread Data
+
+```ruby
+manager = History::ThreadManager.new(
+  config: History::Config.new(
+    create_thread: ->(state:, input:, metadata:, **) {
+      Thread.create(
+        title: input.truncate(50),
+        metadata: metadata,
+        created_at: Time.current
+      )
+    },
+    get: ->(thread_id:, **) { Thread.find(thread_id).results },
+    append_results: ->(thread_id:, new_results:, **) {
+      Thread.find(thread_id).results.concat(new_results)
+    }
+  )
+)
+
+# Pass metadata when creating thread
+thread = manager.create_thread(
+  state: state,
+  input: "Help with billing",
+  metadata: { source: "web", priority: "high" }
+)
+```
+
+## See Also
+
+- [History Overview](index.md)
+- [Config](config.md)
+- [ActiveRecordAdapter](active-record-adapter.md)