RAAF Providers Guide

# Same code works with any provider
agent = RAAF::Agent.new(
  name: "Assistant",
  instructions: "You are helpful",
  model: model_name  # Provider auto-detected from model name
)

# OpenAI
agent = RAAF::Agent.new(model: "gpt-4o")

# Anthropic  
agent = RAAF::Agent.new(model: "claude-3-5-sonnet-20241022")

# Groq
agent = RAAF::Agent.new(model: "mixtral-8x7b-32768")

# LiteLLM with universal access
agent = RAAF::Agent.new(model: "bedrock/claude-3")

require 'raaf'

# Environment variable (recommended)
ENV['OPENAI_API_KEY'] = 'your-openai-key'

# Or explicit configuration
provider = RAAF::Models::ResponsesProvider.new(
  api_key: 'your-openai-key',
  base_url: 'https://api.openai.com/v1',  # Custom endpoint
  timeout: 30,
  max_retries: 3
)

agent = RAAF::Agent.new(
  name: "Assistant",
  instructions: "You are helpful",
  model: "gpt-4o",
  provider: provider
)

# GPT-4o models (newest, multimodal)
agent = RAAF::Agent.new(model: "gpt-4o")           # Best overall
agent = RAAF::Agent.new(model: "gpt-4o-mini")      # Fast and cost-effective

# GPT-4 models (legacy)
agent = RAAF::Agent.new(model: "gpt-4")            # High quality
agent = RAAF::Agent.new(model: "gpt-4-turbo")      # Faster GPT-4

# GPT-3.5 models (cost-effective)
agent = RAAF::Agent.new(model: "gpt-3.5-turbo")    # Balanced

# Structured outputs (native support)
schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'integer' }
  }
}

agent = RAAF::Agent.new(
  model: "gpt-4o",
  response_format: schema,
  strict: true  # Enable strict schema validation
)

# Function calling with parallel execution
agent = RAAF::Agent.new(
  model: "gpt-4o",
  parallel_tool_calls: true,
  tool_choice: "auto"  # "none", "auto", or specific tool
)

# Vision capabilities
agent = RAAF::Agent.new(
  model: "gpt-4o",
  multimodal: true
)

# Add image tool
agent.add_tool(lambda do |image_url:|
  # Process image
  { description: "Image analysis result" }
end)

# Route by complexity
def choose_openai_model(complexity_score)
  case complexity_score
  when 0..3
    "gpt-4o-mini"      # $0.15/$0.60 per 1M tokens
  when 4..7  
    "gpt-4o"           # $5/$15 per 1M tokens
  else
    "gpt-4"            # $30/$60 per 1M tokens
  end
end

agent = RAAF::Agent.new(
  model: choose_openai_model(task_complexity),
  instructions: "You are helpful"
)

# Environment variable
ENV['ANTHROPIC_API_KEY'] = 'your-anthropic-key'

# Explicit configuration
provider = RAAF::Models::AnthropicProvider.new(
  api_key: 'your-anthropic-key',
  base_url: 'https://api.anthropic.com',
  timeout: 60,  # Anthropic may be slower
  max_retries: 3
)

agent = RAAF::Agent.new(
  model: "claude-3-5-sonnet-20241022",
  provider: provider
)

# Claude 3.5 (newest generation)
agent = RAAF::Agent.new(model: "claude-3-5-sonnet-20241022")  # Best overall
agent = RAAF::Agent.new(model: "claude-3-5-haiku-20241022")   # Fast and affordable

# Claude 3 (previous generation)
agent = RAAF::Agent.new(model: "claude-3-opus-20240229")      # Most capable
agent = RAAF::Agent.new(model: "claude-3-sonnet-20240229")    # Balanced
agent = RAAF::Agent.new(model: "claude-3-haiku-20240307")     # Fast and cheap

# Large context windows
agent = RAAF::Agent.new(
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 8192,  # Up to 200K context window
  temperature: 0.7
)

# Tool use (function calling)
agent = RAAF::Agent.new(
  model: "claude-3-5-sonnet-20241022",
  tools: agent_tools,
  tool_choice: { type: "auto" }
)

