ai-agents 0.1.2 → 0.2.0

data/docs/_config.yml

@@ -0,0 +1,53 @@
+title: AI Agents
+description: A Ruby SDK for building multi-agent AI workflows
+baseurl: ""
+url: ""
+
+# Theme
+theme: just-the-docs
+
+# Color scheme
+color_scheme: ruby
+
+# Search
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
+
+# Navigation
+nav_sort: case_insensitive
+nav_external_links:
+  - title: GitHub
+    url: https://github.com/chatwoot/ai-agents
+
+# Footer
+footer_content: "Copyright © 2025 Chatwoot Inc."
+
+# Plugins
+plugins:
+  - jekyll-remote-theme
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# Markdown
+markdown: kramdown
+highlighter: rouge
+
+# Exclude from processing
+exclude:
+  - .sass-cache/
+  - .jekyll-cache/
+  - gemfiles/
+  - Gemfile
+  - Gemfile.lock
+  - node_modules/
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/

data/docs/_sass/color_schemes/ruby.scss

@@ -0,0 +1,72 @@
+// Ruby red color scheme for AI Agents documentation
+// Inspired by Ruby's signature red color
+
+// Define red color variables
+$red-000: #fff5f5;
+$red-100: #fed7d7;
+$red-200: #feb2b2;
+$red-300: #fc8181;
+$red-400: #e53e3e;
+$red-500: #d30001; // Primary Ruby red
+$red-600: #b30001;
+$red-700: #930001;
+$red-800: #730001;
+$red-900: #530001;
+
+// Grey colors with subtle reddish tint for text and backgrounds
+$grey-dk-000: #959396;
+$grey-dk-100: #5c5962;
+$grey-dk-200: #44434d;
+$grey-dk-250: #302d36;
+$grey-dk-300: #27262b;
+
+$grey-lt-000: #faf6f6; // Very slightly reddish background
+$grey-lt-100: #f7f2f2; // Very subtle reddish tint
+$grey-lt-200: #f4efef; // Very subtle reddish tint
+$grey-lt-300: #f0e8e8; // Very subtle reddish tint
+
+// Override theme variables
+$link-color: $red-500;
+$btn-primary-color: $red-500;
+$base-button-color: #f7f7f7;
+
+// Navigation
+$nav-child-link-color: $grey-dk-100;
+$nav-list-item-color: $grey-dk-100;
+$nav-list-item-active-color: $red-500;
+
+// Sidebar background
+$sidebar-color: $grey-lt-100; // Subtle reddish tint for sidebar
+
+// Search
+$search-active-color: $red-500;
+$search-background-color: $grey-lt-000;
+
+// Code
+$code-background-color: $grey-lt-000;
+$code-border-color: $grey-lt-300;
+
+// Tables
+$table-background-color: $grey-lt-000;
+$border-color: $grey-lt-300;
+
+// Buttons
+$btn-outline-color: $red-500;
+
+// Focus states
+$focus-color: $red-400;
+
+// Feedback states
+$feedback-color: $grey-lt-300;
+
+// Headings
+$h1-color: $grey-dk-300;
+$h2-color: $grey-dk-300;
+$h3-color: $grey-dk-200;
+$h4-color: $grey-dk-200;
+$h5-color: $grey-dk-200;
+$h6-color: $grey-dk-200;
+
+// Body text
+$body-text-color: $grey-dk-100;
+$body-heading-color: $grey-dk-300;

data/docs/_sass/custom/custom.scss

