ruby_llm 0.1.0.pre38 → 0.1.0.pre39

data/docs/guides/streaming.md

@@ -1,242 +0,0 @@
----
-layout: default
-title: Streaming
-parent: Guides
-nav_order: 4
-permalink: /guides/streaming
----
-
-# Streaming Responses
-
-RubyLLM provides streaming capabilities that allow you to receive AI responses in real-time as they're being generated, rather than waiting for the complete response. This creates a more interactive experience and is especially useful for long responses or applications with real-time UI updates.
-
-## Basic Streaming
-
-To stream responses, simply provide a block to the `ask` method:
-
-```ruby
-chat = RubyLLM.chat
-
-chat.ask "Write a short story about a programmer" do |chunk|
-  # Each chunk contains a portion of the response
-  print chunk.content
-  $stdout.flush  # Ensure content is displayed immediately
-end
-```
-
-## Understanding Chunks
-
-Each streamed chunk is an instance of `RubyLLM::Chunk` (which inherits from `RubyLLM::Message`) and provides:
-
-```ruby
-chunk.content       # The text fragment in this chunk
-chunk.role          # Always :assistant for streamed chunks
-chunk.model_id      # The model generating the response
-chunk.input_tokens  # Input token count (usually only in the final chunk)
-chunk.output_tokens # Output token count (usually only in the final chunk)
-```
-
-## Accumulated Response
-
-Even when streaming, RubyLLM still returns the complete final message:
-
-```ruby
-final_message = chat.ask "Write a poem" do |chunk|
-  print chunk.content
-end
-
-# You can use the final message as normal
-puts "\nFinal message length: #{final_message.content.length}"
-puts "Token usage: #{final_message.output_tokens} tokens"
-```
-
-## Web Application Integration
-
-### Rails with ActionCable
-
-```ruby
-# In your controller
-def ask
-  @chat = Chat.find(params[:id])
-
-  @chat.ask(params[:message]) do |chunk|
-    ActionCable.server.broadcast(
-      "chat_#{@chat.id}",
-      { content: chunk.content }
-    )
-  end
-
-  head :ok
-end
-
-# In your JavaScript
-const channel = consumer.subscriptions.create({ channel: "ChatChannel", id: chatId }, {
-  received(data) {
-    // Append incoming chunk to the display
-    document.getElementById('response').innerHTML += data.content;
-  }
-});
-```
-
-### Rails with Turbo Streams
-
-```ruby
-class ChatJob < ApplicationJob
-  queue_as :default
-
-  def perform(chat_id, message)
-    chat = Chat.find(chat_id)
-
-    chat.ask(message) do |chunk|
-      Turbo::StreamsChannel.broadcast_update_to(
-        "chat_#{chat.id}",
-        target: "response",
-        html: chunk.content,
-        append: true
-      )
-    end
-  end
-end
-```
-
-### Sinatra with Server-Sent Events (SSE)
-
-```ruby
-get '/chat/:id/ask' do
-  content_type 'text/event-stream'
-
-  chat = Chat.find(params[:id])
-
-  chat.ask(params[:message]) do |chunk|
-    # Send chunk as SSE event
-    out << "data: #{chunk.content}\n\n"
-  end
-
-  # Send completion signal
-  out << "event: complete\ndata: {}\n\n"
-end
-```
-
-## Error Handling
-
-Errors that occur during streaming need special handling:
-
-```ruby
-begin
-  chat.ask("Tell me a story") do |chunk|
-    print chunk.content
-  end
-rescue RubyLLM::Error => e
-  puts "\nError during streaming: #{e.message}"
-end
-```
-
-Common errors during streaming:
-
-- `ServiceUnavailableError` - The AI service is temporarily unavailable
-- `RateLimitError` - You've exceeded your API rate limit
-- `BadRequestError` - There was a problem with your request parameters
-
-## Provider-Specific Considerations
-
-### OpenAI
-
-OpenAI's streaming implementation provides small, frequent chunks for a smooth experience.
-
-### Anthropic
-
-Claude models may return slightly larger chunks with potentially longer pauses between them.
-
-### Google Gemini
-
-Gemini streaming is highly responsive but may show slightly different chunking behavior.
-
-## Streaming with Tools
-
-When using tools, streaming works a bit differently:
-
-```ruby
-chat.with_tool(Calculator)
-   .ask("What's 123 * 456?") do |chunk|
-     # Tool call execution isn't streamed
-     # You'll receive chunks after tool execution completes
-     print chunk.content
-   end
-```
-
-The tool call execution introduces a pause in the streaming, as the model waits for the tool response before continuing.
-
-## Performance Considerations
-
-Streaming typically uses the same number of tokens as non-streaming responses but establishes longer-lived connections to the AI provider. Consider these best practices:
-
-1. Set appropriate timeouts for streaming connections
-2. Handle network interruptions gracefully
-3. Consider background processing for long-running streams
-4. Implement rate limiting to avoid overwhelming your servers
-
-## Tracking Token Usage
-
-Token usage information is typically only available in the final chunk or completed message:
-
-```ruby
-total_tokens = 0
-
-chat.ask("Write a detailed explanation of quantum computing") do |chunk|
-  print chunk.content
-
-  # Only count tokens in the final chunk
-  if chunk.output_tokens
-    total_tokens = chunk.input_tokens + chunk.output_tokens
-  end
-end
-
-puts "\nTotal tokens: #{total_tokens}"
-```
-
-## Custom Processing of Streamed Content
-
-You can process streamed content in real-time:
-
-```ruby
-accumulated_text = ""
-
-chat.ask("Write a list of 10 fruits") do |chunk|
-  new_content = chunk.content
-  accumulated_text += new_content
-
-  # Count fruits as they come in
-  if new_content.include?("\n")
-    fruit_count = accumulated_text.scan(/\d+\./).count
-    print "\rFruits listed: #{fruit_count}/10"
-  end
-end
-```
-
-## Rails Integration
-
-When using RubyLLM's Rails integration with `acts_as_chat`, streaming still works seamlessly:
-
-```ruby
-class Chat < ApplicationRecord
-  acts_as_chat
-end
-
-chat = Chat.create!(model_id: 'gpt-4o-mini')
-
-# Stream responses while persisting the final result
-chat.ask("Tell me about Ruby") do |chunk|
-  ActionCable.server.broadcast("chat_#{chat.id}", { content: chunk.content })
-end
-
-# The complete message is saved in the database
-puts chat.messages.last.content
-```
-
-## Next Steps
-
-Now that you understand streaming, you might want to explore:
-
-- [Using Tools]({% link guides/tools.md %}) to add capabilities to your AI interactions
-- [Rails Integration]({% link guides/rails.md %}) to persist conversations
-- [Error Handling]({% link guides/error-handling.md %}) for reliable applications