# System prompts (Anthropic excels at following system instructions)
agent = RAAF::Agent.new(
  model: "claude-3-5-sonnet-20241022",
  instructions: <<~HEREDOC
    You are Claude, an AI assistant created by Anthropic.
    You are helpful, harmless, and honest.
    Think step by step and be very careful about accuracy.
  HEREDOC
)

# Claude 3 models support vision
agent = RAAF::Agent.new(
  model: "claude-3-5-sonnet-20241022",
  multimodal: true
)

agent.add_tool(lambda do |image_data:, question:|
  # Claude can analyze images
  response = provider.complete(
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: question },
          { type: 'image', source: { type: 'base64', data: image_data } }
        ]
      }
    ]
  )

  response['content'][0]['text']
end)

# Environment variable
ENV['GROQ_API_KEY'] = 'your-groq-key'

# High-speed inference configuration
provider = RAAF::Models::GroqProvider.new(
  api_key: 'your-groq-key',
  timeout: 10,  # Groq is very fast
  max_retries: 2
)

agent = RAAF::Agent.new(
  model: "mixtral-8x7b-32768",
  provider: provider
)

# Mixtral models (excellent performance)
agent = RAAF::Agent.new(model: "mixtral-8x7b-32768")      # Balanced, 32K context
agent = RAAF::Agent.new(model: "mixtral-8x22b-32768")     # Larger, more capable

# Llama models
agent = RAAF::Agent.new(model: "llama3-70b-8192")         # Very capable
agent = RAAF::Agent.new(model: "llama3-8b-8192")          # Fast and efficient

# Gemma models  
agent = RAAF::Agent.new(model: "gemma-7b-it")             # Google's model

# Groq excels at high-throughput, low-latency inference
class HighSpeedAgent
  def initialize
    @groq_provider = RAAF::Models::GroqProvider.new(
      api_key: ENV['GROQ_API_KEY'],
      timeout: 5,  # Very short timeout for speed
      connection_pool_size: 20  # High concurrency
    )
  end

  def create_fast_agent(task_type)
    model = case task_type
    when :simple_qa
      "llama3-8b-8192"      # Fastest for simple tasks
    when :complex_reasoning
      "mixtral-8x7b-32768"  # Better reasoning
    when :coding
      "mixtral-8x22b-32768" # Best for code
    end

    RAAF::Agent.new(
      model: model,
      provider: @groq_provider,
      temperature: 0.1,  # Lower for consistency
      max_tokens: 1000   # Shorter for speed
    )
  end
end

# Together.ai is supported through LiteLLM
agent = RAAF::Agent.new(
  model: "together_ai/meta-llama/Llama-2-70b-chat-hf"
)

# Or configure directly
ENV['TOGETHER_API_KEY'] = 'your-together-key'
agent = RAAF::Agent.new(
  model: "meta-llama/Llama-2-70b-chat-hf",
  provider_config: {
    api_base: 'https://api.together.xyz/v1'
  }
)

# Meta Llama models
agent = RAAF::Agent.new(model: "meta-llama/Llama-2-70b-chat-hf")
agent = RAAF::Agent.new(model: "meta-llama/Llama-2-13b-chat-hf")

# Mistral models
agent = RAAF::Agent.new(model: "mistralai/Mixtral-8x7B-Instruct-v0.1")
agent = RAAF::Agent.new(model: "mistralai/Mistral-7B-Instruct-v0.1")

# Code-specific models
agent = RAAF::Agent.new(model: "codellama/CodeLlama-34b-Instruct-hf")
agent = RAAF::Agent.new(model: "WizardLM/WizardCoder-Python-34B-V1.0")

# Environment variable
ENV['COHERE_API_KEY'] = 'your-cohere-key'

# Explicit configuration
# Cohere is supported through standard configuration
ENV['COHERE_API_KEY'] = 'your-cohere-key'

agent = RAAF::Agent.new(
  model: "command-r-plus"
)