@@ -0,0 +1,93 @@
+// Self-hosted Inter Variable font
+@font-face {
+  font-family: "Inter";
+  src: url("/assets/fonts/InterVariable.woff2") format("woff2-variations");
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+  font-named-instance: "Regular";
+}
+
+// Override font variables
+$body-font-family:
+  "Inter",
+  -apple-system,
+  BlinkMacSystemFont,
+  "Segoe UI",
+  Helvetica,
+  Arial,
+  sans-serif;
+$mono-font-family: "SF Mono", Monaco, Inconsolata, "Roboto Mono", monospace;
+
+// Apply Inter to all text elements
+body {
+  font-family: $body-font-family;
+  font-feature-settings:
+    "cv02", "cv03", "cv04", "cv11"; // Display-like features
+}
+
+// Ensure headings use Inter as well
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: $body-font-family;
+}
+
+// Custom logo styling
+.site-logo {
+  padding: 1rem;
+  border-bottom: 1px solid var(--border-color);
+
+  .site-logo-link {
+    display: flex;
+    align-items: center;
+    text-decoration: none;
+    color: inherit;
+
+    &:hover {
+      text-decoration: none;
+    }
+  }
+
+  .site-logo-image {
+    width: 32px;
+    height: 32px;
+    margin-right: 0.75rem;
+    border-radius: 6px;
+  }
+
+  .site-title {
+    font-weight: 600;
+    font-size: 1.1rem;
+    color: var(--body-heading-color);
+  }
+}
+
+// Note callout styling
+.note {
+  padding: 1rem;
+  margin: 1rem 0;
+  background-color: #faf6f6;
+  border: 1px solid #f0e8e8;
+  border-left: 4px solid #d30001;
+  border-radius: 6px;
+  position: relative;
+
+  &::before {
+    content: "NOTE";
+    font-weight: 600;
+    font-size: 0.75rem;
+    color: #d30001;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    display: block;
+    margin-bottom: 0.5rem;
+  }
+
+  p:last-child {
+    margin-bottom: 0;
+  }
+}

data/docs/architecture.md

