ruby_llm 0.1.0.pre41 → 0.1.0.pre43

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6a58fa5d1286364224b46aced4e7150aa935988ca5e6a5f5a12d760da76c214
-  data.tar.gz: 7d24ed72b786fea8b030191e796facd27c6ac6d45efe499ea2a25d3a5d01fab1
+  metadata.gz: b2433d0b669ef8bd499507edf33ed672d011fc1c95c2de0febd4e83d2593e0b8
+  data.tar.gz: a818a1c59220404c29c0e562c473480ac630a6fd53fadee65ab102b8955e9ec5
 SHA512:
-  metadata.gz: 293c57036acd3a7b0b5fdeda7866d0bf1599f52138aeac058bb248bc53d4b687caff047ab84aa57b1b50ae034e8cfb25729bd1e027af3febd1c50ce640bebf44
-  data.tar.gz: 762c75a2d0e7dc02829c2b7d7171c6fc57932656c72890ca0d1656fefc7d9d5cfa5989726ee40fa3b5d63cac81b1a2dc66c0439cb487272e70288718d993c21e
+  metadata.gz: afa3882a1850692e63f16dbc8c379a9aa71d704096f1eb2d5d88aeefa0c9c17f2585e8e215be0ed126caa0ec6bb7d07b4c12b5b6eaa5a1cf69a054b976b0d9e8
+  data.tar.gz: a8089658eab75b8200f51d39568dc876cdcc2d61d6581dbd1e6c211f487fa127c9300e0fcbb318f958b6b109f5fb43c2f7f6824acd2f426e4a0a9ae2a7023c63

data/.rspec_status

@@ -34,7 +34,8 @@ example_id                                         | status | run_time        |
 ./spec/ruby_llm/embeddings_spec.rb[1:1:1:2]        | passed | 0.43632 seconds |
 ./spec/ruby_llm/embeddings_spec.rb[1:1:2:1]        | passed | 0.65614 seconds |
 ./spec/ruby_llm/embeddings_spec.rb[1:1:2:2]        | passed | 2.16 seconds    |
-./spec/ruby_llm/error_handling_spec.rb[1:1]        | passed | 0.19586 seconds |
-./spec/ruby_llm/image_generation_spec.rb[1:1:1]    | passed | 12.77 seconds   |
-./spec/ruby_llm/image_generation_spec.rb[1:1:2]    | passed | 18.13 seconds   |
-./spec/ruby_llm/image_generation_spec.rb[1:1:3]    | passed | 0.00035 seconds |
+./spec/ruby_llm/error_handling_spec.rb[1:1]        | passed | 0.29366 seconds |
+./spec/ruby_llm/image_generation_spec.rb[1:1:1]    | passed | 11.61 seconds   |
+./spec/ruby_llm/image_generation_spec.rb[1:1:2]    | passed | 17.63 seconds   |
+./spec/ruby_llm/image_generation_spec.rb[1:1:3]    | passed | 8.77 seconds    |
+./spec/ruby_llm/image_generation_spec.rb[1:1:4]    | passed | 0.00319 seconds |

data/README.md

@@ -1,6 +1,6 @@
 # RubyLLM
 
-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.
+A delightful Ruby way to work with AI. No configuration madness, no complex callbacks, no handler hell – just beautiful, expressive Ruby code.
 
 <p align="center">
   <img src="https://upload.wikimedia.org/wikipedia/commons/4/4d/OpenAI_Logo.svg" alt="OpenAI" height="40" width="120">