# Command models (latest generation)
agent = RAAF::Agent.new(model: "command-r-plus")    # Most capable
agent = RAAF::Agent.new(model: "command-r")         # Balanced performance
agent = RAAF::Agent.new(model: "command-light")     # Fast and efficient

# Specialized models
agent = RAAF::Agent.new(model: "command-nightly")   # Latest experimental features

# Text classification
agent = RAAF::Agent.new(
  model: "command-r",
  task_type: "classify",
  categories: ["positive", "negative", "neutral"]
)

# Retrieval augmented generation
agent = RAAF::Agent.new(
  model: "command-r-plus",
  retrieval_enabled: true,
  max_tokens: 4096
)

# LiteLLM provides access to 100+ providers
require 'raaf'

provider = RAAF::Models::LiteLLMProvider.new(
  # Automatically routes based on model name
)

# Use any model from any provider
agent = RAAF::Agent.new(
  model: "azure/gpt-4o",      # Azure OpenAI
  provider: provider
)

agent = RAAF::Agent.new(
  model: "bedrock/claude-3",  # AWS Bedrock
  provider: provider
)

agent = RAAF::Agent.new(
  model: "vertex_ai/gemini-pro", # Google Vertex AI
  provider: provider
)

class UniversalAI
  def initialize
    @litellm = RAAF::Models::LiteLLMProvider.new
  end

  def create_agent_for_provider(provider_name, task_type)
    model = case [provider_name, task_type]
    when ['azure', 'reasoning']
      "azure/gpt-4o"
    when ['aws', 'conversation']
      "bedrock/claude-3-sonnet"
    when ['google', 'analysis']
      "vertex_ai/gemini-pro"
    when ['huggingface', 'coding']
      "huggingface/codellama/CodeLlama-34b-Instruct-hf"
    else
      "gpt-4o-mini"  # Default fallback
    end

    RAAF::Agent.new(
      model: model,
      provider: @litellm,
      instructions: "You are helpful"
    )
  end
end

class CostOptimizedRouting
  def initialize
    @providers = {
      openai: RAAF::Models::ResponsesProvider.new,
      anthropic: RAAF::Models::AnthropicProvider.new,
      groq: RAAF::Models::GroqProvider.new,
      litellm: RAAF::Models::LiteLLMProvider.new
    }

    # Cost per 1M tokens (input/output)
    @costs = {
      'gpt-4o-mini' => [0.15, 0.60],
      'claude-3-haiku' => [0.25, 1.25],
      'mixtral-8x7b-32768' => [0.27, 0.27],  # Groq
      'command-light' => [0.15, 0.15]  # Cohere
    }
  end

  def route_by_cost(task_complexity, budget_cents_per_1k_tokens)
    suitable_models = @costs.select do |model, (input_cost, output_cost)|
      avg_cost = (input_cost + output_cost) / 2 / 1000  # Per 1K tokens
      avg_cost <= budget_cents_per_1k_tokens
    end

    # Choose best model within budget
    if task_complexity > 8 && suitable_models.include?('gpt-4o')
      ['gpt-4o', @providers[:openai]]
    elsif task_complexity > 5 && suitable_models.include?('claude-3-sonnet')
      ['claude-3-sonnet', @providers[:anthropic]]
    elsif suitable_models.include?('mixtral-8x7b-32768')
      ['mixtral-8x7b-32768', @providers[:groq]]
    else
      ['command-light', @providers[:litellm]]  # Cost-effective fallback
    end
  end
end