@@ -0,0 +1,353 @@
+---
+layout: default
+title: Architecture
+nav_order: 4
+published: false
+---
+
+# Architecture
+
+The AI Agents library is designed around key principles of immutability, thread safety, and separation of concerns. This architecture enables scalable multi-agent systems that can handle concurrent conversations while maintaining state consistency.
+
+## Core Architecture Principles
+
+### Immutability by Design
+- **Agents are immutable** once created, preventing configuration drift
+- **Context is deep-copied** for each execution to prevent cross-contamination
+- **Registry is frozen** after initialization to prevent runtime modifications
+
+### Thread Safety
+- **No shared mutable state** between concurrent executions
+- **Context isolation** through deep copying and closure capture
+- **Stateless tool design** with context injection via parameters
+
+### Separation of Concerns
+- **Agent definition** (configuration) vs **Agent execution** (runtime)
+- **Tool functionality** vs **Tool context** (execution state)
+- **Conversation orchestration** vs **LLM communication**
+
+## Component Architecture
+
+### Two-Tier Execution Model
+
+The library uses a two-tier architecture separating long-lived configuration from short-lived execution:
+
+```
+┌─────────────────┐    ┌─────────────────┐
+│   AgentRunner   │    │     Runner      │
+│   (Long-lived)  │────▶│  (Per-request)  │
+│                 │    │                 │
+│ • Agent Registry│    │ • Execution     │
+│ • Entry Point   │    │ • Context Mgmt  │
+│ • Thread Safety │    │ • Handoff Logic │
+└─────────────────┘    └─────────────────┘
+```
+
+**AgentRunner** (Thread-Safe Manager):
+- Created once, reused for multiple conversations
+- Maintains immutable agent registry
+- Determines conversation continuity
+- Thread-safe for concurrent use
+
+**Runner** (Execution Engine):
+- Created per conversation turn
+- Handles LLM communication and tool execution
+- Manages context state during execution
+- Stateless and garbage-collected after use
+
+### Context Management Architecture
+
+Context flows through multiple abstraction layers:
+
+```
+┌─────────────────┐
+│   User Context  │ (Serializable across sessions)
+│                 │
+├─────────────────┤
+│   RunContext    │ (Execution isolation)
+│                 │
+├─────────────────┤
+│   ToolContext   │ (Tool-specific state)
+│                 │
+└─────────────────┘
+```
+
+**User Context**: Serializable hash for persistence
+**RunContext**: Execution wrapper with usage tracking
+**ToolContext**: Tool-specific view with retry metadata
+
+## Handoff Architecture
+
+### Tool-Based Handoff System
+
+Handoffs are implemented as specialized tools rather than instruction-parsing:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Triage Agent  │    │  HandoffTool    │    │  Billing Agent  │
+│                 │    │                 │    │                 │
+│ • Instructions  │────▶│ • Target Agent  │────▶│ • Instructions  │
+│ • Handoff List  │    │ • Schema        │    │ • Specialized   │
+│ • General Role  │    │ • Execution     │    │ • Tools         │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+**Benefits of Tool-Based Handoffs**:
+- **Reliable invocation**: LLMs consistently use tools when available
+- **Clear semantics**: Tool schema explicitly defines handoff criteria
+- **No text parsing**: Eliminates need to parse free-form responses
+- **Provider agnostic**: Works consistently across OpenAI, Anthropic, etc.
+
+### First-Call-Wins Handoff Resolution
+
+To prevent infinite handoff loops, the system implements first-call-wins semantics:
+
+```
+LLM Response with Multiple Handoffs:
+┌─────────────────────────────────────┐
+│ Call 1: handoff_to_support()       │ ✓ Processed
+│ Call 2: handoff_to_billing()       │ ✗ Ignored
+│ Call 3: handoff_to_support()       │ ✗ Ignored
+└─────────────────────────────────────┘
+Result: Transfer to Support Agent only
+```
+
+This mirrors OpenAI's SDK behavior and prevents conflicting handoff states.
+
+## Thread Safety Implementation
+
+### Context Isolation Pattern
+
+Each execution receives an isolated context copy:
+
+```ruby
+# Thread-safe execution flow
+def run(input, context: {})
+  # 1. Deep copy context for isolation
+  context_copy = deep_copy_context(context)
+
+  # 2. Create execution wrapper
+  run_context = RunContext.new(context_copy)
+
+  # 3. Execute with isolated state
+  result = execute_with_context(run_context)
+
+  # 4. Return serializable result
+  return result
+end
+```
+
+### Tool Wrapper Pattern
+
+Tools remain stateless through the wrapper pattern:
+
+```ruby
+# Tool Definition (Stateless)
+class WeatherTool < Agents::Tool
+  def perform(tool_context, city:)
+    api_key = tool_context.context[:weather_api_key]
+    WeatherAPI.get(city, api_key)
+  end
+end
+
+# Runtime Wrapping (Context Injection)
+wrapped_tool = ToolWrapper.new(weather_tool, context_wrapper)
+```
+
+The wrapper captures context in its closure, injecting it during execution without modifying the tool instance.
+
+## Chat Architecture
+
+### Extended Chat System
+
+The library extends RubyLLM::Chat with handoff detection:
+
+```
+┌─────────────────┐    ┌─────────────────┐
+│   Agents::Chat  │    │  RubyLLM::Chat  │
+│   (Extended)    │────▶│   (Base)        │
+│                 │    │                 │
+│ • Handoff Detect│    │ • LLM Comm      │
+│ • Tool Classify │    │ • Tool Execution│
+│ • First-Call-Wins│   │ • Message Mgmt  │
+└─────────────────┘    └─────────────────┘
+```
+
+**Handoff Detection Flow**:
+1. Classify tool calls into handoff vs regular tools
+2. Execute first handoff only (first-call-wins)
+3. Return HandoffResponse to signal agent switch
+4. Execute regular tools normally with continuation
+
+### Conversation Continuity
+
+The system maintains conversation state through message attribution:
+
+```ruby
+# Messages include agent attribution
+{
+  role: :assistant,
+  content: "I can help with billing",
+  agent_name: "Billing"  # Enables conversation continuity
+}
+```
+
+AgentRunner uses this attribution to determine conversation ownership when resuming.
+
+## Provider Abstraction
+
+### RubyLLM Integration
+
+The library builds on RubyLLM for provider abstraction:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   AI Agents     │    │    RubyLLM      │    │   Providers     │
+│                 │    │                 │    │                 │
+│ • Multi-Agent   │────▶│ • Unified API   │────▶│ • OpenAI        │
+│ • Handoffs      │    │ • Tool Calling  │    │ • Anthropic     │
+│ • Context Mgmt  │    │ • Streaming     │    │ • Gemini        │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+This abstraction allows switching between providers without changing agent logic.
+
+## State Management
+
+### Context Serialization
+
+The entire conversation state is serializable:
+
+```ruby
+# Serialize context for persistence
+context_json = result.context.to_json
+
+# Restore and continue conversation
+restored_context = JSON.parse(context_json, symbolize_names: true)
+next_result = runner.run("Continue conversation", context: restored_context)
+```
+
+**Serialization includes**:
+- Conversation history with agent attribution
+- Current agent state
+- Tool-specific state
+- User-defined context data
+
+### State Persistence Patterns
+
+The library supports multiple persistence patterns:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   In-Memory     │    │   File-Based    │    │   Database      │
+│                 │    │                 │    │                 │
+│ • Development   │    │ • Simple Deploy │    │ • Production    │
+│ • Testing       │    │ • Single Server │    │ • Multi-Server  │
+│ • Rapid Iteration│   │ • File Storage  │    │ • ActiveRecord  │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+All patterns use the same serialization format for consistency.
+
+## Performance Characteristics
+
+### Memory Management
+
+- **Immutable objects** are shared safely across threads
+- **Context copies** are garbage-collected after execution
+- **Tool instances** are reused without state accumulation
+
+### Execution Efficiency
+
+- **Minimal object creation** during execution
+- **Direct LLM communication** without additional abstractions
+- **Efficient handoff detection** through tool classification
+
+### Scalability
+
+- **Thread-safe design** enables horizontal scaling
+- **Stateless execution** supports load balancing
+- **Serializable state** enables process migration
+
+## Error Handling Architecture
+
+### Graceful Degradation
+
+The system handles errors at multiple levels:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Agent Level   │    │   Tool Level    │    │   LLM Level     │
+│                 │    │                 │    │                 │
+│ • Handoff Fails │    │ • Tool Errors   │    │ • API Errors    │
+│ • Max Turns     │    │ • Retry Logic   │    │ • Rate Limits   │
+│ • State Errors  │    │ • Fallback      │    │ • Timeouts      │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+### Error Recovery
+
+- **Context preservation** even during errors
+- **Partial execution results** for debugging
+- **Conversation continuity** after error resolution
+
+## Extension Points
+
+### Custom Tools
+
+The tool system is fully extensible:
+
+```ruby
+class CustomTool < Agents::Tool
+  name "custom_action"
+  description "Perform custom business logic"
+  param :input, type: "string"
+
+  def perform(tool_context, input:)
+    # Access context for state
+    user_id = tool_context.context[:user_id]
+
+    # Perform custom logic
+    result = BusinessLogic.process(input, user_id)
+
+    # Update shared state
+    tool_context.state[:last_action] = result
+
+    result
+  end
+end
+```
+
+### Custom Providers
+
+While built on RubyLLM, the architecture supports custom providers:
+
+```ruby
+# Custom provider integration
+class CustomProvider < RubyLLM::Provider
+  def complete(messages, **options)
+    # Custom LLM integration
+  end
+end
+
+# Use with agents
+agent = Agents::Agent.new(
+  name: "Assistant",
+  model: CustomProvider.new.model("custom-model")
+)
+```
+
+### Debug Hooks
+
+The system provides hooks for debugging and tracing:
+
+```ruby
+# Enable debug logging
+ENV["RUBYLLM_DEBUG"] = "true"
+
+# Custom callbacks
+chat.on(:new_message) { puts "Sending to LLM..." }
+chat.on(:end_message) { |response| puts "Received: #{response.content}" }
+```
+
+This architecture provides a robust foundation for building production-ready multi-agent systems while maintaining simplicity and developer productivity.