@@ -15,446 +15,164 @@ A delightful Ruby way to work with AI. Chat in text, analyze and generate images
 <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://rubygems.org/gems/ruby_llm"><img alt="Gem Downloads" src="https://img.shields.io/gem/dt/ruby_llm"></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>
 
 🤺 Battle tested at [💬  Chat with Work](https://chatwithwork.com)
 
-## Features
+## The problem with AI libraries
 
-- 💬 **Beautiful Chat Interface** - Converse with AI models as easily as `RubyLLM.chat.ask "teach me Ruby"`
-- 📄 **PDF Analysis** - Analyze PDF documents directly with Claude models using `chat.ask "What's in this?", with: { pdf: "document.pdf" }`
-- 🎵 **Audio Analysis** - Get audio transcription and understanding with `chat.ask "what's said here?", with: { audio: "clip.wav" }`
-- 👁️ **Vision Understanding** - Let AIs analyze images with a simple `chat.ask "what's in this?", with: { image: "photo.jpg" }`
-- 🌊 **Streaming** - Real-time responses with proper Ruby streaming with `chat.ask "hello" do |chunk| puts chunk.content end`
-- 🚂 **Rails Integration** - Persist chats and messages with ActiveRecord with `acts_as_{chat|message|tool_call}`
-- 🛠️ **Tool Support** - Give AIs access to your Ruby code with `chat.with_tool(Calculator).ask "what's 2+2?"`
-- 🎨 **Paint with AI** - Create images as easily as `RubyLLM.paint "a sunset over mountains"`
-- 📊 **Embeddings** - Generate vector embeddings for your text with `RubyLLM.embed "hello"`
-- 🔄 **Multi-Provider Support** - Works with OpenAI, Anthropic, Google, and DeepSeek
-- 🎯 **Token Tracking** - Automatic usage tracking across providers
+Every AI provider comes with its own client library, its own response format, its own conventions for streaming, and its own way of handling errors. Want to use multiple providers? Prepare to juggle incompatible APIs and bloated dependencies.
 
-## Installation
-
-Add it to your Gemfile:
-
-```ruby
-gem 'ruby_llm'
-```
-
-Or install it yourself:
-
-```bash
-gem install ruby_llm
-```
-
-## Configuration
-
-```ruby
-require 'ruby_llm'
-
-# Configure your API keys
-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
-```
+RubyLLM fixes all that. One beautiful API for everything. One consistent format. Minimal dependencies — just Faraday and Zeitwerk. Because working with AI should be a joy, not a chore.
 
-## Quick Start
-
-RubyLLM makes it dead simple to start chatting with AI models:
+## What makes it great
 
 ```ruby
-# Start a conversation
+# Just ask questions
 chat = RubyLLM.chat
 chat.ask "What's the best way to learn Ruby?"
-```
 
-## Available Models
-
-RubyLLM gives you access to the latest models from multiple providers:
-
-```ruby
-# List all available models
-RubyLLM.models.all
-
-# Get models by type
-chat_models = RubyLLM.models.chat_models
-embedding_models = RubyLLM.models.embedding_models
-audio_models = RubyLLM.models.audio_models
-image_models = RubyLLM.models.image_models
-```
+# Analyze images
+chat.ask "What's in this image?", with: { image: "ruby_conf.jpg" }
 
-## Having a Conversation
+# Analyze audio recordings
+chat.ask "Describe this meeting", with: { audio: "meeting.wav" }
 
-Conversations are simple and natural:
-
-```ruby
-chat = RubyLLM.chat model: 'gemini-2.0-flash'
-
-# Ask questions
-response = chat.ask "What's your favorite Ruby feature?"
-
-# Multi-turn conversations just work
-chat.ask "Can you elaborate on that?"
-chat.ask "How does that compare to Python?"
-
-# Stream responses as they come
-chat.ask "Tell me a story about a Ruby programmer" do |chunk|
-  print chunk.content
-end
+# Analyze documents
+chat.ask "Summarize this document", with: { pdf: "contract.pdf" }
 
-# Ask about images
-chat.ask "What do you see in this image?", with: { image: "ruby_logo.png" }
+# Generate images
+RubyLLM.paint "a sunset over mountains in watercolor style"
 
-# Get analysis of audio content
-chat.ask "What's being said in this recording?", with: { audio: "meeting.wav" }
+# Create vector embeddings
+RubyLLM.embed "Ruby is elegant and expressive"
 
-# Combine multiple pieces of content
-chat.ask "Compare these diagrams", with: { image: ["diagram1.png", "diagram2.png"] }
-
-# Ask about PDFs (currently supported with Claude models)
-chat = RubyLLM.chat(model: 'claude-3-7-sonnet-20250219')
-chat.ask "Summarize this research paper", with: { pdf: "research.pdf" }
-
-# Multiple PDFs work too
-chat.ask "Compare these contracts", with: { pdf: ["contract1.pdf", "contract2.pdf"] }
-
-# Check token usage
-last_message = chat.messages.last
-puts "Conversation used #{last_message.input_tokens} input tokens and #{last_message.output_tokens} output tokens"
-```
-
-You can provide content as local files or URLs - RubyLLM handles the rest. Vision and audio capabilities are available with compatible models. The API stays clean and consistent whether you're working with text, images, or audio.
-
-## Image Generation
-
-Want to create AI-generated images? RubyLLM makes it super simple:
-
-```ruby
-# Paint a picture!
-image = RubyLLM.paint "a starry night over San Francisco in Van Gogh's style"
-image.url         # => "https://..."
-image.revised_prompt  # Shows how DALL-E interpreted your prompt
-
-# Choose size and model
-image = RubyLLM.paint(
-  "a cyberpunk cityscape at sunset",
-  model: "dall-e-3",
-  size: "1792x1024"
-)
-
-# Set your default model
-RubyLLM.configure do |config|
-  config.default_image_model = "dall-e-3"
-end
-```
-
-RubyLLM automatically handles all the complexities of the DALL-E API, token/credit management, and error handling, so you can focus on being creative.
-
-## Text Embeddings
-
-Need vector embeddings for your text? RubyLLM makes it simple:
-
-```ruby
-# Get embeddings with the default model
-RubyLLM.embed "Hello, world!"
-
-# Use a specific model
-RubyLLM.embed "Ruby is awesome!", model: "text-embedding-004"
-
-# Process multiple texts at once
-RubyLLM.embed([
-  "First document",
-  "Second document",
-  "Third document"
-])
-
-# Configure the default model
-RubyLLM.configure do |config|
-  config.default_embedding_model = 'text-embedding-3-large'
-end
-```
-
-## Using Tools
-
-Give your AI assistants access to your Ruby code by creating tool classes that do one thing well:
-
-```ruby
+# Let AI use your code
 class Calculator < RubyLLM::Tool
-  description "Performs arithmetic calculations"
-
-  param :expression,
-    type: :string,
-    desc: "A mathematical expression to evaluate (e.g. '2 + 2')"
+  description "Performs calculations"
+  param :expression, type: :string, desc: "Math expression to evaluate"
 
   def execute(expression:)
     eval(expression).to_s
   end
 end
 
-class Search < RubyLLM::Tool
-  description "Searches documents by similarity"
-
-  param :query,
-    desc: "The search query"
-
-  param :limit,
-    type: :integer,
-    desc: "Number of results to return",
-    required: false
-
-  def initialize(repo:)
-    @repo = repo
-  end
-
-  def execute(query:, limit: 5)
-    @repo.similarity_search(query, limit:)
-  end
-end
+chat.with_tool(Calculator).ask "What's 123 * 456?"
 ```
 
-Then use them in your conversations:
+## Installation
 
 ```ruby
-# Simple tools just work
-chat = RubyLLM.chat.with_tool Calculator
-
-# Tools with dependencies are just regular Ruby objects
-search = Search.new repo: Document
-chat.with_tools search, Calculator
-
-# Configure as needed
-chat.with_model('claude-3-5-sonnet-20241022')
-    .with_temperature(0.9)
+# In your Gemfile
+gem 'ruby_llm'
 
-chat.ask "What's 2+2?"
-# => "Let me calculate that for you. The result is 4."
+# Then run
+bundle install
 
-chat.ask "Find documents about Ruby performance"
-# => "I found these relevant documents about Ruby performance..."
+# Or install it yourself
+gem install ruby_llm
 ```
 
-Need to debug a tool? RubyLLM automatically logs all tool calls:
+Configure with your API keys:
 
 ```ruby
-ENV['RUBY_LLM_DEBUG'] = 'true'
-
-chat.ask "What's 123 * 456?"
-# D, -- RubyLLM: Tool calculator called with: {"expression" => "123 * 456"}
-# D, -- RubyLLM: Tool calculator returned: "56088"
+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'] # Optional
+end
 ```
 
-## Error Handling
-
-RubyLLM wraps provider errors in clear Ruby exceptions:
+## Have great conversations
 
 ```ruby
-begin
-  chat = RubyLLM.chat
-  chat.ask "Hello world!"
-rescue RubyLLM::UnauthorizedError
-  puts "Check your API credentials"
-rescue RubyLLM::BadRequestError => e
-  puts "Something went wrong: #{e.message}"
-rescue RubyLLM::PaymentRequiredError
-  puts "Time to top up your API credits"
-rescue RubyLLM::ServiceUnavailableError
-  puts "API service is temporarily down"
-end
-```
+# Start a chat with the default model (GPT-4o-mini)
+chat = RubyLLM.chat
 
-## Rails Integration
+# Or specify what you want
+chat = RubyLLM.chat(model: 'claude-3-7-sonnet-20250219')
 
-RubyLLM comes with built-in Rails support that makes it dead simple to persist your chats and messages. Just create your tables and hook it up:
+# Simple questions just work
+chat.ask "What's the difference between attr_reader and attr_accessor?"
 
-```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
+# Multi-turn conversations are seamless
+chat.ask "Could you give me an example?"
 
-# db/migrate/YYYYMMDDHHMMSS_create_messages.rb
-class CreateMessages < ActiveRecord::Migration[8.0]
-  def change
-    create_table :messages do |t|
-      t.references :chat, null: false
-      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
+# Stream responses in real-time
+chat.ask "Tell me a story about a Ruby programmer" do |chunk|
+  print chunk.content
 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
-      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
+# Understand content in multiple forms
+chat.ask "Compare these diagrams", with: { image: ["diagram1.png", "diagram2.png"] }
+chat.ask "Summarize this document", with: { pdf: "contract.pdf" }
+chat.ask "What's being said?", with: { audio: "meeting.wav" }
+
+# Need a different model mid-conversation? No problem
+chat.with_model('gemini-2.0-flash').ask "What's your favorite algorithm?"
 ```
 
-Then in your models:
+## Rails integration that makes sense
 
 ```ruby
+# app/models/chat.rb
 class Chat < ApplicationRecord
   acts_as_chat
 
-  # Optional: Add Turbo Streams support
+  # Works great with Turbo
   broadcasts_to ->(chat) { "chat_#{chat.id}" }
 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
-```
 
-That's it! Now you can use chats straight from your models:
-
-```ruby
-# Create a new chat
-chat = Chat.create! model_id: "gpt-4o-mini"
-
-# Ask questions - messages are automatically saved
-chat.ask "What's the weather in Paris?"
-
-# Stream responses in real-time
-chat.ask "Tell me a story" do |chunk|
-  broadcast_chunk chunk
+# In your controller
+chat = Chat.create!(model_id: "gpt-4o-mini")
+chat.ask("What's your favorite Ruby gem?") do |chunk|
+  Turbo::StreamsChannel.broadcast_append_to(
+    chat,
+    target: "response",
+    partial: "messages/chunk",
+    locals: { chunk: chunk }
+  )
 end
 
-# Everything is persisted automatically
-chat.messages.each do |message|
-  case message.role
-  when :user
-    puts "User: #{message.content}"
-  when :assistant
-    puts "Assistant: #{message.content}"
-  end
-end
+# That's it - chat history is automatically saved
 ```
 
-### Real-time Updates with Hotwire
-
-The Rails integration works great with Hotwire out of the box:
+## Creating tools is a breeze
 
 ```ruby
-# app/controllers/chats_controller.rb
-class ChatsController < ApplicationController
-  def show
-    @chat = Chat.find(params[:id])
-  end
-
-  def ask
-    @chat = Chat.find(params[:id])
-    @chat.ask(params[:message]) do |chunk|
-      Turbo::StreamsChannel.broadcast_append_to(
-        @chat,
-        target: "messages",
-        partial: "messages/chunk",
-        locals: { chunk: chunk }
-      )
-    end
-  end
-end
-
-# app/views/chats/show.html.erb
-<%= turbo_stream_from @chat %>
-
-<div id="messages">
-  <%= render @chat.messages %>
-</div>
-
-<%= form_with(url: ask_chat_path(@chat), local: false) do |f| %>
-  <%= f.text_area :message %>
-  <%= f.submit "Send" %>
-<% end %>
-```
-
-### Background Jobs
-
-The persistence works seamlessly with background jobs:
-
-```ruby
-class ChatJob < ApplicationJob
-  def perform(chat_id, message)
-    chat = Chat.find chat_id
-
-    chat.ask(message) do |chunk|
-      # Optional: Broadcast chunks for real-time updates
-      Turbo::StreamsChannel.broadcast_append_to(
-        chat,
-        target: "messages",
-        partial: "messages/chunk",
-        locals: { chunk: chunk }
-      )
-    end
-  end
-end
-```
-
-### Using Tools
-
-Tools work just like they do in regular RubyLLM chats:
-
-```ruby
-class WeatherTool < RubyLLM::Tool
-  description "Gets current weather for a location"
+class Search < RubyLLM::Tool
+  description "Searches a knowledge base"
 
-  param :location,
-    type: :string,
-    desc: "City name or coordinates"
+  param :query, desc: "The search query"
+  param :limit, type: :integer, desc: "Max results", required: false
 
-  def execute(location:)
-    # Fetch weather data...
-    { temperature: 22, conditions: "Sunny" }
+  def execute(query:, limit: 5)
+    # Your search logic here
+    Document.search(query).limit(limit).map(&:title)
   end
 end
 
-# Use tools with your persisted chats
-chat = Chat.create! model_id: "deepseek-reasoner"
-chat.chat.with_tool WeatherTool.new
-
-# Ask about weather - tool usage is automatically saved
-chat.ask "What's the weather in Paris?"
-
-# Tool calls and results are persisted as messages
-pp chat.messages.map(&:role)
-#=> [:user, :assistant, :tool, :assistant]
+# Let the AI use it
+chat.with_tool(Search).ask "Find documents about Ruby 3.3 features"
 ```
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt.
-
-## Contributing
+## Learn more
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/crmne/ruby_llm.
+Check out the guides at https://rubyllm.com for deeper dives into conversations with tools, streaming responses, embedding generations, and more.
 
 ## License
 
-Released under the MIT License. See [LICENSE](LICENSE) for details.
+Released under the MIT License.

data/lib/ruby_llm/content.rb

@@ -68,7 +68,7 @@ module RubyLLM
       }
     end
 
-    def attach_pdf(source) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+    def attach_pdf(source)
       source = File.expand_path(source) unless source.start_with?('http')
 
       pdf_data = {
@@ -80,19 +80,11 @@ module RubyLLM
       unless source.start_with?('http')
         raise Error, "PDF file not found: #{source}" unless File.exist?(source)
 
-        # Simple check for PDF file type (could be more robust)
-        unless source.downcase.end_with?('.pdf') || File.read(source, 5) == '%PDF-'
-          RubyLLM.logger.warn "File may not be a valid PDF: #{source}"
-        end
-
         # Preload file content for providers that need it
         pdf_data[:content] = File.read(source)
       end
 
       pdf_data
-    rescue StandardError => e
-      RubyLLM.logger.error "Error attaching PDF #{source}: #{e.message}"
-      raise Error, "Failed to attach PDF: #{e.message}"
     end
 
     def encode_file(source)