ai-agents 0.1.1 → 0.1.3

data/docs/guides/state-persistence.md

@@ -0,0 +1,451 @@
+---
+layout: default
+title: State Persistence
+parent: Guides
+nav_order: 3
+---
+
+# State Persistence
+
+The AI Agents library provides flexible mechanisms for persisting state between agent interactions and tool executions. This guide covers context serialization, cross-session persistence, and state management patterns.
+
+## Context Serialization
+
+The library's context system is designed to be fully serializable, enabling persistence across process boundaries.
+
+### Basic Serialization
+
+Context objects can be converted to and from JSON:
+
+```ruby
+# Run an agent
+result = runner.run("Hello, my name is John")
+
+# Serialize context to JSON
+context_json = result.context.to_json
+
+# Later, deserialize and continue conversation
+restored_context = JSON.parse(context_json, symbolize_names: true)
+next_result = runner.run("What's my name?", context: restored_context)
+# => "Your name is John"
+```
+
+### Database Storage
+
+Store context in your database for long-term persistence:
+
+```ruby
+# Store context in database
+class ConversationState < ActiveRecord::Base
+  def context=(hash)
+    self.context_data = hash.to_json
+  end
+  
+  def context
+    JSON.parse(context_data, symbolize_names: true)
+  end
+end
+
+# Usage
+conversation = ConversationState.create(
+  user_id: user.id,
+  context: result.context.to_h
+)
+
+# Restore later
+restored_context = conversation.context
+continued_result = runner.run("Continue conversation", context: restored_context)
+```
+
+## Cross-Session Persistence
+
+### Session-Based State
+
+Maintain state across HTTP requests using sessions:
+
+```ruby
+class ChatController < ApplicationController
+  def send_message
+    # Retrieve context from session
+    context = session[:agent_context] || {}
+    
+    # Run agent
+    result = agent_runner.run(params[:message], context: context)
+    
+    # Store updated context in session
+    session[:agent_context] = result.context.to_h
+    
+    render json: { response: result.output }
+  end
+  
+  def reset_conversation
+    session[:agent_context] = nil
+    render json: { message: "Conversation reset" }
+  end
+end
+```
+
+### File-Based Persistence
+
+For development or simple deployments:
+
+```ruby
+class FileContextPersistence
+  def initialize(storage_path = "./contexts")
+    @storage_path = storage_path
+    FileUtils.mkdir_p(@storage_path)
+  end
+  
+  def save_context(user_id, context)
+    file_path = context_file_path(user_id)
+    File.write(file_path, context.to_json)
+  end
+  
+  def load_context(user_id)
+    file_path = context_file_path(user_id)
+    return {} unless File.exist?(file_path)
+    
+    JSON.parse(File.read(file_path), symbolize_names: true)
+  end
+  
+  def delete_context(user_id)
+    file_path = context_file_path(user_id)
+    File.delete(file_path) if File.exist?(file_path)
+  end
+  
+  private
+  
+  def context_file_path(user_id)
+    File.join(@storage_path, "#{user_id}.json")
+  end
+end
+
+# Usage
+persistence = FileContextPersistence.new
+context = persistence.load_context(user.id)
+
+result = runner.run(message, context: context)
+persistence.save_context(user.id, result.context.to_h)
+```
+
+## State Management Patterns
+
+### Context Layering
+
+Organize context data into logical layers:
+
+```ruby
+def build_layered_context(user, conversation_id)
+  {
+    # User layer - persistent across all conversations
+    user: {
+      id: user.id,
+      name: user.name,
+      preferences: user.preferences
+    },
+    
+    # Conversation layer - specific to this conversation
+    conversation: {
+      id: conversation_id,
+      started_at: Time.current,
+      topic: nil
+    },
+    
+    # Session layer - temporary data for current session
+    session: {
+      last_activity: Time.current,
+      interaction_count: 0
+    }
+  }
+end
+```
+
+### Context Cleanup
+
+Prevent context from growing indefinitely:
+
+```ruby
+class ContextCleaner
+  MAX_HISTORY_SIZE = 20
+  MAX_CONTEXT_KEYS = 50
+  
+  def self.clean_context(context)
+    cleaned = context.deep_dup
+    
+    # Limit conversation history
+    if cleaned[:conversation_history]&.size > MAX_HISTORY_SIZE
+      cleaned[:conversation_history] = cleaned[:conversation_history].last(MAX_HISTORY_SIZE)
+    end
+    
+    # Remove old temporary data
+    cleaned.delete(:temp_data) if cleaned[:temp_data]
+    
+    # Limit total context size
+    if cleaned.keys.size > MAX_CONTEXT_KEYS
+      # Keep essential keys, remove extras
+      essential_keys = [:user_id, :current_agent_name, :conversation_history]
+      extra_keys = cleaned.keys - essential_keys
+      extra_keys.first(cleaned.keys.size - MAX_CONTEXT_KEYS).each do |key|
+        cleaned.delete(key)
+      end
+    end
+    
+    cleaned
+  end
+end
+
+# Use in your service
+result = runner.run(message, context: context)
+cleaned_context = ContextCleaner.clean_context(result.context.to_h)
+save_context(user_id, cleaned_context)
+```
+
+## Tool State Management
+
+### Stateless Tool Design
+
+Tools should be stateless and rely on context for all data:
+
+```ruby
+class DatabaseTool < Agents::Tool
+  name "query_database"
+  description "Query the application database"
+  param :query, type: "string", desc: "SQL query to execute"
+  
+  def perform(tool_context, query:)
+    # Get database connection from context, not instance variables
+    db_config = tool_context.context[:database_config]
+    connection = establish_connection(db_config)
+    
+    # Execute query and return results
+    connection.execute(query)
+  end
+  
+  private
+  
+  def establish_connection(config)
+    # Create connection based on config
+    ActiveRecord::Base.establish_connection(config)
+  end
+end
+```
+
+### Tool State Persistence
+
+Store tool-specific data in context:
+
+```ruby
+class FileProcessorTool < Agents::Tool
+  name "process_file"
+  description "Process uploaded files"
+  param :file_path, type: "string", desc: "Path to file"
+  
+  def perform(tool_context, file_path:)
+    # Initialize tool state in context if needed
+    tool_context.context[:file_processor] ||= {
+      processed_files: [],
+      processing_status: {}
+    }
+    
+    # Process file
+    result = process_file(file_path)
+    
+    # Update tool state in context
+    tool_context.context[:file_processor][:processed_files] << file_path
+    tool_context.context[:file_processor][:processing_status][file_path] = result[:status]
+    
+    result
+  end
+end
+```
+
+## Advanced Persistence Patterns
+
+### Context Versioning
+
+Track context changes over time:
+
+```ruby
+class VersionedContext
+  def initialize(initial_context = {})
+    @versions = [initial_context.deep_dup]
+    @current_version = 0
+  end
+  
+  def update_context(new_context)
+    @versions << new_context.deep_dup
+    @current_version = @versions.size - 1
+  end
+  
+  def current_context
+    @versions[@current_version]
+  end
+  
+  def rollback(versions = 1)
+    target_version = [@current_version - versions, 0].max
+    @current_version = target_version
+    current_context
+  end
+  
+  def context_history
+    @versions.map.with_index do |context, index|
+      {
+        version: index,
+        timestamp: context[:updated_at],
+        agent: context[:current_agent_name]
+      }
+    end
+  end
+end
+```
+
+### Context Encryption
+
+Encrypt sensitive context data:
+
+```ruby
+class EncryptedContextStorage
+  def initialize(encryption_key)
+    @cipher = OpenSSL::Cipher.new('AES-256-CBC')
+    @key = encryption_key
+  end
+  
+  def encrypt_context(context)
+    @cipher.encrypt
+    @cipher.key = @key
+    
+    encrypted_data = @cipher.update(context.to_json)
+    encrypted_data << @cipher.final
+    
+    Base64.encode64(encrypted_data)
+  end
+  
+  def decrypt_context(encrypted_data)
+    @cipher.decrypt
+    @cipher.key = @key
+    
+    decoded_data = Base64.decode64(encrypted_data)
+    decrypted_data = @cipher.update(decoded_data)
+    decrypted_data << @cipher.final
+    
+    JSON.parse(decrypted_data, symbolize_names: true)
+  end
+end
+
+# Usage
+storage = EncryptedContextStorage.new(Rails.application.secret_key_base)
+
+# Encrypt before storing
+encrypted_context = storage.encrypt_context(result.context.to_h)
+database_record.update(encrypted_context: encrypted_context)
+
+# Decrypt when loading
+encrypted_data = database_record.encrypted_context
+context = storage.decrypt_context(encrypted_data)
+```
+
+### Distributed Context Storage
+
+For multi-server deployments using Redis:
+
+```ruby
+class RedisContextStorage
+  def initialize(redis_client = Redis.new)
+    @redis = redis_client
+  end
+  
+  def save_context(user_id, context, ttl: 1.hour)
+    key = context_key(user_id)
+    @redis.setex(key, ttl, context.to_json)
+  end
+  
+  def load_context(user_id)
+    key = context_key(user_id)
+    data = @redis.get(key)
+    return {} unless data
+    
+    JSON.parse(data, symbolize_names: true)
+  end
+  
+  def delete_context(user_id)
+    key = context_key(user_id)
+    @redis.del(key)
+  end
+  
+  def extend_ttl(user_id, ttl: 1.hour)
+    key = context_key(user_id)
+    @redis.expire(key, ttl)
+  end
+  
+  private
+  
+  def context_key(user_id)
+    "agent_context:#{user_id}"
+  end
+end
+```
+
+## Context Migration
+
+Handle context format changes across application versions:
+
+```ruby
+class ContextMigrator
+  CURRENT_VERSION = 2
+  
+  def self.migrate_context(context)
+    version = context[:_version] || 1
+    
+    case version
+    when 1
+      migrate_v1_to_v2(context)
+    when 2
+      context # Already current
+    else
+      raise "Unknown context version: #{version}"
+    end
+  end
+  
+  private
+  
+  def self.migrate_v1_to_v2(context)
+    # V1 -> V2: Rename 'current_agent' to 'current_agent_name'
+    migrated = context.deep_dup
+    
+    if migrated[:current_agent]
+      migrated[:current_agent_name] = migrated.delete(:current_agent)
+    end
+    
+    migrated[:_version] = 2
+    migrated
+  end
+end
+
+# Use in context loading
+def load_context(user_id)
+  raw_context = storage.load_context(user_id)
+  ContextMigrator.migrate_context(raw_context)
+end
+```
+
+## Best Practices
+
+### Context Size Management
+- Regularly clean up old conversation history
+- Remove temporary data after use
+- Set reasonable size limits for context values
+
+### Security Considerations
+- Encrypt sensitive data in persistent storage
+- Validate context data when loading from external sources  
+- Sanitize context data before serialization
+
+### Performance Optimization
+- Use lazy loading for large context objects
+- Cache frequently accessed context data
+- Consider context compression for large datasets
+
+### Error Handling
+- Always validate context structure after deserialization
+- Provide fallback default contexts for corrupted data
+- Log context-related errors for debugging

