robot_lab 0.0.1

data/docs/api/adapters/index.md

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

@@ -0,0 +1,134 @@
+# 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/core/index.md

@@ -0,0 +1,113 @@
+# Core Classes
+
+The fundamental classes that power RobotLab.
+
+## Overview
+
+```mermaid
+classDiagram
+    class Robot {
+        +name: String
+        +description: String
+        +model: String
+        +template: String
+        +tools: Array~Tool~
+        +run(state, network)
+    }
+
+    class Network {
+        +name: String
+        +robots: Hash
+        +router: Proc
+        +run(state)
+    }
+
+    class State {
+        +data: StateProxy
+        +results: Array
+        +messages: Array
+        +memory: Memory
+    }
+
+    class Tool {
+        +name: String
+        +description: String
+        +parameters: Hash
+        +handler: Proc
+    }
+
+    class Memory {
+        +remember(key, value)
+        +recall(key)
+        +forget(key)
+        +scoped(namespace)
+    }
+
+    Network --> Robot : contains
+    Robot --> Tool : has
+    State --> Memory : has
+    Network --> State : uses
+```
+
+## Classes
+
+| Class | Purpose |
+|-------|---------|
+| [Robot](robot.md) | LLM agent with personality, tools, and model configuration |
+| [Network](network.md) | Container for robots with routing and orchestration |
+| [State](state.md) | Conversation state with data, results, and memory |
+| [Tool](tool.md) | Callable function with parameters and handler |
+| [Memory](memory.md) | Namespaced key-value store for sharing data |
+
+## Quick Examples
+
+### Robot
+
+```ruby
+robot = RobotLab.build do
+  name "assistant"
+  model "claude-sonnet-4"
+  template "You are helpful."
+
+  tool :greet do
+    parameter :name, type: :string
+    handler { |name:, **_| "Hello, #{name}!" }
+  end
+end
+```
+
+### Network
+
+```ruby
+network = RobotLab.create_network do
+  name "my_network"
+  add_robot robot
+  router ->(args) { args.call_count.zero? ? :assistant : nil }
+end
+```
+
+### State
+
+```ruby
+state = RobotLab.create_state(
+  message: "Hello",
+  data: { user_id: "123" }
+)
+```
+
+### Tool
+
+```ruby
+tool = RobotLab::Tool.new(
+  name: "get_time",
+  description: "Get current time",
+  handler: ->(**, _) { Time.now.to_s }
+)
+```
+
+### Memory
+
+```ruby
+state.memory.remember("key", "value")
+value = state.memory.recall("key")
+```

data/docs/api/core/memory.md

