robot_lab 0.0.1 → 0.0.6

data/docs/api/history/index.md

@@ -1,132 +0,0 @@
-# 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

@@ -1,144 +0,0 @@
-# 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)

data/docs/guides/history.md

@@ -1,359 +0,0 @@
-# Conversation History
-
-Persist and restore conversation threads across sessions.
-
-## Overview
-
-History allows you to:
-
-- Save conversation results to a database
-- Restore previous conversations
-- Continue multi-turn interactions
-- Maintain context across sessions
-
-## Configuration
-
-### History Config
-
-Configure history with callbacks:
-
-```ruby
-history_config = RobotLab::History::Config.new(
-  create_thread: ->(state:, input:, **) {
-    # Create a new thread, return thread_id
-    { thread_id: SecureRandom.uuid }
-  },
-
-  get: ->(thread_id:, **) {
-    # Retrieve history for thread
-    # Return Array<RobotResult>
-    []
-  },
-
-  append_user_message: ->(thread_id:, message:, **) {
-    # Optional: Store user message
-  },
-
-  append_results: ->(thread_id:, new_results:, **) {
-    # Store new results
-  }
-)
-```
-
-### Apply to Network
-
-```ruby
-network = RobotLab.create_network do
-  name "persistent_chat"
-  history history_config
-end
-```
-
-## Callback Reference
-
-### create_thread
-
-Called when starting a new conversation:
-
-```ruby
-create_thread: ->(state:, input:, **kwargs) {
-  # state - Current State object
-  # input - UserMessage or string
-  # kwargs - Additional context
-
-  thread = Thread.create!(
-    initial_input: input.to_s,
-    user_id: state.data[:user_id]
-  )
-
-  { thread_id: thread.id.to_s }  # Must return hash with :thread_id
-}
-```
-
-### get
-
-Called to retrieve existing history:
-
-```ruby
-get: ->(thread_id:, **kwargs) {
-  # thread_id - The thread identifier
-  # kwargs - Additional context
-
-  Result.where(thread_id: thread_id)
-        .order(:created_at)
-        .map { |r| deserialize_result(r) }
-
-  # Must return Array<RobotResult>
-}
-```
-
-### append_user_message (Optional)
-
-Called when a user message is added:
-
-```ruby
-append_user_message: ->(thread_id:, message:, **kwargs) {
-  # thread_id - The thread identifier
-  # message - UserMessage object
-
-  Message.create!(
-    thread_id: thread_id,
-    content: message.content,
-    metadata: message.metadata
-  )
-}
-```
-
-### append_results
-
-Called after robots finish:
-
-```ruby
-append_results: ->(thread_id:, new_results:, **kwargs) {
-  # thread_id - The thread identifier
-  # new_results - Array<RobotResult>
-
-  new_results.each do |result|
-    Result.create!(
-      thread_id: thread_id,
-      robot_name: result.robot_name,
-      output_data: serialize_output(result.output),
-      stop_reason: result.stop_reason
-    )
-  end
-}
-```
-
-## ActiveRecord Adapter
-
-RobotLab includes a built-in ActiveRecord adapter:
-
-```ruby
-adapter = RobotLab::History::ActiveRecordAdapter.new(
-  thread_model: RobotLabThread,
-  result_model: RobotLabResult
-)
-
-network = RobotLab.create_network do
-  history adapter.to_config
-end
-```
-
-### Required Models
-
-```ruby title="app/models/robot_lab_thread.rb"
-class RobotLabThread < ApplicationRecord
-  has_many :results, class_name: "RobotLabResult", foreign_key: :thread_id
-
-  # Required columns:
-  # - thread_id: string
-  # - initial_input: text
-  # - input_metadata: jsonb
-  # - state_data: jsonb
-  # - last_user_message: text
-  # - last_user_message_at: datetime
-end
-```
-
-```ruby title="app/models/robot_lab_result.rb"
-class RobotLabResult < ApplicationRecord
-  belongs_to :thread, class_name: "RobotLabThread", foreign_key: :thread_id
-
-  # Required columns:
-  # - thread_id: string
-  # - robot_name: string
-  # - sequence_number: integer
-  # - output_data: jsonb
-  # - tool_calls_data: jsonb
-  # - stop_reason: string
-  # - checksum: string
-end
-```
-
-## Using Thread IDs
-
-### Start New Thread
-
-```ruby
-state = RobotLab.create_state(message: "Hello!")
-result = network.run(state: state)
-
-# Thread ID is assigned automatically
-thread_id = state.thread_id
-```
-
-### Continue Existing Thread
-
-```ruby
-# Option 1: Via UserMessage
-message = RobotLab::UserMessage.new(
-  "Continue our conversation",
-  thread_id: existing_thread_id
-)
-state = RobotLab.create_state(message: message)
-
-# Option 2: Direct assignment
-state = RobotLab.create_state(message: "Continue")
-state.thread_id = existing_thread_id
-
-# History is automatically loaded
-result = network.run(state: state)
-```
-
-## ThreadManager
-
-For programmatic control:
-
-```ruby
-manager = RobotLab::History::ThreadManager.new(history_config)
-
-# Create thread
-thread_id = manager.create_thread(state: state, input: message)
-
-# Load history
-results = manager.get_history(thread_id)
-
-# Save state
-manager.save_state(thread_id: thread_id, state: state, since_index: 5)
-```
-
-## Serialization
-
-### RobotResult
-
-Results are serialized via `export`:
-
-```ruby
-result.export
-# => {
-#   robot_name: "assistant",
-#   output: [...],
-#   tool_calls: [...],
-#   stop_reason: "stop",
-#   id: "...",
-#   created_at: "..."
-# }
-```
-
-### Messages
-
-Messages serialize to hashes:
-
-```ruby
-message.to_h
-# => {
-#   type: "text",
-#   role: "assistant",
-#   content: "Hello!",
-#   stop_reason: "stop"
-# }
-```
-
-### Restore from hash
-
-```ruby
-RobotLab::Message.from_hash(hash)
-```
-
-## Patterns
-
-### Redis-Based History
-
-```ruby
-history_config = History::Config.new(
-  create_thread: ->(state:, input:, **) {
-    thread_id = SecureRandom.uuid
-    Redis.current.hset("threads", thread_id, input.to_s)
-    { thread_id: thread_id }
-  },
-
-  get: ->(thread_id:, **) {
-    data = Redis.current.lrange("results:#{thread_id}", 0, -1)
-    data.map { |json| deserialize_result(JSON.parse(json)) }
-  },
-
-  append_results: ->(thread_id:, new_results:, **) {
-    new_results.each do |result|
-      Redis.current.rpush("results:#{thread_id}", result.export.to_json)
-    end
-  }
-)
-```
-
-### Custom Storage
-
-```ruby
-class CustomHistoryAdapter
-  def initialize(storage)
-    @storage = storage
-  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:, **)
-    id = @storage.create_conversation(input: input.to_s)
-    { thread_id: id }
-  end
-
-  def get(thread_id:, **)
-    @storage.fetch_results(thread_id)
-  end
-
-  def append_results(thread_id:, new_results:, **)
-    @storage.store_results(thread_id, new_results)
-  end
-end
-```
-
-## Best Practices
-
-### 1. Handle Missing Threads
-
-```ruby
-get: ->(thread_id:, **) {
-  thread = Thread.find_by(thread_id: thread_id)
-  return [] unless thread
-
-  thread.results.order(:created_at).map(&:to_robot_result)
-}
-```
-
-### 2. Index for Performance
-
-```sql
-CREATE INDEX idx_results_thread_id ON robot_lab_results(thread_id);
-CREATE INDEX idx_results_created_at ON robot_lab_results(created_at);
-```
-
-### 3. Clean Up Old Threads
-
-```ruby
-# Periodic cleanup job
-Thread.where("updated_at < ?", 30.days.ago).destroy_all
-```
-
-### 4. Limit History Size
-
-```ruby
-get: ->(thread_id:, **) {
-  Result.where(thread_id: thread_id)
-        .order(created_at: :desc)
-        .limit(50)  # Last 50 exchanges
-        .reverse
-        .map(&:to_robot_result)
-}
-```
-
-## Next Steps
-
-- [Memory System](memory.md) - In-memory data sharing
-- [State Management](../architecture/state-management.md) - State details
-- [API Reference: History](../api/history/index.md) - Complete API