data/docs/guides/tools.md

@@ -1,247 +0,0 @@
----
-layout: default
-title: Tools
-parent: Guides
-nav_order: 3
-permalink: /guides/tools
----
-
-# Using Tools with RubyLLM
-
-Tools allow AI models to call your Ruby code to perform actions or retrieve information. This guide explains how to create and use tools with RubyLLM.
-
-## What Are Tools?
-
-Tools (also known as "functions" or "plugins") let AI models:
-
-1. Recognize when external functionality is needed
-2. Call your Ruby code with appropriate parameters
-3. Use the results to enhance their responses
-
-Common use cases include:
-- Retrieving real-time data
-- Performing calculations
-- Accessing databases
-- Controlling external systems
-
-## Creating a Tool
-
-Tools are defined as Ruby classes that inherit from `RubyLLM::Tool`:
-
-```ruby
-class Calculator < RubyLLM::Tool
-  description "Performs arithmetic calculations"
-
-  param :expression,
-    type: :string,
-    desc: "A mathematical expression to evaluate (e.g. '2 + 2')"
-
-  def execute(expression:)
-    eval(expression).to_s
-  rescue StandardError => e
-    "Error: #{e.message}"
-  end
-end
-```
-
-### Tool Components
-
-Each tool has these key elements:
-
-1. **Description** - Explains what the tool does, helping the AI decide when to use it
-2. **Parameters** - Define the inputs the tool expects
-3. **Execute Method** - The code that runs when the tool is called
-
-### Parameter Definition
-
-Parameters accept several options:
-
-```ruby
-param :parameter_name,
-  type: :string,          # Data type (:string, :integer, :boolean, :array, :object)
-  desc: "Description",    # Description of what the parameter does
-  required: true          # Whether the parameter is required (default: true)
-```
-
-## Using Tools in Chat
-
-To use a tool, attach it to a chat:
-
-```ruby
-# Create the chat
-chat = RubyLLM.chat
-
-# Add a tool
-chat.with_tool(Calculator)
-
-# Now you can ask questions that might require calculation
-response = chat.ask "What's 123 * 456?"
-# => "Let me calculate that for you. 123 * 456 = 56088."
-```
-
-### Multiple Tools
-
-You can provide multiple tools to a single chat:
-
-```ruby
-class Weather < RubyLLM::Tool
-  description "Gets current weather for a location"
-
-  param :location,
-    desc: "City name or zip code"
-
-  def execute(location:)
-    # Simulate weather lookup
-    "72°F and sunny in #{location}"
-  end
-end
-
-# Add multiple tools
-chat = RubyLLM.chat
-  .with_tools(Calculator, Weather)
-
-# Ask questions that might use either tool
-chat.ask "What's the temperature in New York City?"
-chat.ask "If it's 72°F in NYC and 54°F in Boston, what's the average?"
-```
-
-## Custom Initialization
-
-Tools can have custom initialization:
-
-```ruby
-class DocumentSearch < RubyLLM::Tool
-  description "Searches documents by relevance"
-
-  param :query,
-    desc: "The search query"
-
-  param :limit,
-    type: :integer,
-    desc: "Maximum number of results",
-    required: false
-
-  def initialize(database)
-    @database = database
-  end
-
-  def execute(query:, limit: 5)
-    # Search in @database
-    @database.search(query, limit: limit)
-  end
-end
-
-# Initialize with dependencies
-search_tool = DocumentSearch.new(MyDatabase)
-chat.with_tool(search_tool)
-```
-
-## The Tool Execution Flow
-
-Here's what happens when a tool is used:
-
-1. You ask a question
-2. The model decides a tool is needed
-3. The model selects the tool and provides arguments
-4. RubyLLM calls your tool's `execute` method
-5. The result is sent back to the model
-6. The model incorporates the result into its response
-
-For example:
-
-```ruby
-response = chat.ask "What's 123 squared plus 456?"
-
-# Behind the scenes:
-# 1. Model decides it needs to calculate
-# 2. Model calls Calculator with expression: "123 * 123 + 456"
-# 3. Tool returns "15,585"
-# 4. Model incorporates this in its response
-```
-
-## Debugging Tools
-
-Enable debugging to see tool calls in action:
-
-```ruby
-# Enable debug logging
-ENV['RUBY_LLM_DEBUG'] = 'true'
-
-# Make a request
-chat.ask "What's 15329 divided by 437?"
-
-# Console output:
-# D, -- RubyLLM: Tool calculator called with: {"expression"=>"15329 / 437"}
-# D, -- RubyLLM: Tool calculator returned: "35.078719"
-```
-
-## Error Handling
-
-Tools can handle errors gracefully:
-
-```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
-    # Return error as a result
-    { error: "Error calculating #{expression}: #{e.message}" }
-  end
-end
-
-# When there's an error, the model will receive and explain it
-chat.ask "What's 1/0?"
-# => "I tried to calculate 1/0, but there was an error: divided by 0"
-```
-
-## Advanced Tool Parameters
-
-Tools can have complex parameter types:
-
-```ruby
-class DataAnalysis < RubyLLM::Tool
-  description "Analyzes numerical data"
-
-  param :data,
-    type: :array,
-    desc: "Array of numbers to analyze"
-
-  param :operations,
-    type: :object,
-    desc: "Analysis operations to perform",
-    required: false
-
-  def execute(data:, operations: {mean: true, median: false})
-    result = {}
-
-    result[:mean] = data.sum.to_f / data.size if operations[:mean]
-    result[:median] = calculate_median(data) if operations[:median]
-
-    result
-  end
-
-  private
-
-  def calculate_median(data)
-    sorted = data.sort
-    mid = sorted.size / 2
-    sorted.size.odd? ? sorted[mid] : (sorted[mid-1] + sorted[mid]) / 2.0
-  end
-end
-```
-
-## When to Use Tools
-
-Tools are best for:
-
-1. **External data retrieval** - Getting real-time information like weather, prices, or database records
-2. **Computation** - When calculations are complex or involve large numbers
-3. **System integration** - Connecting to external APIs or services
-4. **Data processing** - Working with files, formatting data, or analyzing information
-5. **Stateful operations** - When you need to maintain state between calls