class LoadBalancedProvider
  def initialize
    @providers = [
      RAAF::Models::ResponsesProvider.new,
      RAAF::Models::AnthropicProvider.new,
      RAAF::Models::GroqProvider.new
    ]
    @current_index = 0
    @mutex = Mutex.new
  end

  def create_agent(model_type)
    provider = next_provider
    model = select_model_for_provider(provider, model_type)

    RAAF::Agent.new(
      model: model,
      provider: provider,
      instructions: "You are helpful"
    )
  end

  private

  def next_provider
    @mutex.synchronize do
      provider = @providers[@current_index]
      @current_index = (@current_index + 1) % @providers.length
      provider
    end
  end

  def select_model_for_provider(provider, model_type)
    case [provider.class.name, model_type]
    when ['ResponsesProvider', :fast]
      'gpt-4o-mini'
    when ['ResponsesProvider', :quality]
      'gpt-4o'
    when ['AnthropicProvider', :fast]
      'claude-3-haiku'
    when ['AnthropicProvider', :quality]
      'claude-3-5-sonnet'
    when ['GroqProvider', :fast]
      'llama3-8b-8192'
    when ['GroqProvider', :quality]
      'mixtral-8x7b-32768'
    end
  end
end

class ResilientProvider
  def initialize
    @primary_provider = RAAF::Models::ResponsesProvider.new
    @secondary_provider = RAAF::Models::AnthropicProvider.new
    @fallback_provider = RAAF::Models::LiteLLMProvider.new

    @circuit_breakers = {}
  end

  def create_resilient_agent(model_preference)
    providers_to_try = [
      [@primary_provider, select_primary_model(model_preference)],
      [@secondary_provider, select_secondary_model(model_preference)],
      [@fallback_provider, select_fallback_model(model_preference)]
    ]

    providers_to_try.each do |provider, model|
      next if circuit_breaker_open?(provider)

      begin
        agent = RAAF::Agent.new(
          model: model,
          provider: provider,
          instructions: "You are helpful"
        )

        # Test the agent
        test_result = test_agent(agent)
        if test_result[:success]
          reset_circuit_breaker(provider)
          return agent
        end

      rescue => e
        record_failure(provider, e)
        open_circuit_breaker(provider) if should_open_circuit?(provider)
        next
      end
    end

    raise "All providers failed"
  end

  private

  def circuit_breaker_open?(provider)
    breaker = @circuit_breakers[provider.class.name]
    breaker && breaker[:open] && (Time.now - breaker[:opened_at]) < 300  # 5 minutes
  end

  def test_agent(agent)
    runner = RAAF::Runner.new(agent: agent)
    result = runner.run("Say 'OK'")
    { success: result.success? }
  rescue
    { success: false }
  end
end

class PooledProviderManager
  def initialize
    @openai_pool = ConnectionPool.new(size: 10, timeout: 5) do
      RAAF::Models::ResponsesProvider.new(
        api_key: ENV['OPENAI_API_KEY'],
        timeout: 30
      )
    end

    @anthropic_pool = ConnectionPool.new(size: 5, timeout: 5) do
      RAAF::Models::AnthropicProvider.new(
        api_key: ENV['ANTHROPIC_API_KEY'],
        timeout: 60
      )
    end
  end

  def with_openai_provider(&block)
    @openai_pool.with(&block)
  end

  def with_anthropic_provider(&block)
    @anthropic_pool.with(&block)
  end

  def create_pooled_agent(provider_type, model)
    case provider_type
    when :openai
      with_openai_provider do |provider|
        RAAF::Agent.new(model: model, provider: provider)
      end
    when :anthropic
      with_anthropic_provider do |provider|
        RAAF::Agent.new(model: model, provider: provider)
      end
    end
  end
end

class CachedProviderResponses
  def initialize(provider)
    @provider = provider
    @cache = ActiveSupport::Cache::MemoryStore.new(size: 100.megabytes)
  end

  def complete(messages, options = {})
    # Create cache key from messages and options
    cache_key = generate_cache_key(messages, options)

    # Try cache first
    cached_response = @cache.read(cache_key)
    return cached_response if cached_response

    # Call actual provider
    response = @provider.complete(messages, options)

    # Cache successful responses
    if response[:success]
      @cache.write(cache_key, response, expires_in: 1.hour)
    end

    response
  end

  private

  def generate_cache_key(messages, options)
    content = messages.map { |m| m[:content] }.join('|')
    options_str = options.to_json
    Digest::MD5.hexdigest("#{content}|#{options_str}")
  end
end