data/examples/prompts/assistant/user.txt.erb

@@ -1 +0,0 @@
-<%= message %>

data/examples/prompts/billing/user.txt.erb

@@ -1 +0,0 @@
-<%= message %>

data/examples/prompts/classifier/user.txt.erb

@@ -1 +0,0 @@
-<%= message %>

data/examples/prompts/entity_extractor/user.txt.erb

@@ -1,3 +0,0 @@
-Extract all named entities from this text:
-
-<%= message %>

data/examples/prompts/escalation/user.txt.erb

@@ -1,34 +0,0 @@
-Customer <%= customer[:name] %> (escalated case): <%= message %>
-
-## Case Context
-<% if defined?(escalation_context) && escalation_context %>
-<% if escalation_context[:previous_interactions]&.any? %>
-### Previous Interactions
-<% escalation_context[:previous_interactions].each do |interaction| %>
-- <%= interaction[:date] %> (<%= interaction[:channel] %>): <%= interaction[:summary] %>
-<% end %>
-<% end %>
-
-<% if escalation_context[:related_orders]&.any? %>
-### Related Orders
-<% escalation_context[:related_orders].each do |order| %>
-- Order #<%= order[:id] %>: $<%= order[:total] %> - <%= order[:status] %>
-<% end %>
-<% end %>
-
-<% if escalation_context[:compensation_history]&.any? %>
-### Previous Compensation
-<% escalation_context[:compensation_history].each do |comp| %>
-- <%= comp[:date] %>: <%= comp[:type] %> - $<%= comp[:amount] %> (<%= comp[:reason] %>)
-<% end %>
-<% end %>
-
-### Escalation Reason
-<%= escalation_context[:escalation_reason] || "Not specified" %>
-
-### Sentiment Analysis
-- Detected Sentiment: <%= escalation_context[:sentiment] || "Unknown" %>
-- Urgency Level: <%= escalation_context[:urgency] || "Normal" %>
-<% end %>
-
-Please resolve this escalated case with empathy and authority.

