ruby_llm 0.1.0.pre36 → 0.1.0.pre37

data/docs/guides/tools.md

@@ -0,0 +1,247 @@
+---
+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

@@ -0,0 +1,53 @@
+---
+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 }
+
+---
+
+## Overview
+
+RubyLLM provides a beautiful, unified interface to modern AI services, including:
+
+- 💬 **Chat** with OpenAI GPT, Anthropic Claude, Google Gemini, and DeepSeek models
+- 🖼️ **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

@@ -0,0 +1,98 @@
+---
+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.

data/lib/ruby_llm/active_record/acts_as.rb

@@ -85,10 +85,10 @@ module RubyLLM
              .on_end_message { |msg| persist_message_completion(msg) }
       end
 
-      def ask(message, &block)
+      def ask(message, &)
         message = { role: :user, content: message }
         messages.create!(**message)
-        to_llm.complete(&block)
+        to_llm.complete(&)
       end
 
       alias say ask

data/lib/ruby_llm/chat.rb

@@ -72,18 +72,18 @@ module RubyLLM
       self
     end
 
-    def each(&block)
-      messages.each(&block)
+    def each(&)
+      messages.each(&)
     end
 
-    def complete(&block)
+    def complete(&)
       @on[:new_message]&.call
-      response = @provider.complete(messages, tools: @tools, temperature: @temperature, model: @model.id, &block)
+      response = @provider.complete(messages, tools: @tools, temperature: @temperature, model: @model.id, &)
       @on[:end_message]&.call(response)
 
       add_message response
       if response.tool_call?
-        handle_tool_calls response, &block
+        handle_tool_calls(response, &)
       else
         response
       end
@@ -97,7 +97,7 @@ module RubyLLM
 
     private
 
-    def handle_tool_calls(response, &block)
+    def handle_tool_calls(response, &)
       response.tool_calls.each_value do |tool_call|
         @on[:new_message]&.call
         result = execute_tool tool_call
@@ -105,7 +105,7 @@ module RubyLLM
         @on[:end_message]&.call(message)
       end
 
-      complete(&block)
+      complete(&)
     end
 
     def execute_tool(tool_call)

data/lib/ruby_llm/providers/anthropic/capabilities.rb

@@ -20,8 +20,7 @@ module RubyLLM
         # @return [Integer] the maximum output tokens
         def determine_max_tokens(model_id)
           case model_id
-          when /claude-3-7-sonnet/ then 8_192 # Can be increased to 64K with extended thinking
-          when /claude-3-5/ then 8_192
+          when /claude-3-(7-sonnet|5)/ then 8_192 # Can be increased to 64K with extended thinking
           else 4_096 # Claude 3 Opus and Haiku
           end
         end

data/lib/ruby_llm/providers/anthropic/chat.rb

@@ -35,7 +35,7 @@ module RubyLLM
 
         def extract_text_content(blocks)
           text_blocks = blocks.select { |c| c['type'] == 'text' }
-          text_blocks.map { |c| c['text'] }.join('')
+          text_blocks.map { |c| c['text'] }.join
         end
 
         def build_message(data, content, tool_use)
@@ -68,8 +68,7 @@ module RubyLLM
 
         def convert_role(role)
           case role
-          when :tool then 'user'
-          when :user then 'user'
+          when :tool, :user then 'user'
           else 'assistant'
           end
         end

data/lib/ruby_llm/providers/deepseek/capabilities.rb

@@ -95,7 +95,6 @@ module RubyLLM
         # @return [Symbol] the model family
         def model_family(model_id)
           case model_id
-          when /deepseek-chat/ then :chat
           when /deepseek-reasoner/ then :reasoner
           else :chat # Default to chat family
           end

data/lib/ruby_llm/providers/gemini/capabilities.rb

@@ -97,7 +97,7 @@ module RubyLLM
             .join(' ')
             .gsub(/(\d+\.\d+)/, ' \1') # Add space before version numbers
             .gsub(/\s+/, ' ')          # Clean up multiple spaces
-            .gsub(/Aqa/, 'AQA')        # Special case for AQA
+            .gsub('Aqa', 'AQA')        # Special case for AQA
             .strip
         end
 

data/lib/ruby_llm/providers/openai/capabilities.rb

@@ -15,7 +15,6 @@ module RubyLLM
           when /o1-2024/, /o3-mini/, /o3-mini-2025/ then 200_000
           when /gpt-4o/, /gpt-4o-mini/, /gpt-4-turbo/, /o1-mini/ then 128_000
           when /gpt-4-0[0-9]{3}/ then 8_192
-          when /gpt-3.5-turbo-instruct/ then 4_096
           when /gpt-3.5/ then 16_385
           when /babbage-002/, /davinci-002/ then 16_384
           else 4_096
@@ -25,16 +24,12 @@ module RubyLLM
         # Returns the maximum output tokens for the given model ID
         # @param model_id [String] the model identifier
         # @return [Integer] the maximum output tokens
-        def max_tokens_for(model_id) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+        def max_tokens_for(model_id)
           case model_id
           when /o1-2024/, /o3-mini/, /o3-mini-2025/ then 100_000
           when /o1-mini-2024/ then 65_536
-          when /gpt-4o-2024-05-13/ then 4_096
-          when /gpt-4o-realtime/, /gpt-4o-mini-realtime/ then 4_096
-          when /gpt-4o/, /gpt-4o-mini/, /gpt-4o-audio/, /gpt-4o-mini-audio/ then 16_384
+          when /gpt-4o/, /gpt-4o-mini/, /gpt-4o-audio/, /gpt-4o-mini-audio/, /babbage-002/, /davinci-002/ then 16_384
           when /gpt-4-0[0-9]{3}/ then 8_192
