robot_lab 0.0.1 → 0.0.6

data/docs/api/adapters/index.md

@@ -1,104 +0,0 @@
-# Adapters
-
-LLM provider adapters for unified API access.
-
-## Overview
-
-Adapters provide a consistent interface to different LLM providers, handling the translation between RobotLab's message format and provider-specific APIs.
-
-```ruby
-# Configure globally
-RobotLab.configure do |config|
-  config.default_model = "claude-sonnet-4"
-  # Adapter is selected automatically based on model
-end
-
-# Or configure per-robot
-robot = RobotLab.build do
-  model "gpt-4o"  # Uses OpenAI adapter
-end
-```
-
-## Adapter Selection
-
-Adapters are automatically selected based on model name:
-
-| Model Pattern | Adapter |
-|---------------|---------|
-| `claude-*`, `anthropic/*` | Anthropic |
-| `gpt-*`, `o1-*`, `openai/*` | OpenAI |
-| `gemini-*`, `google/*` | Gemini |
-
-## Common Interface
-
-All adapters implement:
-
-```ruby
-adapter.chat(
-  messages: messages,
-  model: model,
-  tools: tools,
-  system: system_prompt,
-  streaming: callback
-)
-# => Response with content and usage
-```
-
-## Available Adapters
-
-| Adapter | Description |
-|---------|-------------|
-| [Anthropic](anthropic.md) | Claude models via Anthropic API |
-| [OpenAI](openai.md) | GPT models via OpenAI API |
-| [Gemini](gemini.md) | Gemini models via Google AI |
-
-## Configuration
-
-### API Keys
-
-Set via environment variables:
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-export OPENAI_API_KEY="sk-..."
-export GOOGLE_AI_API_KEY="..."
-```
-
-### Custom Endpoints
-
-```ruby
-RobotLab.configure do |config|
-  config.adapter_options = {
-    anthropic: { base_url: "https://custom.anthropic.endpoint" },
-    openai: { base_url: "https://custom.openai.endpoint" }
-  }
-end
-```
-
-## Creating Custom Adapters
-
-Implement the adapter interface:
-
-```ruby
-class MyAdapter
-  def chat(messages:, model:, tools: [], system: nil, streaming: nil)
-    # Translate messages to provider format
-    # Make API call
-    # Translate response back
-
-    Response.new(
-      content: content,
-      tool_calls: tool_calls,
-      usage: { input_tokens: x, output_tokens: y }
-    )
-  end
-end
-
-# Register the adapter
-RobotLab.register_adapter(:my_provider, MyAdapter)
-```
-
-## See Also
-
-- [Configuration Guide](../../getting-started/configuration.md)
-- [Streaming Guide](../../guides/streaming.md)

data/docs/api/adapters/openai.md

@@ -1,134 +0,0 @@
-# OpenAI Adapter
-
-Adapter for GPT models via OpenAI API.
-
-## Class: `RobotLab::Adapters::OpenAI`
-
-```ruby
-# Automatically used for GPT models
-robot = RobotLab.build do
-  model "gpt-4o"
-end
-```
-
-## Supported Models
-
-| Model | Description |
-|-------|-------------|
-| `gpt-4o` | Latest GPT-4 Omni |
-| `gpt-4o-mini` | Fast, efficient GPT-4 |
-| `gpt-4-turbo` | GPT-4 Turbo |
-| `o1-preview` | Reasoning model |
-| `o1-mini` | Fast reasoning model |
-
-## Configuration
-
-### API Key
-
-```bash
-export OPENAI_API_KEY="sk-..."
-```
-
-### Options
-
-```ruby
-RobotLab.configure do |config|
-  config.adapter_options = {
-    openai: {
-      base_url: "https://api.openai.com/v1",
-      organization: "org-...",
-      timeout: 120,
-      max_tokens: 4096
-    }
-  }
-end
-```
-
-### Azure OpenAI
-
-```ruby
-RobotLab.configure do |config|
-  config.adapter_options = {
-    openai: {
-      base_url: "https://your-resource.openai.azure.com",
-      api_key: ENV["AZURE_OPENAI_KEY"],
-      api_version: "2024-02-15-preview"
-    }
-  }
-end
-```
-
-## Features
-
-### Streaming
-
-```ruby
-result = robot.run(state: state) do |event|
-  case event
-  when :text_delta
-    print event.text
-  when :tool_call
-    puts "Calling: #{event.name}"
-  end
-end
-```
-
-### Tool Use
-
-Tools are automatically converted to OpenAI's function calling format:
-
-```ruby
-robot = RobotLab.build do
-  model "gpt-4o"
-
-  tool :get_weather do
-    description "Get current weather"
-    parameter :location, type: :string, required: true
-    handler { |location:, **_| WeatherAPI.fetch(location) }
-  end
-end
-```
-
-### JSON Mode
-
-```ruby
-robot = RobotLab.build do
-  model "gpt-4o"
-  template "Always respond with valid JSON."
-  # Response format is automatically configured
-end
-```
-
-## Response Format
-
-```ruby
-{
-  content: [TextMessage, ...],
-  tool_calls: [ToolCallMessage, ...],
-  usage: {
-    input_tokens: 150,
-    output_tokens: 250,
-    total_tokens: 400
-  },
-  stop_reason: "stop"
-}
-```
-
-## Error Handling
-
-```ruby
-begin
-  result = robot.run(state: state)
-rescue RobotLab::Adapters::RateLimitError => e
-  sleep(e.retry_after || 60)
-  retry
-rescue RobotLab::Adapters::APIError => e
-  logger.error("OpenAI API error: #{e.message}")
-end
-```
-
-## See Also
-
-- [Adapters Overview](index.md)
-- [Streaming Guide](../../guides/streaming.md)
-- [OpenAI API Documentation](https://platform.openai.com/docs/)

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

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

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