ruby_llm 0.1.0.pre38 → 0.1.0.pre39

data/docs/guides/error-handling.md

@@ -1,301 +0,0 @@
----
-layout: default
-title: Error Handling
-parent: Guides
-nav_order: 8
-permalink: /guides/error-handling
----
-
-# Error Handling
-
-Proper error handling is crucial when working with AI services. RubyLLM provides a comprehensive error handling system that helps you build robust applications.
-
-## Error Hierarchy
-
-RubyLLM uses a structured error hierarchy:
-
-```ruby
-RubyLLM::Error                    # Base error class
-    RubyLLM::BadRequestError      # Invalid request parameters (400)
-    RubyLLM::UnauthorizedError    # API key issues (401)
-    RubyLLM::PaymentRequiredError # Billing issues (402)
-    RubyLLM::RateLimitError       # Rate limit exceeded (429)
-    RubyLLM::ServerError          # Provider server error (500)
-    RubyLLM::ServiceUnavailableError # Service unavailable (503)
-    RubyLLM::ModelNotFoundError   # Invalid model ID
-    RubyLLM::InvalidRoleError     # Invalid message role
-```
-
-## Basic Error Handling
-
-Wrap your AI interactions in `begin/rescue` blocks:
-
-```ruby
-begin
-  chat = RubyLLM.chat
-  response = chat.ask "What's the capital of France?"
-  puts response.content
-rescue RubyLLM::Error => e
-  puts "AI interaction failed: #{e.message}"
-end
-```
-
-## Handling Specific Errors
-
-Target specific error types for more precise handling:
-
-```ruby
-begin
-  chat = RubyLLM.chat
-  response = chat.ask "Generate a detailed analysis"
-rescue RubyLLM::UnauthorizedError
-  puts "Please check your API credentials"
-rescue RubyLLM::PaymentRequiredError
-  puts "Payment required - please check your account balance"
-rescue RubyLLM::RateLimitError
-  puts "Rate limit exceeded - please try again later"
-rescue RubyLLM::ServiceUnavailableError
-  puts "Service temporarily unavailable - please try again later"
-rescue RubyLLM::BadRequestError => e
-  puts "Bad request: #{e.message}"
-rescue RubyLLM::Error => e
-  puts "Other error: #{e.message}"
-end
-```
-
-## API Response Details
-
-The `Error` class contains the original response, allowing for detailed error inspection:
-
-```ruby
-begin
-  chat = RubyLLM.chat
-  chat.ask "Some question"
-rescue RubyLLM::Error => e
-  puts "Error: #{e.message}"
-  puts "Status: #{e.response.status}"
-  puts "Body: #{e.response.body}"
-end
-```
-
-## Error Handling with Streaming
-
-When using streaming, errors can occur during the stream:
-
-```ruby
-begin
-  chat = RubyLLM.chat
-  chat.ask "Generate a long response" do |chunk|
-    print chunk.content
-  end
-rescue RubyLLM::Error => e
-  puts "\nStreaming error: #{e.message}"
-end
-```
-
-## Handling Tool Errors
-
-When using tools, errors can be handled within the tool or in the calling code:
-
-```ruby
-# Error handling within tools
-class Calculator < RubyLLM::Tool
-  description "Performs calculations"
-
-  param :expression,
-    type: :string,
-    desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
-  rescue StandardError => e
-    # Return error as structured data
-    { error: "Calculation error: #{e.message}" }
-  end
-end
-
-# Error handling when using tools
-begin
-  chat = RubyLLM.chat.with_tool(Calculator)
-  chat.ask "What's 1/0?"
-rescue RubyLLM::Error => e
-  puts "Error using tools: #{e.message}"
-end
-```
-
-## Automatic Retries
-
-RubyLLM automatically retries on certain transient errors:
-
-```ruby
-# Configure retry behavior
-RubyLLM.configure do |config|
-  config.max_retries = 5 # Maximum number of retries
-end
-```
-
-The following errors trigger automatic retries:
-- Network timeouts
-- Connection failures
-- Rate limit errors (429)
-- Server errors (500, 502, 503, 504)
-
-## Provider-Specific Errors
-
-Each provider may return slightly different error messages. RubyLLM normalizes these into standard error types, but the original error details are preserved:
-
-```ruby
-begin
-  chat = RubyLLM.chat
-  chat.ask "Some question"
-rescue RubyLLM::Error => e
-  if e.response.body.include?("organization_quota_exceeded")
-    puts "Your organization's quota has been exceeded"
-  else
-    puts "Error: #{e.message}"
-  end
-end
-```
-
-## Error Handling in Rails
-
-When using RubyLLM in a Rails application, you can handle errors at different levels:
-
-### Controller Level
-
-```ruby
-class ChatController < ApplicationController
-  rescue_from RubyLLM::Error, with: :handle_ai_error
-
-  def create
-    @chat = Chat.create!(chat_params)
-    @chat.ask(params[:message])
-    redirect_to @chat
-  end
-
-  private
-
-  def handle_ai_error(exception)
-    flash[:error] = "AI service error: #{exception.message}"
-    redirect_to chats_path
-  end
-end
-```
-
-### Background Job Level
-
-```ruby
-class AiChatJob < ApplicationJob
-  retry_on RubyLLM::RateLimitError, RubyLLM::ServiceUnavailableError,
-           wait: :exponentially_longer, attempts: 5
-
-  discard_on RubyLLM::UnauthorizedError, RubyLLM::BadRequestError
-
-  def perform(chat_id, message)
-    chat = Chat.find(chat_id)
-    chat.ask(message)
-  rescue RubyLLM::Error => e
-    # Log error and notify user
-    ErrorNotifier.notify(chat.user, "AI chat error: #{e.message}")
-  end
-end
-```
-
-## Monitoring Errors
-
-For production applications, monitor AI service errors:
-
-```ruby
-# Custom error handler
-module AiErrorMonitoring
-  def self.track_error(error, context = {})
-    # Record error in your monitoring system
-    Sentry.capture_exception(error, extra: context)
-
-    # Log details
-    Rails.logger.error "[AI Error] #{error.class}: #{error.message}"
-    Rails.logger.error "Context: #{context.inspect}"
-
-    # Return or re-raise as needed
-    error
-  end
-end
-
-# Usage
-begin
-  chat.ask "Some question"
-rescue RubyLLM::Error => e
-  AiErrorMonitoring.track_error(e, {
-    model: chat.model.id,
-    tokens: chat.messages.sum(&:input_tokens)
-  })
-
-  # Show appropriate message to user
-  flash[:error] = "Sorry, we encountered an issue with our AI service"
-end
-```
-
-## Graceful Degradation
-
-For critical applications, implement fallback strategies:
-
-```ruby
-def get_ai_response(question, fallback_message = nil)
-  begin
-    chat = RubyLLM.chat
-    response = chat.ask(question)
-    response.content
-  rescue RubyLLM::Error => e
-    Rails.logger.error "AI error: #{e.message}"
-
-    # Fallback to alternative model
-    begin
-      fallback_chat = RubyLLM.chat(model: 'gpt-3.5-turbo')
-      fallback_response = fallback_chat.ask(question)
-      fallback_response.content
-    rescue RubyLLM::Error => e2
-      Rails.logger.error "Fallback AI error: #{e2.message}"
-      fallback_message || "Sorry, our AI service is currently unavailable"
-    end
-  end
-end
-```
-
-## Best Practices
-
-1. **Always wrap AI calls in error handling** - Don't assume AI services will always be available
-2. **Implement timeouts** - Configure appropriate request timeouts
-3. **Use background jobs** - Process AI requests asynchronously when possible
-4. **Set up monitoring** - Track error rates and response times
-5. **Have fallback content** - Prepare fallback responses when AI services fail
-6. **Gracefully degrade** - Implement multiple fallback strategies
-7. **Communicate to users** - Provide clear error messages when AI services are unavailable
-
-## Error Recovery
-
-When dealing with errors, consider recovery strategies:
-
-```ruby
-MAX_RETRIES = 3
-
-def ask_with_recovery(chat, question, retries = 0)
-  chat.ask(question)
-rescue RubyLLM::RateLimitError, RubyLLM::ServiceUnavailableError => e
-  if retries < MAX_RETRIES
-    # Exponential backoff
-    sleep_time = 2 ** retries
-    puts "Error: #{e.message}. Retrying in #{sleep_time} seconds..."
-    sleep sleep_time
-    ask_with_recovery(chat, question, retries + 1)
-  else
-    raise e
-  end
-end
-```
-
-## Next Steps
-
-Now that you understand error handling in RubyLLM, you might want to explore:
-
-- [Rails Integration]({% link guides/rails.md %}) for using RubyLLM in Rails applications
-- [Tools]({% link guides/tools.md %}) for using tools with error handling

