ruby_llm 0.1.0.pre38 → 0.1.0.pre39

data/docs/guides/image-generation.md

@@ -1,274 +0,0 @@
----
-layout: default
-title: Image Generation
-parent: Guides
-nav_order: 6
-permalink: /guides/image-generation
----
-
-# Image Generation
-
-RubyLLM makes it easy to generate images using AI models like DALL-E. This guide explains how to create images and customize the generation process.
-
-## Basic Image Generation
-
-The simplest way to generate an image is using the global `paint` method:
-
-```ruby
-# Generate an image with DALL-E
-image = RubyLLM.paint("a sunset over mountains")
-
-# The URL where you can view/download the image
-puts image.url  # => "https://..."
-
-# How the model interpreted your prompt
-puts image.revised_prompt  # => "A breathtaking sunset painting the sky with warm..."
-```
-
-The `paint` method handles all the complexities of connecting to the right provider and processing the request.
-
-## Choosing Models
-
-By default, RubyLLM uses DALL-E 3, but you can specify a different model:
-
-```ruby
-# Use a specific model
-image = RubyLLM.paint(
-  "a cyberpunk city at night",
-  model: "dall-e-3"
-)
-
-# Alternate syntax
-image = RubyLLM.paint(
-  "a cyberpunk city at night",
-  model: "dalle-3"  # with or without hyphen
-)
-```
-
-You can configure the default model globally:
-
-```ruby
-RubyLLM.configure do |config|
-  config.default_image_model = "dall-e-3"
-end
-```
-
-## Image Sizes
-
-You can control the size of the generated image:
-
-```ruby
-# Standard size (1024x1024)
-image = RubyLLM.paint("a white siamese cat")
-
-# Landscape (1792x1024)
-landscape = RubyLLM.paint(
-  "a panoramic mountain landscape",
-  size: "1792x1024"
-)
-
-# Portrait (1024x1792)
-portrait = RubyLLM.paint(
-  "a tall redwood tree",
-  size: "1024x1792"
-)
-
-# Square with custom size
-square = RubyLLM.paint(
-  "a perfect square mandala",
-  size: "1024x1024" # standard square
-)
-```
-
-Available sizes depend on the model. DALL-E 3 supports:
-- `"1024x1024"` - Standard square (default)
-- `"1792x1024"` - Wide landscape
-- `"1024x1792"` - Tall portrait
-
-## Working with Generated Images
-
-The `Image` object returned by `paint` contains information about the generated image:
-
-```ruby
-image = RubyLLM.paint("a cyberpunk cityscape")
-
-# URL to the generated image (temporary, expires after some time)
-image_url = image.url
-
-# How the model interpreted/enhanced your prompt
-enhanced_prompt = image.revised_prompt
-
-# The model used to generate the image
-model_used = image.model_id
-```
-
-### Saving Images Locally
-
-To save the generated image to a local file:
-
-```ruby
-require 'open-uri'
-
-# Generate an image
-image = RubyLLM.paint("a sunset over mountains")
-
-# Save to a file
-File.open("sunset.png", "wb") do |file|
-  file.write(URI.open(image.url).read)
-end
-```
-
-## Prompt Engineering for Images
-
-Crafting effective prompts is crucial for getting the best results:
-
-```ruby
-# Basic prompt
-image = RubyLLM.paint("cat")
-
-# Detailed prompt
-image = RubyLLM.paint(
-  "A fluffy orange tabby cat sitting on a windowsill, " \
-  "looking out at a rainy day. Soft lighting, detailed fur, " \
-  "photorealistic style."
-)
-```
-
-### Tips for Better Prompts
-
-1. **Be specific** about subject, setting, lighting, style, and perspective
-2. **Specify artistic style** (e.g., "oil painting", "digital art", "photorealistic")
-3. **Include lighting details** ("soft morning light", "dramatic sunset")
-4. **Add composition details** ("close-up", "wide angle", "overhead view")
-5. **Specify mood or atmosphere** ("serene", "mysterious", "cheerful")
-
-## Error Handling
-
-Handle errors that may occur during image generation:
-
-```ruby
-begin
-  image = RubyLLM.paint("a sunset over mountains")
-  puts "Image generated: #{image.url}"
-rescue RubyLLM::UnauthorizedError
-  puts "Please check your API key"
-rescue RubyLLM::BadRequestError => e
-  puts "Invalid request: #{e.message}"
-rescue RubyLLM::Error => e
-  puts "Error generating image: #{e.message}"
-end
-```
-
-Common errors include:
-- `UnauthorizedError` - Invalid API key
-- `BadRequestError` - Content policy violation
-- `RateLimitError` - Too many requests
-- `ServiceUnavailableError` - Service temporarily unavailable
-
-## Content Safety
-
-Image generation models have built-in safety filters. If your prompt violates content policies, you'll receive an error.
-
-To avoid content policy violations:
-- Avoid requesting violent, adult, or disturbing content
-- Don't ask for images of real public figures
-- Avoid copyrighted characters and content
-- Be mindful of sensitive subject matter
-
-## Performance Considerations
-
-Image generation typically takes 5-15 seconds. Consider these best practices:
-
-1. **Handle asynchronously** - Don't block your application while waiting
-2. **Implement timeouts** - Set appropriate request timeouts
-3. **Cache results** - Save images to your server rather than regenerating
-4. **Implement retries** - Retry on temporary failures
-
-## Rails Integration
-
-In a Rails application, you might implement image generation like this:
-
-```ruby
-class ImagesController < ApplicationController
-  def create
-    GenerateImageJob.perform_later(
-      prompt: params[:prompt],
-      user_id: current_user.id
-    )
-
-    redirect_to images_path, notice: "Your image is being generated..."
-  end
-end
-
-class GenerateImageJob < ApplicationJob
-  queue_as :default
-
-  def perform(prompt:, user_id:)
-    user = User.find(user_id)
-
-    begin
-      image = RubyLLM.paint(prompt)
-
-      # Download and store the image
-      image_file = URI.open(image.url)
-
-      # Create record in your database
-      user.images.create!(
-        prompt: prompt,
-        revised_prompt: image.revised_prompt,
-        file: image_file,
-        model: image.model_id
-      )
-
-      # Notify user
-      UserMailer.image_ready(user, prompt).deliver_later
-    rescue RubyLLM::Error => e
-      ErrorLogger.log(e, context: { prompt: prompt, user_id: user_id })
-      UserMailer.image_failed(user, prompt, e.message).deliver_later
-    end
-  end
-end
-```
-
-## Example Use Cases
-
-### Product Visualization
-
-```ruby
-def visualize_product(product_name, description)
-  prompt = "#{product_name}: #{description}. " \
-           "Professional product photography on white background, " \
-           "detailed, commercial quality."
-
-  RubyLLM.paint(prompt, size: "1024x1024")
-end
-
-image = visualize_product(
-  "Ergonomic Office Chair",
-  "Modern mesh back office chair with adjustable armrests and lumbar support"
-)
-```
-
-### Art Generation for Content
-
-```ruby
-def generate_article_header(title, style)
-  prompt = "Header image for an article titled '#{title}'. " \
-           "Style: #{style}. Wide format, suitable for a blog header."
-
-  RubyLLM.paint(prompt, size: "1792x1024")
-end
-
-image = generate_article_header(
-  "The Future of Renewable Energy",
-  "Minimalist digital illustration with clean lines and a blue-green color palette"
-)
-```
-
-## Next Steps
-
-Now that you understand image generation, you might want to explore:
-
-- [Embeddings]({% link guides/embeddings.md %}) for vector representations
-- [Chat with Images]({% link guides/chat.md %}#working-with-images) to analyze images with AI
-- [Error Handling]({% link guides/error-handling.md %}) for robust applications

data/docs/guides/index.md

@@ -1,45 +0,0 @@
----
-layout: default
-title: Guides
-nav_order: 3
-has_children: true
-permalink: /guides/
----
-
-# RubyLLM Guides
-
-This section contains detailed guides to help you make the most of RubyLLM. Each guide focuses on a specific aspect of the library and provides practical examples and best practices.
-
-## Available Guides
-
-### [Getting Started]({% link guides/getting-started.md %})
-Learn the basics of RubyLLM and get up and running quickly with simple examples.
-
-### [Chat]({% link guides/chat.md %})
-Explore the chat interface, which is the primary way to interact with AI models through RubyLLM.
-
-### [Tools]({% link guides/tools.md %})
-Learn how to extend AI capabilities by creating tools that let models call your Ruby code.
-
-### [Streaming]({% link guides/streaming.md %})
-Understand how to use streaming responses for real-time interactions.
-
-### [Rails Integration]({% link guides/rails.md %})
-See how to integrate RubyLLM with Rails applications, including ActiveRecord persistence.
-
-### [Image Generation]({% link guides/image-generation.md %})
-Learn how to generate images using DALL-E and other providers.
-
-### [Embeddings]({% link guides/embeddings.md %})
-Explore how to create vector embeddings for semantic search and other applications.
-
-### [Error Handling]({% link guides/error-handling.md %})
-Master the techniques for robust error handling in AI applications.
-
-## Getting Help
-
-If you can't find what you're looking for in these guides, consider:
-
-1. Checking the [API Documentation]() for detailed information about specific classes and methods
-2. Looking at the [GitHub repository](https://github.com/yourusername/ruby_llm) for examples and the latest updates
-3. Filing an issue on GitHub if you find a bug or have a feature request

data/docs/guides/rails.md

@@ -1,401 +0,0 @@
----
-layout: default
-title: Rails Integration
-parent: Guides
-nav_order: 5
-permalink: /guides/rails
----
-
-# Rails Integration
-
-RubyLLM provides seamless integration with Rails through ActiveRecord models. This allows you to easily persist chats, messages, and tool calls in your database.
-
-## Setup
-
-### 1. Create Migrations
-
-First, create the necessary tables in your database:
-
-```ruby
-# db/migrate/YYYYMMDDHHMMSS_create_chats.rb
-class CreateChats < ActiveRecord::Migration[8.0]
-  def change
-    create_table :chats do |t|
-      t.string :model_id
-      t.timestamps
-    end
-  end
-end
-
-# db/migrate/YYYYMMDDHHMMSS_create_messages.rb
-class CreateMessages < ActiveRecord::Migration[8.0]
-  def change
-    create_table :messages do |t|
-      t.references :chat, null: false, foreign_key: true
-      t.string :role
-      t.text :content
-      t.string :model_id
-      t.integer :input_tokens
-      t.integer :output_tokens
-      t.references :tool_call
-      t.timestamps
-    end
-  end
-end
-
-# db/migrate/YYYYMMDDHHMMSS_create_tool_calls.rb
-class CreateToolCalls < ActiveRecord::Migration[8.0]
-  def change
-    create_table :tool_calls do |t|
-      t.references :message, null: false, foreign_key: true
-      t.string :tool_call_id, null: false
-      t.string :name, null: false
-      t.jsonb :arguments, default: {}
-      t.timestamps
-    end
-
-    add_index :tool_calls, :tool_call_id
-  end
-end
-```
-
-Run the migrations:
-
-```bash
-rails db:migrate
-```
-
-### 2. Set Up Models
-
-Create the model classes:
-
-```ruby
-# app/models/chat.rb
-class Chat < ApplicationRecord
-  acts_as_chat
-end
-
-# app/models/message.rb
-class Message < ApplicationRecord
-  acts_as_message
-end
-
-# app/models/tool_call.rb
-class ToolCall < ApplicationRecord
-  acts_as_tool_call
-end
-```
-
-### 3. Configure RubyLLM
-
-In an initializer (e.g., `config/initializers/ruby_llm.rb`):
-
-```ruby
-RubyLLM.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.deepseek_api_key = ENV['DEEPSEEK_API_KEY']
-end
-```
-
-## Basic Usage
-
-Once your models are set up, you can use them like any other Rails model:
-
-```ruby
-# Create a new chat
-chat = Chat.create!(model_id: 'gpt-4o-mini')
-
-# Ask a question
-chat.ask "What's the capital of France?"
-
-# The response is automatically persisted
-puts chat.messages.last.content
-
-# Continue the conversation
-chat.ask "Tell me more about that city"
-
-# All messages are stored in the database
-chat.messages.order(:created_at).each do |message|
-  puts "#{message.role}: #{message.content}"
-end
-```
-
-## Streaming Responses
-
-You can stream responses while still persisting the final result:
-
-```ruby
-chat = Chat.create!(model_id: 'gpt-4o-mini')
-
-chat.ask "Write a short poem about Ruby" do |chunk|
-  # Stream content to the user
-  ActionCable.server.broadcast "chat_#{chat.id}", { content: chunk.content }
-end
-
-# The complete message is saved in the database
-puts chat.messages.last.content
-```
-
-## Using with Hotwire
-
-RubyLLM's Rails integration works seamlessly with Hotwire for real-time updates:
-
-```ruby
-# app/models/chat.rb
-class Chat < ApplicationRecord
-  acts_as_chat
-
-  # Add broadcast capabilities
-  broadcasts_to ->(chat) { "chat_#{chat.id}" }
-end
-```
-
-In your controller:
-
-```ruby
-# app/controllers/chats_controller.rb
-class ChatsController < ApplicationController
-  def show
-    @chat = Chat.find(params[:id])
-  end
-
-  def ask
-    @chat = Chat.find(params[:id])
-
-    # Use a background job to avoid blocking
-    ChatJob.perform_later(@chat.id, params[:message])
-
-    # Let the user know we're working on it
-    respond_to do |format|
-      format.turbo_stream
-      format.html { redirect_to @chat }
-    end
-  end
-end
-```
-
-Create a background job:
-
-```ruby
-# app/jobs/chat_job.rb
-class ChatJob < ApplicationJob
-  queue_as :default
-
-  def perform(chat_id, message)
-    chat = Chat.find(chat_id)
-
-    # Start with a "typing" indicator
-    Turbo::StreamsChannel.broadcast_append_to(
-      chat,
-      target: "messages",
-      partial: "messages/typing"
-    )
-
-    chat.ask(message) do |chunk|
-      # Remove typing indicator after first chunk
-      if chunk == chat.messages.last.to_llm.content[0...chunk.content.length]
-        Turbo::StreamsChannel.broadcast_remove_to(
-          chat,
-          target: "typing"
-        )
-      end
-
-      # Update the streaming message
-      Turbo::StreamsChannel.broadcast_replace_to(
-        chat,
-        target: "assistant_message_#{chat.messages.last.id}",
-        partial: "messages/message",
-        locals: { message: chat.messages.last, content: chunk.content }
-      )
-    end
-  end
-end
-```
-
-In your views:
-
-```erb
-<!-- app/views/chats/show.html.erb -->
-<%= turbo_stream_from @chat %>
-
-<div id="messages">
-  <%= render @chat.messages %>
-</div>
-
-<%= form_with(url: ask_chat_path(@chat), method: :post) do |f| %>
-  <%= f.text_area :message %>
-  <%= f.submit "Send" %>
-<% end %>
-```
-
-## Using Tools
-
-Tools work seamlessly with Rails integration:
-
-```ruby
-class Calculator < RubyLLM::Tool
-  description "Performs arithmetic calculations"
-
-  param :expression,
-    type: :string,
-    desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
-  rescue StandardError => e
-    "Error: #{e.message}"
-  end
-end
-
-# Add the tool to your chat
-chat = Chat.create!(model_id: 'gpt-4o-mini')
-chat.with_tool(Calculator)
-
-# Ask a question that requires calculation
-chat.ask "What's 123 * 456?"
-
-# Tool calls are persisted
-tool_call = chat.messages.find_by(role: 'assistant').tool_calls.first
-puts "Tool: #{tool_call.name}"
-puts "Arguments: #{tool_call.arguments}"
-```
-
-## Customizing Models
-
-You can customize the behavior of your models:
-
-```ruby
-class Chat < ApplicationRecord
-  acts_as_chat
-
-  # Add custom behavior
-  belongs_to :user
-  has_many :tags
-
-  # Add custom scopes
-  scope :recent, -> { order(created_at: :desc).limit(10) }
-  scope :by_model, ->(model_id) { where(model_id: model_id) }
-
-  # Add custom methods
-  def summarize
-    self.ask "Please summarize our conversation so far."
-  end
-
-  def token_count
-    messages.sum { |m| (m.input_tokens || 0) + (m.output_tokens || 0) }
-  end
-end
-```
-
-## Message Content Customization
-
-You can customize how message content is stored or extracted:
-
-```ruby
-class Message < ApplicationRecord
-  acts_as_message
-
-  # Override content handling
-  def extract_content
-    # For example, compress or expand content
-    JSON.parse(content) rescue content
-  end
-end
-```
-
-## Advanced Integration
-
-### User Association
-
-Associate chats with users:
-
-```ruby
-# Migration
-add_reference :chats, :user, foreign_key: true
-
-# Model
-class Chat < ApplicationRecord
-  acts_as_chat
-  belongs_to :user
-end
-
-# Usage
-user.chats.create!(model_id: 'gpt-4o-mini').ask("Hello!")
-```
-
-### Metadata and Tagging
-
-Add metadata to chats:
-
-```ruby
-# Migration
-add_column :chats, :metadata, :jsonb, default: {}
-
-# Model
-class Chat < ApplicationRecord
-  acts_as_chat
-end
-
-# Usage
-chat = Chat.create!(
-  model_id: 'gpt-4o-mini',
-  metadata: {
-    purpose: 'customer_support',
-    category: 'billing',
-    priority: 'high'
-  }
-)
-```
-
-### Scoping and Filtering
-
-Create scopes for easier querying:
-
-```ruby
-class Chat < ApplicationRecord
-  acts_as_chat
-
-  scope :using_gpt, -> { where("model_id LIKE ?", "gpt-%") }
-  scope :using_claude, -> { where("model_id LIKE ?", "claude-%") }
-  scope :recent, -> { order(created_at: :desc).limit(10) }
-  scope :with_high_token_count, -> {
-    joins(:messages)
-    .group(:id)
-    .having("SUM(messages.input_tokens + messages.output_tokens) > ?", 10000)
-  }
-end
-```
-
-## Performance Considerations
-
-For high-volume applications:
-
-1. **Background Processing**: Use background jobs for AI requests
-2. **Connection Pooling**: Ensure your database connection pool is sized appropriately
-3. **Pagination**: Use pagination when showing chat histories
-4. **Archiving**: Consider archiving old chats to maintain performance
-
-```ruby
-# Example background job
-class AskAiJob < ApplicationJob
-  queue_as :ai_requests
-
-  def perform(chat_id, message)
-    chat = Chat.find(chat_id)
-    chat.ask(message)
-  end
-end
-
-# Usage
-AskAiJob.perform_later(chat.id, "Tell me about Ruby")
-```
-
-## Next Steps
-
-Now that you've integrated RubyLLM with Rails, you might want to explore:
-
-- [Using Tools]({% link guides/tools.md %}) to add capabilities to your chats
-- [Streaming Responses]({% link guides/streaming.md %}) for a better user experience
-- [Error Handling]({% link guides/error-handling.md %}) to handle AI service issues gracefully