data/examples/prompts/general/user.txt.erb

@@ -1 +0,0 @@
-<%= message %>

data/examples/prompts/github_assistant/user.txt.erb

@@ -1 +0,0 @@
-<%= message %>

data/examples/prompts/helper/user.txt.erb

@@ -1 +0,0 @@
-<%= message %>

data/examples/prompts/keyword_extractor/user.txt.erb

@@ -1,3 +0,0 @@
-Extract keywords and topics from this text:
-
-<%= message %>

data/examples/prompts/order_support/user.txt.erb

@@ -1,22 +0,0 @@
-Customer <%= customer[:name] %> asks: <%= message %>
-
-## Order History
-<% if orders&.any? %>
-<% orders.each do |order| %>
-### Order #<%= order[:id] %>
-- Date: <%= order[:date] %>
-- Status: <%= order[:status] %>
-- Total: $<%= order[:total] %>
-- Items:
-<% order[:items].each do |item| %>
-  - <%= item[:name] %> (x<%= item[:quantity] %>) - $<%= item[:price] %>
-<% end %>
-<% if order[:tracking] %>
-- Tracking: <%= order[:tracking] %>
-<% end %>
-<% end %>
-<% else %>
-No orders found for this customer.
-<% end %>
-
-Please help the customer with their order inquiry.