data/docs/guides/getting-started.md

@@ -1,164 +0,0 @@
----
-layout: default
-title: Getting Started
-parent: Guides
-nav_order: 1
-permalink: /guides/getting-started
----
-
-# Getting Started with RubyLLM
-
-This guide will help you get up and running with RubyLLM, showing you the basics of chatting with AI models, generating images, and creating embeddings.
-
-## Prerequisites
-
-Before starting, make sure you have:
-
-1. Installed the RubyLLM gem (see the [Installation guide]({% link installation.md %}))
-2. At least one API key from a supported provider (OpenAI, Anthropic, Google, or DeepSeek)
-
-## Basic Configuration
-
-Let's start by setting up RubyLLM with your API keys:
-
-```ruby
-require 'ruby_llm'
-
-RubyLLM.configure do |config|
-  # Add the API keys you have available
-  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.deepseek_api_key = ENV['DEEPSEEK_API_KEY']
-end
-```
-
-## Your First Chat
-
-Let's start with a simple chat interaction:
-
-```ruby
-# Create a chat (uses the default model)
-chat = RubyLLM.chat
-
-# Ask a question
-response = chat.ask "What's the capital of France?"
-puts response.content
-# => "The capital of France is Paris."
-
-# Continue the conversation
-response = chat.ask "What's the population of that city?"
-puts response.content
-# => "Paris has a population of approximately 2.1 million people..."
-```
-
-### Using a Specific Model
-
-You can specify which model you want to use:
-
-```ruby
-# Use Claude
-claude_chat = RubyLLM.chat(model: 'claude-3-5-sonnet-20241022')
-claude_chat.ask "Tell me about Ruby programming language"
-
-# Use Gemini
-gemini_chat = RubyLLM.chat(model: 'gemini-2.0-flash')
-gemini_chat.ask "What are the best Ruby gems for machine learning?"
-```
-
-## Exploring Available Models
-
-RubyLLM gives you access to models from multiple providers. You can see what's available:
-
-```ruby
-# List all models
-all_models = RubyLLM.models.all
-puts "Total models: #{all_models.count}"
-
-# List chat models
-chat_models = RubyLLM.models.chat_models
-puts "Chat models:"
-chat_models.each do |model|
-  puts "- #{model.id} (#{model.provider})"
-end
-
-# List embedding models
-RubyLLM.models.embedding_models.each do |model|
-  puts "- #{model.id} (#{model.provider})"
-end
-
-# Find info about a specific model
-gpt = RubyLLM.models.find('gpt-4o-mini')
-puts "Context window: #{gpt.context_window}"
-puts "Max tokens: #{gpt.max_tokens}"
-puts "Pricing: $#{gpt.input_price_per_million} per million input tokens"
-```
-
-## Generating Images
-
-RubyLLM makes it easy to generate images with DALL-E:
-
-```ruby
-# Generate an image
-image = RubyLLM.paint("a sunset over mountains")
-
-# The URL where you can view/download the image
-puts image.url
-
-# How the model interpreted your prompt
-puts image.revised_prompt
-
-# Generate a larger image
-large_image = RubyLLM.paint(
-  "a cyberpunk city at night with neon lights",
-  size: "1792x1024"
-)
-```
-
-## Creating Embeddings
-
-Embeddings are vector representations of text that can be used for semantic search, classification, and more:
-
-```ruby
-# Create an embedding for a single text
-embedding = RubyLLM.embed("Ruby is a programmer's best friend")
-
-# The vector representation
-vector = embedding.vectors
-puts "Vector dimension: #{vector.length}"
-
-# Create embeddings for multiple texts
-texts = ["Ruby", "Python", "JavaScript"]
-embeddings = RubyLLM.embed(texts)
-
-# Each text gets its own vector
-puts "Number of vectors: #{embeddings.vectors.length}"
-```
-
-## Working with Conversations
-
-Here's how to have a multi-turn conversation:
-
-```ruby
-chat = RubyLLM.chat
-
-# First message
-chat.ask "What are the benefits of Ruby on Rails?"
-
-# Follow-up questions
-chat.ask "How does that compare to Django?"
-chat.ask "Which one would you recommend for a new web project?"
-
-# You can check all messages in the conversation
-chat.messages.each do |message|
-  puts "#{message.role}: #{message.content[0..100]}..."
-end
-```
-
-## What's Next?
-
-Now that you've got the basics down, you're ready to explore more advanced features:
-
-- [Chatting with AI]({% link guides/chat.md %}) - Learn more about chat capabilities
-- [Using Tools]({% link guides/tools.md %}) - Let AI use your Ruby code
-- [Rails Integration]({% link guides/rails.md %}) - Persist chats in your Rails apps