data/docs/guides.md

@@ -0,0 +1,18 @@
+---
+layout: default
+title: Guides
+nav_order: 3
+published: false
+has_children: true
+---
+
+# Guides
+
+Practical guides for building real-world applications with the AI Agents library. These guides provide step-by-step instructions, code examples, and best practices for common use cases.
+
+## Available Guides
+
+- **[Building Multi-Agent Systems](guides/multi-agent-systems.html)** - Design patterns and best practices for creating collaborative agent workflows
+- **[Agent-as-Tool Pattern](guides/agent-as-tool-pattern.html)** - Enable agent collaboration behind the scenes without conversation handoffs
+- **[Rails Integration](guides/rails-integration.html)** - Integrating agents with Ruby on Rails applications and ActiveRecord persistence
+- **[State Persistence](guides/state-persistence.html)** - Managing conversation state and context across sessions and processes

data/docs/index.md

@@ -0,0 +1,95 @@
+---
+layout: default
+title: Home
+nav_order: 1
+description: "AI Agents is a Ruby SDK for building multi-agent AI workflows."
+permalink: /
+---
+
+# AI Agents
+
+A Ruby SDK for building sophisticated multi-agent AI workflows.
+
+{: .fs-6 .fw-300 }
+
+[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
+[View it on GitHub](https://github.com/chatwoot/ai-agents){: .btn .fs-5 .mb-4 .mb-md-0 }
+
+---
+
+## What is AI Agents?
+
+AI Agents is a Ruby SDK that enables developers to create sophisticated multi-agent AI workflows. Build specialized AI agents that can collaborate, use tools, and seamlessly hand off conversations to solve complex tasks.
+
+### Key Features
+
+- **Multi-Agent Orchestration**: Define and manage multiple AI agents with distinct roles
+- **Seamless Handoffs**: Transfer conversations between agents without user knowledge
+- **Tool Integration**: Allow agents to use custom tools to interact with external systems
+- **Shared Context**: Maintain state and conversation history across agent interactions
+- **Thread-Safe Architecture**: Reusable agent runners that work safely across multiple threads
+- **Provider Agnostic**: Support for OpenAI, Anthropic, and Gemini
+
+## Getting Started
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ai-agents'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install ai-agents
+```
+
+### Quick Start
+
+```ruby
+require 'agents'
+
+# Configure your API keys
+Agents.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+  # config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+  # config.gemini_api_key = ENV['GEMINI_API_KEY']
+  config.default_model = 'gpt-4o-mini'
+end
+
+# Create agents
+triage = Agents::Agent.new(
+  name: "Triage",
+  instructions: "You help route customer inquiries to the right department."
+)
+
+support = Agents::Agent.new(
+  name: "Support", 
+  instructions: "You provide technical support for our products."
+)
+
+# Set up handoffs
+triage.register_handoffs(support)
+
+# Create runner and start conversation
+runner = Agents::AgentRunner.with_agents(triage, support)
+result = runner.run("I need help with a technical issue")
+
+puts result.output
+```
+
+## Next Steps
+
+- [Learn about Agents](concepts/agents.html)
+- [Understand Context](concepts/context.html)
+- [Working with Tools](concepts/tools.html)
+- [Agent Handoffs](concepts/handoffs.html)
+- [Using the Runner](concepts/runner.html)