# Usage
cached_openai = CachedProviderResponses.new(
  RAAF::Models::ResponsesProvider.new
)

agent = RAAF::Agent.new(
  model: "gpt-4o",
  provider: cached_openai
)

# Use structured outputs for consistent data
agent = RAAF::Agent.new(
  model: "gpt-4o",
  response_format: your_schema,
  strict: true  # Enables strict mode
)

# Batch requests for efficiency
class OpenAIBatcher
  def initialize
    @provider = RAAF::Models::ResponsesProvider.new
    @batch_requests = []
  end

  def add_request(messages, options = {})
    @batch_requests << { messages: messages, options: options }
  end

  def execute_batch
    # OpenAI batch API for cost savings
    @provider.batch_complete(@batch_requests)
  end
end

# Use system prompts effectively
agent = RAAF::Agent.new(
  model: "claude-3-5-sonnet-20241022",
  instructions: <<~HEREDOC
    You are an expert assistant.

    Guidelines:

    - Think step by step
    - Be precise and accurate
    - Ask clarifying questions when needed
  HEREDOC
)

# Leverage large context windows
agent = RAAF::Agent.new(
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 8192,  # Can handle up to 200K input tokens
  instructions: "Analyze this large document..."
)

# Optimize for speed
agent = RAAF::Agent.new(
  model: "mixtral-8x7b-32768",
  temperature: 0.1,  # Lower for consistency
  max_tokens: 1000,  # Shorter responses for speed
  top_p: 0.9
)

# Use for high-throughput scenarios
class HighThroughputGroq
  def initialize
    @provider = RAAF::Models::GroqProvider.new(
      timeout: 5,  # Short timeout
      max_retries: 1  # Fail fast
    )
  end

  def process_batch(tasks)
    futures = tasks.map do |task|
      Concurrent::Future.execute do
        agent = RAAF::Agent.new(
          model: "llama3-8b-8192",
          provider: @provider
        )

        runner = RAAF::Runner.new(agent: agent)
        runner.run(task)
      end
    end

    futures.map(&:value)
  end
end

RSpec.describe 'Multi-Provider Agent System' do
  let(:providers) do
    {
      openai: RAAF::Models::ResponsesProvider.new,
      anthropic: RAAF::Models::AnthropicProvider.new,
      groq: RAAF::Models::GroqProvider.new
    }
  end

  it 'works with all configured providers' do
    providers.each do |name, provider|
      agent = RAAF::Agent.new(
        model: select_test_model(name),
        provider: provider,
        instructions: "Say 'Hello from #{name}'"
      )

      runner = RAAF::Runner.new(agent: agent)
      result = runner.run("Please respond")

      expect(result.success?).to be true
      expect(result.messages.last[:content]).to include(name.to_s)
    end
  end

  def select_test_model(provider_name)
    case provider_name
    when :openai
      'gpt-4o-mini'
    when :anthropic
      'claude-3-haiku'
    when :groq
      'llama3-8b-8192'
    end
  end
end

class MockProvider
  def initialize(responses = {})
    @responses = responses
    @call_count = 0
  end

  def complete(messages, options = {})
    @call_count += 1

    # Return predefined response or default
    response_content = @responses[@call_count] || "Mock response"

    {
      success: true,
      choices: [
        {
          message: {
            role: 'assistant',
            content: response_content
          }
        }
      ],
      usage: {
        prompt_tokens: 10,
        completion_tokens: 5,
        total_tokens: 15
      }
    }
  end
end

# In tests
RSpec.describe 'Agent Behavior' do
  let(:mock_provider) do
    MockProvider.new(
      1 => "First response",
      2 => "Second response"
    )
  end

  let(:agent) do
    RAAF::Agent.new(
      model: "mock-model",
      provider: mock_provider
    )
  end

  it 'uses mock responses' do
    runner = RAAF::Runner.new(agent: agent)

    result1 = runner.run("First message")
    expect(result1.messages.last[:content]).to eq("First response")

    result2 = runner.run("Second message")
    expect(result2.messages.last[:content]).to eq("Second response")
  end
end