data/docs/index.md

@@ -1,73 +0,0 @@
----
-layout: default
-title: Home
-nav_order: 1
-description: "RubyLLM is a delightful Ruby way to work with AI."
-permalink: /
----
-
-# RubyLLM
-{: .fs-9 }
-
-A delightful Ruby way to work with AI through a unified interface to OpenAI, Anthropic, Google, and DeepSeek.
-{: .fs-6 .fw-300 }
-
-[Get started now]({% link installation.md %}){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
-[View on GitHub](https://github.com/crmne/ruby_llm){: .btn .fs-5 .mb-4 .mb-md-0 }
-
----
-<p align="center">
-  <img src="https://upload.wikimedia.org/wikipedia/commons/4/4d/OpenAI_Logo.svg" alt="OpenAI" height="40" width="120">
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Anthropic_logo.svg" alt="Anthropic" height="40" width="120">
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/8/8a/Google_Gemini_logo.svg" alt="Google" height="40" width="120">
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/e/ec/DeepSeek_logo.svg" alt="DeepSeek" height="40" width="120">
-</p>
-
-<p align="center">
-  <a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg" alt="Gem Version" /></a>
-  <a href="https://github.com/testdouble/standard"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Ruby Style Guide" /></a>
-  <a href="https://rubygems.org/gems/ruby_llm"><img alt="Gem Total Downloads" src="https://img.shields.io/gem/dt/ruby_llm"></a>
-  <a href="https://github.com/crmne/ruby_llm/actions/workflows/cicd.yml"><img src="https://github.com/crmne/ruby_llm/actions/workflows/cicd.yml/badge.svg" alt="CI" /></a>
-  <a href="https://codecov.io/gh/crmne/ruby_llm"><img src="https://codecov.io/gh/crmne/ruby_llm/branch/main/graph/badge.svg" alt="codecov" /></a>
-</p>
-
----
-
-## Overview
-
-RubyLLM provides a beautiful, unified interface to modern AI services, including:
-
-- 💬 **Chat** with OpenAI GPT, Anthropic Claude, Google Gemini, and DeepSeek models
-- 🎵 **Vision and Audio** understanding
-- 🖼️ **Image generation** with DALL-E and other providers
-- 📊 **Embeddings** for vector search and semantic analysis
-- 🔧 **Tools** that let AI use your Ruby code
-- 🚂 **Rails integration** to persist chats and messages with ActiveRecord
-- 🌊 **Streaming** responses with proper Ruby patterns
-
-## Quick start
-
-```ruby
-require 'ruby_llm'
-
-# Configure your API keys
-RubyLLM.configure do |config|
-  config.openai_api_key = ENV['OPENAI_API_KEY']
-end
-
-# Start chatting
-chat = RubyLLM.chat
-response = chat.ask "What's the best way to learn Ruby?"
-
-# Generate images
-image = RubyLLM.paint "a sunset over mountains"
-puts image.url
-```
-
-## Learn more
-
-- [Installation]({% link installation.md %})
-- [Guides]({% link guides/index.md %})

data/docs/installation.md

@@ -1,98 +0,0 @@
----
-layout: default
-title: Installation
-nav_order: 2
-permalink: /installation
----
-
-# Installation
-
-RubyLLM is packaged as a Ruby gem, making it easy to install in your projects.
-
-## Requirements
-
-* Ruby 3.1 or later
-* An API key from at least one of the supported providers:
-  * OpenAI
-  * Anthropic
-  * Google (Gemini)
-  * DeepSeek
-
-## Installation Methods
-
-### Using Bundler (recommended)
-
-Add RubyLLM to your project's Gemfile:
-
-```ruby
-gem 'ruby_llm'
-```
-
-Then install the dependencies:
-
-```bash
-bundle install
-```
-
-### Manual Installation
-
-If you're not using Bundler, you can install RubyLLM directly:
-
-```bash
-gem install ruby_llm
-```
-
-## Configuration
-
-After installing RubyLLM, you'll need to configure it with your API keys:
-
-```ruby
-require 'ruby_llm'
-
-RubyLLM.configure do |config|
-  # Required: At least one API key
-  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']
-
-  # Optional: Set default models
-  config.default_model = 'gpt-4o-mini'               # Default chat model
-  config.default_embedding_model = 'text-embedding-3-small'  # Default embedding model
-  config.default_image_model = 'dall-e-3'            # Default image generation model
-
-  # Optional: Configure request settings
-  config.request_timeout = 120  # Request timeout in seconds
-  config.max_retries = 3        # Number of retries on failures
-end
-```
-
-We recommend storing your API keys as environment variables rather than hardcoding them in your application.
-
-## Verifying Installation
-
-You can verify that RubyLLM is correctly installed and configured by running a simple test:
-
-```ruby
-require 'ruby_llm'
-
-# Configure with at least one API key
-RubyLLM.configure do |config|
-  config.openai_api_key = ENV['OPENAI_API_KEY']
-end
-
-# Try a simple query
-chat = RubyLLM.chat
-response = chat.ask "Hello, world!"
-puts response.content
-
-# Check available models
-puts "Available models:"
-RubyLLM.models.chat_models.each do |model|
-  puts "- #{model.id} (#{model.provider})"
-end
-```
-
-## Next Steps
-
-Once you've successfully installed RubyLLM, check out the [Getting Started guide]({% link guides/getting-started.md %}) to learn how to use it in your applications.