@@ -0,0 +1,314 @@
+# Memory
+
+Namespaced key-value store for sharing data between robots.
+
+## Class: `RobotLab::Memory`
+
+```ruby
+memory = state.memory
+
+memory.remember("key", "value")
+value = memory.recall("key")
+```
+
+## Constants
+
+### SHARED_NAMESPACE
+
+```ruby
+Memory::SHARED_NAMESPACE  # => "SHARED"
+```
+
+Conventional namespace for cross-robot data.
+
+## Constructor
+
+```ruby
+memory = Memory.new(initial_data = {})
+```
+
+## Methods
+
+### remember
+
+```ruby
+memory.remember(key, value)
+```
+
+Store a value.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `key` | `String`, `Symbol` | Storage key |
+| `value` | `Object` | Value to store |
+
+### recall
+
+```ruby
+memory.recall(key)  # => Object | nil
+```
+
+Retrieve a value.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `key` | `String`, `Symbol` | Storage key |
+
+**Returns:** Stored value or `nil`.
+
+### exists?
+
+```ruby
+memory.exists?(key)  # => Boolean
+```
+
+Check if key exists.
+
+### forget
+
+```ruby
+memory.forget(key)  # => Object | nil
+```
+
+Remove a key, returns the value.
+
+### all
+
+```ruby
+memory.all  # => Hash
+```
+
+Get all stored data.
+
+### namespaces
+
+```ruby
+memory.namespaces  # => Array<String>
+```
+
+List all namespaces.
+
+### clear
+
+```ruby
+memory.clear
+```
+
+Clear all data in current scope.
+
+### clear_all
+
+```ruby
+memory.clear_all
+```
+
+Clear all data globally.
+
+### search
+
+```ruby
+memory.search(pattern)  # => Hash
+```
+
+Find keys matching pattern.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pattern` | `String` | Glob pattern (e.g., "user:*") |
+
+### stats
+
+```ruby
+memory.stats  # => Hash
+```
+
+Get memory statistics.
+
+**Returns:**
+
+```ruby
+{
+  total_keys: 15,
+  namespaces: ["user", "session"]
+}
+```
+
+### scoped
+
+```ruby
+scoped_memory = memory.scoped(namespace)  # => ScopedMemory
+```
+
+Create a scoped view.
+
+## ScopedMemory
+
+Scoped view with automatic key prefixing.
+
+### Methods
+
+All Memory methods are available:
+
+```ruby
+scoped = memory.scoped("user:123")
+
+scoped.remember("name", "Alice")   # Key: "user:123:name"
+scoped.recall("name")              # => "Alice"
+scoped.exists?("name")             # => true
+scoped.forget("name")
+scoped.all                         # Only "user:123:*" keys
+scoped.clear                       # Clear only this scope
+```
+
+### Nested Scopes
+
+```ruby
+user = memory.scoped("user:123")
+prefs = user.scoped("preferences")
+
+prefs.remember("theme", "dark")
+# Full key: "user:123:preferences:theme"
+```
+
+## Examples
+
+### Basic Usage
+
+```ruby
+state.memory.remember("user_name", "Alice")
+state.memory.remember("order_count", 5)
+
+name = state.memory.recall("user_name")  # => "Alice"
+count = state.memory.recall("order_count")  # => 5
+```
+
+### Storing Objects
+
+```ruby
+state.memory.remember("user", {
+  id: 123,
+  name: "Alice",
+  plan: "pro"
+})
+
+user = state.memory.recall("user")
+user[:plan]  # => "pro"
+```
+
+### Scoped Organization
+
+```ruby
+# User-specific data
+user = state.memory.scoped("user:#{user_id}")
+user.remember("last_login", Time.now)
+user.remember("preferences", { theme: "dark" })
+
+# Session-specific data
+session = state.memory.scoped("session:#{session_id}")
+session.remember("page_views", 0)
+
+# Temporary working data
+temp = state.memory.scoped("temp")
+temp.remember("intermediate_result", calculation)
+```
+
+### Cross-Robot Communication
+
+```ruby
+# In classifier robot
+state.memory.remember("SHARED:intent", "billing")
+state.memory.remember("SHARED:entities", ["order", "refund"])
+
+# In handler robot
+intent = state.memory.recall("SHARED:intent")
+entities = state.memory.recall("SHARED:entities")
+```
+
+### In Tool Handlers
+
+```ruby
+tool :update_preference do
+  handler do |key:, value:, state:, **_|
+    prefs = state.memory.scoped("preferences")
+    old_value = prefs.recall(key)
+    prefs.remember(key, value)
+
+    {
+      success: true,
+      key: key,
+      old_value: old_value,
+      new_value: value
+    }
+  end
+end
+```
+
+### Search and Iteration
+
+```ruby
+# Find all user keys
+user_data = state.memory.search("user:*")
+# => { "user:123:name" => "Alice", "user:123:email" => "..." }
+
+# Process all keys
+state.memory.all.each do |key, value|
+  puts "#{key}: #{value}"
+end
+```
+
+### Cleanup
+
+```ruby
+# Clear temporary data
+state.memory.scoped("temp").clear
+
+# Clear specific namespace
+state.memory.scoped("cache").clear
+
+# Clear everything
+state.memory.clear_all
+```
+
+### Caching Pattern
+
+```ruby
+def cached_fetch(state, key, &block)
+  cache = state.memory.scoped("cache")
+  cached = cache.recall(key)
+  return cached if cached
+
+  result = block.call
+  cache.remember(key, result)
+  result
+end
+
+# Usage
+data = cached_fetch(state, "expensive:#{id}") do
+  ExpensiveService.fetch(id)
+end
+```
+
+### Accumulating Results
+
+```ruby
+# In each robot, accumulate findings
+findings = state.memory.recall("findings") || []
+findings << { robot: robot.name, finding: new_finding }
+state.memory.remember("findings", findings)
+
+# In final robot, aggregate
+all_findings = state.memory.recall("findings")
+summary = all_findings.group_by { |f| f[:robot] }
+```
+
+## See Also
+
+- [Memory Guide](../../guides/memory.md)
+- [State](state.md)
+- [State Management Architecture](../../architecture/state-management.md)