-          when /gpt-4-turbo/, /gpt-3.5-turbo/ then 4_096
-          when /babbage-002/, /davinci-002/ then 16_384
           else 4_096
           end
         end
@@ -211,7 +206,7 @@ module RubyLLM
         # @return [String] the humanized model name
         def humanize(id)
           id.tr('-', ' ')
-            .split(' ')
+            .split
             .map(&:capitalize)
             .join(' ')
         end
@@ -229,12 +224,12 @@ module RubyLLM
             .gsub(/^Chatgpt /, 'ChatGPT-')
             .gsub(/^Tts /, 'TTS-')
             .gsub(/^Dall E /, 'DALL-E-')
-            .gsub(/3\.5 /, '3.5-')
-            .gsub(/4 /, '4-')
+            .gsub('3.5 ', '3.5-')
+            .gsub('4 ', '4-')
             .gsub(/4o (?=Mini|Preview|Turbo|Audio|Realtime)/, '4o-')
             .gsub(/\bHd\b/, 'HD')
-            .gsub(/Omni Moderation/, 'Omni-Moderation')
-            .gsub(/Text Moderation/, 'Text-Moderation')
+            .gsub('Omni Moderation', 'Omni-Moderation')
+            .gsub('Text Moderation', 'Text-Moderation')
         end
       end
     end

data/lib/ruby_llm/providers/openai/embeddings.rb

@@ -25,7 +25,7 @@ module RubyLLM
           vectors = data['data'].map { |d| d['embedding'] }
 
           # If we only got one embedding, return it as a single vector
-          vectors = vectors.size == 1 ? vectors.first : vectors
+          vectors = vectors.first if vectors.size == 1
 
           Embedding.new(
             vectors: vectors,

data/lib/ruby_llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  VERSION = '0.1.0.pre36'
+  VERSION = '0.1.0.pre37'
 end

data/lib/tasks/models.rake

@@ -70,8 +70,8 @@ namespace :models do # rubocop:disable Metrics/BlockLength
     RubyLLM.configure do |config|
       config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
       config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY')
-      config.gemini_api_key = ENV['GEMINI_API_KEY']
-      config.deepseek_api_key = ENV['DEEPSEEK_API_KEY']
+      config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)
+      config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
     end
 
     # Get all models

data/ruby_llm.gemspec

@@ -9,19 +9,21 @@ Gem::Specification.new do |spec|
   spec.email         = ['carmine@paolino.me']
 
   spec.summary       = 'Beautiful Ruby interface to modern AI'
-  spec.description   = 'A delightful Ruby way to work with AI. Chat in text, analyze and generate images, understand' \
-                       ' audio, and use tools through a unified interface to OpenAI, Anthropic, Google, and DeepSeek.' \
-                       ' Built for developer happiness with automatic token counting, proper streaming, and Rails' \
-                       ' integration. No wrapping your head around multiple APIs - just clean Ruby code that works.'
-  spec.homepage      = 'https://github.com/crmne/ruby_llm'
+  spec.description   = 'A delightful Ruby way to work with AI. Chat in text, analyze and generate images, understand ' \
+                       'audio, and use tools through a unified interface to OpenAI, Anthropic, Google, and DeepSeek. ' \
+                       'Built for developer happiness with automatic token counting, proper streaming, and Rails ' \
+                       'integration. No wrapping your head around multiple APIs - just clean Ruby code that works.'
+  spec.homepage      = 'https://rubyllm.com'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 3.1.0')
 
   spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = spec.homepage
-  spec.metadata['changelog_uri'] = "#{spec.homepage}/commits/main"
+  spec.metadata['source_code_uri'] = 'https://github.com/crmne/ruby_llm'
+  spec.metadata['changelog_uri'] = "#{spec.metadata['source_code_uri']}/commits/main"
   spec.metadata['documentation_uri'] = spec.homepage
-  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+  spec.metadata['bug_tracker_uri'] = "#{spec.metadata['source_code_uri']}/issues"
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -38,28 +40,4 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'faraday-multipart', '>= 1.0'
   spec.add_dependency 'faraday-retry', '>= 2.0'
   spec.add_dependency 'zeitwerk', '>= 2.6'
-
-  # Rails integration dependencies
-  spec.add_development_dependency 'activerecord', '>= 6.0', '< 9.0'
-  spec.add_development_dependency 'activesupport', '>= 6.0', '< 9.0'
-
-  # Development dependencies
-  spec.add_development_dependency 'bundler', '>= 2.0'
-  spec.add_development_dependency 'codecov'
-  spec.add_development_dependency 'dotenv'
-  spec.add_development_dependency 'irb'
-  spec.add_development_dependency 'nokogiri'
-  spec.add_development_dependency 'overcommit', '>= 0.66'
-  spec.add_development_dependency 'pry', '>= 0.14'
-  spec.add_development_dependency 'rake', '>= 13.0'
-  spec.add_development_dependency 'rdoc'
-  spec.add_development_dependency 'reline'
-  spec.add_development_dependency 'rspec', '~> 3.12'
-  spec.add_development_dependency 'rubocop', '>= 1.0'
-  spec.add_development_dependency 'rubocop-rake', '>= 0.6'
-  spec.add_development_dependency 'simplecov', '>= 0.21'
-  spec.add_development_dependency 'simplecov-cobertura'
-  spec.add_development_dependency 'sqlite3'
-  spec.add_development_dependency 'webmock', '~> 3.18'
-  spec.add_development_dependency 'yard', '>= 0.9'
 end