ruby_llm 0.1.0.pre36 → 0.1.0.pre38

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,73 @@
+---
+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

@@ -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/models.json

@@ -23,7 +23,7 @@
     "created_at": "2023-08-21T18:16:55+02:00",
     "display_name": "Babbage 002",
     "provider": "openai",
-    "context_window": 16384,
+    "context_window": 16385,
     "max_tokens": 16384,
     "type": "chat",
     "family": "babbage",
@@ -262,7 +262,7 @@
     "created_at": "2023-08-21T18:11:41+02:00",
     "display_name": "Davinci 002",
     "provider": "openai",
-    "context_window": 16384,
+    "context_window": 16385,
     "max_tokens": 16384,
     "type": "chat",
     "family": "davinci",
@@ -287,7 +287,7 @@
     "family": "chat",
     "supports_vision": false,
     "supports_functions": true,
-    "supports_json_mode": true,
+    "supports_json_mode": false,
     "input_price_per_million": 0.27,
     "output_price_per_million": 1.1,
     "metadata": {
@@ -371,63 +371,6 @@
       "owned_by": "google"
     }
   },
-  {
-    "id": "gemini-1.0-pro",
-    "created_at": null,
-    "display_name": "Gemini 1.0 Pro",
-    "provider": "gemini",
-    "context_window": 32768,
-    "max_tokens": 4096,
-    "type": "chat",
-    "family": "gemini10_pro",
-    "supports_vision": false,
-    "supports_functions": false,
-    "supports_json_mode": false,
-    "input_price_per_million": 0.5,
-    "output_price_per_million": 1.5,
-    "metadata": {
-      "object": "model",
-      "owned_by": "google"
-    }
-  },
-  {
-    "id": "gemini-1.0-pro-001",
-    "created_at": null,
-    "display_name": "Gemini 1.0 Pro 001",
-    "provider": "gemini",
-    "context_window": 32768,
-    "max_tokens": 4096,
-    "type": "chat",
-    "family": "gemini10_pro",
-    "supports_vision": false,
-    "supports_functions": false,
-    "supports_json_mode": false,
-    "input_price_per_million": 0.5,
-    "output_price_per_million": 1.5,
-    "metadata": {
-      "object": "model",
-      "owned_by": "google"
-    }
-  },
-  {
-    "id": "gemini-1.0-pro-latest",
-    "created_at": null,
-    "display_name": "Gemini 1.0 Pro Latest",
-    "provider": "gemini",
-    "context_window": 32768,
-    "max_tokens": 4096,
-    "type": "chat",
-    "family": "gemini10_pro",
-    "supports_vision": false,
-    "supports_functions": false,
-    "supports_json_mode": false,
-    "input_price_per_million": 0.5,
-    "output_price_per_million": 1.5,
-    "metadata": {
-      "object": "model",
-      "owned_by": "google"
-    }
-  },
   {
     "id": "gemini-1.0-pro-vision-latest",
     "created_at": null,
@@ -884,44 +827,6 @@
       "owned_by": "google"
     }
   },
-  {
-    "id": "gemini-2.0-flash-lite-preview",
-    "created_at": null,
-    "display_name": "Gemini 2.0 Flash Lite Preview",
-    "provider": "gemini",
-    "context_window": 1048576,
-    "max_tokens": 8192,
-    "type": "chat",
-    "family": "gemini20_flash_lite",
-    "supports_vision": true,
-    "supports_functions": false,
-    "supports_json_mode": false,
-    "input_price_per_million": 0.075,
-    "output_price_per_million": 0.3,
-    "metadata": {
-      "object": "model",
-      "owned_by": "google"
-    }
-  },
-  {
-    "id": "gemini-2.0-flash-lite-preview-02-05",
-    "created_at": null,
-    "display_name": "Gemini 2.0 Flash Lite Preview 02 05",
-    "provider": "gemini",
-    "context_window": 1048576,
-    "max_tokens": 8192,
-    "type": "chat",
-    "family": "gemini20_flash_lite",
-    "supports_vision": true,
-    "supports_functions": false,
-    "supports_json_mode": false,
-    "input_price_per_million": 0.075,
-    "output_price_per_million": 0.3,
-    "metadata": {
-      "object": "model",
-      "owned_by": "google"
-    }
-  },
   {
     "id": "gemini-2.0-flash-mmgen-rev17",
     "created_at": null,
@@ -1093,25 +998,6 @@
       "owned_by": "google"
     }
   },
-  {
-    "id": "gemini-pro",
-    "created_at": null,
-    "display_name": "Gemini Pro",
-    "provider": "gemini",
-    "context_window": 32768,
-    "max_tokens": 4096,
-    "type": "chat",
-    "family": "other",
-    "supports_vision": false,
-    "supports_functions": false,
-    "supports_json_mode": false,
-    "input_price_per_million": 0.075,
-    "output_price_per_million": 0.3,
-    "metadata": {
-      "object": "model",
-      "owned_by": "google"
-    }
-  },
   {
     "id": "gemini-pro-vision",
     "created_at": null,
@@ -1212,7 +1098,7 @@
     "created_at": "2024-01-23T23:19:18+01:00",
     "display_name": "GPT-3.5-Turbo 0125",
     "provider": "openai",
-    "context_window": 16385,
+    "context_window": 4096,
     "max_tokens": 4096,
     "type": "chat",
     "family": "gpt35",
@@ -1231,7 +1117,7 @@
     "created_at": "2023-11-02T22:15:48+01:00",
     "display_name": "GPT-3.5-Turbo 1106",
     "provider": "openai",
-    "context_window": 16385,
+    "context_window": 4096,
     "max_tokens": 4096,
     "type": "chat",
     "family": "gpt35",
@@ -1460,7 +1346,7 @@
     "display_name": "GPT-4o 20240513",
     "provider": "openai",
     "context_window": 128000,
-    "max_tokens": 4096,
+    "max_tokens": 16384,
     "type": "chat",
     "family": "gpt4o",
     "supports_vision": true,
@@ -1650,7 +1536,7 @@
     "display_name": "GPT-4o-Mini Realtime Preview",
     "provider": "openai",
     "context_window": 128000,
-    "max_tokens": 4096,
+    "max_tokens": 16384,
     "type": "chat",
     "family": "gpt4o_mini_realtime",
     "supports_vision": true,
@@ -1669,7 +1555,7 @@
     "display_name": "GPT-4o-Mini Realtime Preview 20241217",
     "provider": "openai",
     "context_window": 128000,
-    "max_tokens": 4096,
+    "max_tokens": 16384,
     "type": "chat",
     "family": "gpt4o_mini_realtime",
     "supports_vision": true,
@@ -1688,7 +1574,7 @@
     "display_name": "GPT-4o-Realtime Preview",
     "provider": "openai",
     "context_window": 128000,
-    "max_tokens": 4096,
+    "max_tokens": 16384,
     "type": "chat",
     "family": "gpt4o_realtime",
     "supports_vision": true,
@@ -1707,7 +1593,7 @@
     "display_name": "GPT-4o-Realtime Preview 20241001",
     "provider": "openai",
     "context_window": 128000,
-    "max_tokens": 4096,
+    "max_tokens": 16384,
     "type": "chat",
     "family": "gpt4o_realtime",
     "supports_vision": true,
@@ -1726,7 +1612,7 @@
     "display_name": "GPT-4o-Realtime Preview 20241217",
     "provider": "openai",
     "context_window": 128000,
-    "max_tokens": 4096,
+    "max_tokens": 16384,
     "type": "chat",
     "family": "gpt4o_realtime",
     "supports_vision": true,