ruby_llm 0.1.0.pre13 → 0.1.0.pre14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 325d22d60cd9f0a4157670442830fe2473e8e46879ee672d0e56207f6b3b8e72
-  data.tar.gz: 355be22334837f40ac717974058d4cceb4d46dd13e36a808c11410a9c4624dc0
+  metadata.gz: 634e727da013e56b973856876d2b456075841bd3cd1f9a5939d2028d96a47b38
+  data.tar.gz: af14dd677a8718883f0bc7c555272b5a894457d472edae1e0a4c44de8d9934ba
 SHA512:
-  metadata.gz: a7ea97dbe171c7f62df442134b613c84ec277dffcdf1e86fafeed14a95c7ba2545b950d454153606e205f13ffd5a79a9e6e8158d1f053be51a915bbfb03d4806
-  data.tar.gz: bb20ec1351e7597550283b7b7b2b1dff50a26ceba1b123b5fabd8636150f2fae5eb935dac51153448895b7782cdbb85575c25a671064928a8c83465489bea6b9
+  metadata.gz: 9c1dcc9ac485aa9f85592c0dd12d2bfe3894bfbd7311f19a1168ed17289d21edc14c636532212b01e544365519477314e03be0b34d238f2f6390834ac0a280c7
+  data.tar.gz: 9e4db61a0e5e73d13d7b8a03149625e463f7eb52d181acfc8f3ce06db0a7294615cf17f0bdbcced5f5a2908aa503af3fbc6c0122541ad704f1ddb4d17ea3b494

data/.github/workflows/test.yml

@@ -28,8 +28,8 @@ jobs:
     - name: Install dependencies
       run: bundle install
 
-    # - name: Check code format
-    #   run: bundle exec rubocop
+    - name: Check code format
+      run: bundle exec rubocop
 
     # - name: Run tests
     #   run: bundle exec rspec

data/README.md

@@ -54,14 +54,13 @@ image_models = RubyLLM.models.image_models
 
 ## Having a Conversation
 
-Conversations are simple and natural, with automatic token counting built right in:
+Conversations are simple and natural:
 
 ```ruby
 chat = RubyLLM.chat model: 'claude-3-5-sonnet-20241022'
 
-# Single messages with token tracking
+# Ask questions
 response = chat.ask "What's your favorite Ruby feature?"
-puts "Response used #{response.input_tokens} input tokens and #{response.output_tokens} output tokens"
 
 # Multi-turn conversations just work
 chat.ask "Can you elaborate on that?"
@@ -72,7 +71,7 @@ chat.ask "Tell me a story about a Ruby programmer" do |chunk|
   print chunk.content
 end
 
-# Get token usage for the whole conversation from the last message
+# Check token usage
 last_message = chat.messages.last
 puts "Conversation used #{last_message.input_tokens} input tokens and #{last_message.output_tokens} output tokens"
 ```
@@ -123,9 +122,9 @@ chat = RubyLLM.chat.with_tool Calculator
 
 # Tools with dependencies are just regular Ruby objects
 search = Search.new repo: Document
-chat.with_tools search, CalculatorTool
+chat.with_tools search, Calculator
 
-# Need more control? Configure as needed
+# Configure as needed
 chat.with_model('claude-3-5-sonnet-20241022')
     .with_temperature(0.9)
 
@@ -136,9 +135,7 @@ chat.ask "Find documents about Ruby performance"
 # => "I found these relevant documents about Ruby performance..."
 ```
 
-Tools let you seamlessly integrate your Ruby code with AI capabilities. The model will automatically decide when to use your tools and handle the results appropriately.
-
-Need to debug a tool? RubyLLM automatically logs all tool calls and their results when debug logging is enabled:
+Need to debug a tool? RubyLLM automatically logs all tool calls:
 
 ```ruby
 ENV['RUBY_LLM_DEBUG'] = 'true'
@@ -148,13 +145,169 @@ chat.ask "What's 123 * 456?"
 # D, -- RubyLLM: Tool calculator returned: "56088"
 ```
 
-Create tools for anything - database queries, API calls, custom business logic - and let Claude use them naturally in conversation.
+## Rails Integration
+
+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:
+
+```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
+      t.string :role
+      t.text :content
+      t.json :tool_calls
+      t.string :tool_call_id
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.string :model_id
+      t.timestamps
+    end
+  end
+end
+```
+
+Then in your models:
+
+```ruby
+class Chat < ApplicationRecord
+  acts_as_chat message_class: "Message"
+
+  # Optional: Add Turbo Streams support
+  broadcasts_to ->(chat) { "chat_#{chat.id}" }
+end
+
+class Message < ApplicationRecord
+  acts_as_message chat_class: "Chat"
+end
+```
+
+That's it! Now you can use chats straight from your models:
+
+```ruby
+# Create a new chat
+chat = Chat.create!(model_id: "gpt-4")
+
+# 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)
+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
+```
+
+### Real-time Updates with Hotwire
+
+The Rails integration works great with Hotwire out of the box:
 
-## Coming Soon
+```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"
+
+  param :location,
+    type: :string,
+    desc: "City name or coordinates"
+
+  def execute(location:)
+    # Fetch weather data...
+    { temperature: 22, conditions: "Sunny" }
+  end
+end
+
+# Use tools with your persisted chats
+chat = Chat.create!(model_id: "gpt-4")
+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]
+```
 
-- Rails integration for seamless database and Active Record support
-- Automatic retries and error handling
-- Much more!
+Looking for more examples? Check out the [example Rails app](https://github.com/example/ruby_llm_rails) showing these patterns in action!
 
 ## Development
 

data/lib/ruby_llm/active_record/acts_as.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Adds chat and message persistence capabilities to ActiveRecord models.
+    # Provides a clean interface for storing chat history and message metadata
+    # in your database.
+    module ActsAs
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def acts_as_chat(message_class:)
+          include ChatMethods
+
+          has_many :messages,
+                   -> { order(created_at: :asc) },
+                   class_name: message_class.to_s,
+                   dependent: :destroy
+
+          # No more callback config - just expose the core chat functionality
+          delegate :ask, :say, :complete, to: :chat
+        end
+
+        def acts_as_message(chat_class:)
+          include MessageMethods
+
+          belongs_to :chat, class_name: chat_class.to_s
+
+          serialize :tool_calls, coder: JSON
+        end
+      end
+    end
+
+    # Methods mixed into chat models to handle message persistence and
+    # provide a conversation interface.
+    module ChatMethods
+      extend ActiveSupport::Concern
+
+      def chat
+        @chat ||= begin
+          chat = RubyLLM.chat(model: model_id)
+
+          # Load existing messages into chat
+          messages.each do |msg|
+            chat.add_message(msg.to_llm)
+          end
+
+          # Set up message persistence
+          chat.on_new_message { |msg| persist_new_message(msg) }
+              .on_end_message { |msg| persist_message_completion(msg) }
+
+          chat
+        end
+      end
+
+      private
+
+      def persist_new_message(message)
+        return unless message
+
+        messages.create!(
+          role: message.role,
+          content: message.content,
+          tool_calls: message.tool_calls,
+          tool_call_id: message.tool_call_id,
+          model_id: message.model_id
+        )
+      end
+
+      def persist_message_completion(message)
+        return unless message
+
+        messages.last.update!(
+          content: message.content,
+          tool_calls: message.tool_calls,
+          input_tokens: message.input_tokens,
+          output_tokens: message.output_tokens
+        )
+      end
+    end
+
+    # Methods mixed into message models to handle serialization and
+    # provide a clean interface to the underlying message data.
+    module MessageMethods
+      extend ActiveSupport::Concern
+
+      def to_llm
+        RubyLLM::Message.new(
+          role: role.to_sym,
+          content: content,
+          tool_calls: tool_calls,
+          tool_call_id: tool_call_id,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          model_id: model_id
+        )
+      end
+    end
+  end
+end

data/lib/ruby_llm/chat.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # Represents a conversation with an AI model. Handles message history,
+  # streaming responses, and tool integration with a simple, conversational API.
+  #
+  # Example:
+  #   chat = RubyLLM.chat
+  #   chat.ask "What's the best way to learn Ruby?"
+  #   chat.ask "Can you elaborate on that?"
   class Chat
     include Enumerable
 
@@ -8,13 +15,14 @@ module RubyLLM
 
     def initialize(model: nil)
       model_id = model || RubyLLM.config.default_model
-      @model = Models.find model_id
-      @provider = Models.provider_for model_id
+      self.model = model_id
       @temperature = 0.7
       @messages = []
       @tools = {}
-
-      ensure_valid_tools
+      @on = {
+        new_message: nil,
+        end_message: nil
+      }
     end
 
     def ask(message, &block)
@@ -37,9 +45,13 @@ module RubyLLM
       self
     end
 
-    def with_model(model_id)
+    def model=(model_id)
       @model = Models.find model_id
       @provider = Models.provider_for model_id
+    end
+
+    def with_model(model_id)
+      self.model = model_id
       self
     end
 
@@ -48,14 +60,24 @@ module RubyLLM
       self
     end
 
+    def on_new_message(&block)
+      @on[:new_message] = block
+      self
+    end
+
+    def on_end_message(&block)
+      @on[:end_message] = block
+      self
+    end
+
     def each(&block)
       messages.each(&block)
     end
 
-    private
-
     def complete(&block)
-      response = @provider.complete messages, tools: @tools, temperature: @temperature, model: @model.id, &block
+      @on[:new_message]&.call
+      response = @provider.complete(messages, tools: @tools, temperature: @temperature, model: @model.id, &block)
+      @on[:end_message]&.call(response)
 
       add_message response
       if response.tool_call?
@@ -65,6 +87,8 @@ module RubyLLM
       end
     end
 
+    private
+
     def handle_tool_calls(response, &block)
       response.tool_calls.each_value do |tool_call|
         result = execute_tool tool_call
@@ -82,6 +106,7 @@ module RubyLLM
 
     def add_message(message_or_attributes)
       message = message_or_attributes.is_a?(Message) ? message_or_attributes : Message.new(message_or_attributes)
+      # TODO: callback
       messages << message
       message
     end
@@ -93,13 +118,5 @@ module RubyLLM
         tool_call_id: tool_use_id
       )
     end
-
-    def ensure_valid_tools
-      tools.each_key do |name|
-        unless name.is_a?(Symbol) && tools[name].is_a?(RubyLLM::Tool)
-          raise Error, 'Tools should be of the format {<name.to_sym>: <RubyLLM::Tool>}'
-        end
-      end
-    end
   end
 end

data/lib/ruby_llm/configuration.rb

@@ -1,6 +1,14 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # Global configuration for RubyLLM. Manages API keys, default models,
+  # and provider-specific settings.
+  #
+  # Configure via:
+  #   RubyLLM.configure do |config|
+  #     config.openai_api_key = ENV['OPENAI_API_KEY']
+  #     config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+  #   end
   class Configuration
     attr_accessor :openai_api_key, :anthropic_api_key, :default_model, :request_timeout
 
@@ -8,17 +16,5 @@ module RubyLLM
       @request_timeout = 30
       @default_model = 'gpt-4o-mini'
     end
-
-    def provider_settings
-      @provider_settings ||= {
-        openai: ProviderSettings.new,
-        anthropic: ProviderSettings.new
-      }
-    end
-  end
-
-  # Settings specific to individual LLM providers
-  class ProviderSettings
-    attr_accessor :api_key, :api_version, :default_model, :base_url
   end
 end

data/lib/ruby_llm/message.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # A single message in a chat conversation. Can represent user input,
+  # AI responses, or tool interactions. Tracks token usage and handles
+  # the complexities of tool calls and responses.
   class Message
     ROLES = %i[system user assistant tool].freeze
 

data/lib/ruby_llm/model_capabilities/anthropic.rb

@@ -2,6 +2,7 @@
 
 module RubyLLM
   module ModelCapabilities
+    # Determines capabilities and pricing for Anthropic models
     module Anthropic
       extend self
 

data/lib/ruby_llm/model_capabilities/openai.rb

@@ -2,6 +2,7 @@
 
 module RubyLLM
   module ModelCapabilities
+    # Determines capabilities and pricing for OpenAI models
     module OpenAI
       extend self
 
@@ -56,16 +57,15 @@ module RubyLLM
 
       private
 
-      def model_family(model_id)
+      def model_family(model_id) # rubocop:disable Metrics/CyclomaticComplexity
         case model_id
-        when /o1-2024/                   then :o1
-        when /o1-mini/                   then :o1_mini
-        when /gpt-4o-realtime-preview/   then :gpt4o_realtime
-        when /gpt-4o-mini-realtime/      then :gpt4o_mini_realtime
-        when /gpt-4o-mini/               then :gpt4o_mini
-        when /gpt-4o/                    then :gpt4o
-        when /gpt-4-turbo/               then :gpt4_turbo
-        when /gpt-3.5/                   then :gpt35
+        when /o1-2024/                then :o1
+        when /o1-mini/                then :o1_mini
+        when /gpt-4o-realtime/        then :gpt4o_realtime
+        when /gpt-4o-mini-realtime/   then :gpt4o_mini_realtime
+        when /gpt-4o-mini/            then :gpt4o_mini
+        when /gpt-4o/                 then :gpt4o
+        when /gpt-4-turbo/            then :gpt4_turbo
         else :gpt35
         end
       end
@@ -96,7 +96,7 @@ module RubyLLM
           .join(' ')
       end
 
-      def apply_special_formatting(name)
+      def apply_special_formatting(name) # rubocop:disable Metrics/MethodLength
         name
           .gsub(/(\d{4}) (\d{2}) (\d{2})/, '\1\2\3')
           .gsub(/^Gpt /, 'GPT-')

data/lib/ruby_llm/model_info.rb

@@ -3,12 +3,21 @@
 require 'time'
 
 module RubyLLM
+  # Information about an AI model's capabilities, pricing, and metadata.
+  # Used by the Models registry to help developers choose the right model
+  # for their needs.
+  #
+  # Example:
+  #   model = RubyLLM.models.find('gpt-4')
+  #   model.supports_vision?          # => true
+  #   model.supports_functions?       # => true
+  #   model.input_price_per_million   # => 30.0
   class ModelInfo
     attr_reader :id, :created_at, :display_name, :provider, :metadata,
                 :context_window, :max_tokens, :supports_vision, :supports_functions,
                 :supports_json_mode, :input_price_per_million, :output_price_per_million
 
-    def initialize(data)
+    def initialize(data) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
       @id = data[:id]
       @created_at = data[:created_at].is_a?(String) ? Time.parse(data[:created_at]) : data[:created_at]
       @display_name = data[:display_name]
@@ -23,7 +32,7 @@ module RubyLLM
       @metadata = data[:metadata] || {}
     end
 
-    def to_h
+    def to_h # rubocop:disable Metrics/MethodLength
       {
         id: id,
         created_at: created_at.iso8601,

data/lib/ruby_llm/models.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # Registry of available AI models and their capabilities. Provides a clean interface
+  # to discover and work with models from different providers.
+  #
+  # Example:
+  #   RubyLLM.models.all                  # All available models
+  #   RubyLLM.models.chat_models          # Models that support chat
+  #   RubyLLM.models.find('claude-3')     # Get info about a specific model
   module Models
     module_function
 

data/lib/ruby_llm/provider.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # Base interface for LLM providers like OpenAI and Anthropic.
+  # Handles the complexities of API communication, streaming responses,
+  # and error handling so individual providers can focus on their unique features.
   module Provider
     def self.included(base)
       base.include(InstanceMethods)
     end
 
+    # Common functionality for all LLM providers. Implements the core provider
+    # interface so specific providers only need to implement a few key methods.
     module InstanceMethods
       def complete(messages, tools:, temperature:, model:, &block)
         payload = build_payload messages, tools: tools, temperature: temperature, model: model, stream: block_given?

data/lib/ruby_llm/providers/anthropic.rb

@@ -2,7 +2,9 @@
 
 module RubyLLM
   module Providers
-    class Anthropic
+    # Anthropic Claude API integration. Handles the complexities of
+    # Claude's unique message format and tool calling conventions.
+    class Anthropic # rubocop:disable Metrics/ClassLength
       include Provider
 
       private
@@ -42,32 +44,33 @@ module RubyLLM
         data = response.body
         content_blocks = data['content'] || []
 
-        text_blocks = content_blocks.select { |c| c['type'] == 'text' }
-        text_content = text_blocks.map { |c| c['text'] }.join('')
+        text_content = extract_text_content(content_blocks)
+        tool_use = find_tool_use(content_blocks)
 
-        tool_use = content_blocks.find { |c| c['type'] == 'tool_use' }
+        build_message(data, text_content, tool_use)
+      end
 
-        if tool_use
-          Message.new(
-            role: :assistant,
-            content: text_content,
-            tool_calls: parse_tool_calls(tool_use),
-            input_tokens: data.dig('usage', 'input_tokens'),
-            output_tokens: data.dig('usage', 'output_tokens'),
-            model_id: data['model']
-          )
-        else
-          Message.new(
-            role: :assistant,
-            content: text_content,
-            input_tokens: data.dig('usage', 'input_tokens'),
-            output_tokens: data.dig('usage', 'output_tokens'),
-            model_id: data['model']
-          )
-        end
+      def extract_text_content(blocks)
+        text_blocks = blocks.select { |c| c['type'] == 'text' }
+        text_blocks.map { |c| c['text'] }.join('')
+      end
+
+      def find_tool_use(blocks)
+        blocks.find { |c| c['type'] == 'tool_use' }
       end
 
-      def parse_models_response(response)
+      def build_message(data, content, tool_use)
+        Message.new(
+          role: :assistant,
+          content: content,
+          tool_calls: parse_tool_calls(tool_use),
+          input_tokens: data.dig('usage', 'input_tokens'),
+          output_tokens: data.dig('usage', 'output_tokens'),
+          model_id: data['model']
+        )
+      end
+
+      def parse_models_response(response) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         capabilities = ModelCapabilities::Anthropic.new
 
         (response.body['data'] || []).map do |model|
@@ -90,32 +93,45 @@ module RubyLLM
 
       def handle_stream(&block)
         to_json_stream do |data|
-          if data['type'] == 'content_block_delta' && data.dig('delta', 'type') == 'input_json_delta'
-            block.call(
-              Chunk.new(
-                role: :assistant,
-                model_id: data.dig('message', 'model'),
-                content: data.dig('delta', 'text'),
-                input_tokens: data.dig('message', 'usage', 'input_tokens'),
-                output_tokens: data.dig('message', 'usage', 'output_tokens') || data.dig('usage', 'output_tokens'),
-                tool_calls: { nil => ToolCall.new(id: nil, name: nil, arguments: data.dig('delta', 'partial_json')) }
-              )
-            )
-          else
-            block.call(
-              Chunk.new(
-                role: :assistant,
-                model_id: data.dig('message', 'model'),
-                content: data.dig('delta', 'text'),
-                input_tokens: data.dig('message', 'usage', 'input_tokens'),
-                output_tokens: data.dig('message', 'usage', 'output_tokens') || data.dig('usage', 'output_tokens'),
-                tool_calls: parse_tool_calls(data['content_block'])
-              )
-            )
-          end
+          block.call(build_chunk(data))
+        end
+      end
+
+      def build_chunk(data)
+        Chunk.new(
+          role: :assistant,
+          model_id: extract_model_id(data),
+          content: data.dig('delta', 'text'),
+          input_tokens: extract_input_tokens(data),
+          output_tokens: extract_output_tokens(data),
+          tool_calls: extract_tool_calls(data)
+        )
+      end
+
+      def extract_model_id(data)
+        data.dig('message', 'model')
+      end
+
+      def extract_input_tokens(data)
+        data.dig('message', 'usage', 'input_tokens')
+      end
+
+      def extract_output_tokens(data)
+        data.dig('message', 'usage', 'output_tokens') || data.dig('usage', 'output_tokens')
+      end
+
+      def extract_tool_calls(data)
+        if json_delta?(data)
+          { nil => ToolCall.new(id: nil, name: nil, arguments: data.dig('delta', 'partial_json')) }
+        else
+          parse_tool_calls(data['content_block'])
         end
       end
 
+      def json_delta?(data)
+        data['type'] == 'content_block_delta' && data.dig('delta', 'type') == 'input_json_delta'
+      end
+
       def parse_tool_calls(content_block)
         return nil unless content_block && content_block['type'] == 'tool_use'
 
@@ -141,43 +157,69 @@ module RubyLLM
       end
 
       def format_messages(messages)
-        messages.map do |msg|
-          if msg.tool_call?
-            {
-              role: 'assistant',
-              content: [
-                {
-                  type: 'text',
-                  text: msg.content
-                },
-                {
-                  type: 'tool_use',
-                  id: msg.tool_calls.values.first.id,
-                  name: msg.tool_calls.values.first.name,
-                  input: msg.tool_calls.values.first.arguments
-                }
-              ]
-            }
-          elsif msg.tool_result?
-            {
-              role: 'user',
-              content: [
-                {
-                  type: 'tool_result',
-                  tool_use_id: msg.tool_call_id,
-                  content: msg.content
-                }
-              ]
-            }
-          else
-            {
-              role: convert_role(msg.role),
-              content: msg.content
-            }
-          end
+        messages.map { |msg| format_message(msg) }
+      end
+
+      def format_message(msg)
+        if msg.tool_call?
+          format_tool_call(msg)
+        elsif msg.tool_result?
+          format_tool_result(msg)
+        else
+          format_basic_message(msg)
         end
       end
 
+      def format_tool_call(msg)
+        tool_call = msg.tool_calls.values.first
+
+        {
+          role: 'assistant',
+          content: [
+            format_text_block(msg.content),
+            format_tool_use_block(tool_call)
+          ]
+        }
+      end
+
+      def format_tool_result(msg)
+        {
+          role: 'user',
+          content: [format_tool_result_block(msg)]
+        }
+      end
+
+      def format_basic_message(msg)
+        {
+          role: convert_role(msg.role),
+          content: msg.content
+        }
+      end
+
+      def format_text_block(content)
+        {
+          type: 'text',
+          text: content
+        }
+      end
+
+      def format_tool_use_block(tool_call)
+        {
+          type: 'tool_use',
+          id: tool_call.id,
+          name: tool_call.name,
+          input: tool_call.arguments
+        }
+      end
+
+      def format_tool_result_block(msg)
+        {
+          type: 'tool_result',
+          tool_use_id: msg.tool_call_id,
+          content: msg.content
+        }
+      end
+
       def convert_role(role)
         case role
         when :tool then 'user'

data/lib/ruby_llm/providers/openai.rb

@@ -2,7 +2,10 @@
 
 module RubyLLM
   module Providers
-    class OpenAI
+    # OpenAI API integration. Handles chat completion, function calling,
+    # and OpenAI's unique streaming format. Supports GPT-4, GPT-3.5,
+    # and other OpenAI models.
+    class OpenAI # rubocop:disable Metrics/ClassLength
       include Provider
 
       private
@@ -25,7 +28,7 @@ module RubyLLM
         '/v1/models'
       end
 
-      def build_payload(messages, tools:, temperature:, model:, stream: false)
+      def build_payload(messages, tools:, temperature:, model:, stream: false) # rubocop:disable Metrics/MethodLength
         {
           model: model,
           messages: format_messages(messages),
@@ -50,7 +53,7 @@ module RubyLLM
         end
       end
 
-      def format_tool_calls(tool_calls)
+      def format_tool_calls(tool_calls) # rubocop:disable Metrics/MethodLength
         return nil unless tool_calls&.any?
 
         tool_calls.map do |_, tc|
@@ -65,7 +68,7 @@ module RubyLLM
         end
       end
 
-      def tool_for(tool)
+      def tool_for(tool) # rubocop:disable Metrics/MethodLength
         {
           type: 'function',
           function: {
@@ -87,7 +90,7 @@ module RubyLLM
         }.compact
       end
 
-      def parse_completion_response(response)
+      def parse_completion_response(response) # rubocop:disable Metrics/MethodLength
         data = response.body
         return if data.empty?
 
@@ -104,7 +107,7 @@ module RubyLLM
         )
       end
 
-      def parse_tool_calls(tool_calls, parse_arguments: true)
+      def parse_tool_calls(tool_calls, parse_arguments: true) # rubocop:disable Metrics/MethodLength
         return nil unless tool_calls&.any?
 
         tool_calls.to_h do |tc|
@@ -119,7 +122,7 @@ module RubyLLM
         end
       end
 
-      def parse_models_response(response)
+      def parse_models_response(response) # rubocop:disable Metrics/MethodLength
         (response.body['data'] || []).map do |model|
           model_info = begin
             Models.find(model['id'])
@@ -150,7 +153,7 @@ module RubyLLM
         end
       end
 
-      def parse_list_models_response(response)
+      def parse_list_models_response(response) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         capabilities = ModelCapabilities::OpenAI
         (response.body['data'] || []).map do |model|
           ModelInfo.new(

data/lib/ruby_llm/stream_accumulator.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # Assembles streaming responses from LLMs into complete messages.
+  # Handles the complexities of accumulating content and tool calls
+  # from partial chunks while tracking token usage.
   class StreamAccumulator
     attr_reader :content, :model_id, :tool_calls
 
@@ -49,7 +52,7 @@ module RubyLLM
       end
     end
 
-    def accumulate_tool_calls(new_tool_calls)
+    def accumulate_tool_calls(new_tool_calls) # rubocop:disable Metrics/MethodLength
       new_tool_calls.each_value do |tool_call|
         if tool_call.id
           @tool_calls[tool_call.id] = ToolCall.new(

data/lib/ruby_llm/tool.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # Parameter definition for Tool methods. Specifies type constraints,
+  # descriptions, and whether parameters are required.
   class Parameter
     attr_reader :name, :type, :description, :required
 
@@ -12,6 +14,18 @@ module RubyLLM
     end
   end
 
+  # Base class for creating tools that AI models can use. Provides a simple
+  # interface for defining parameters and implementing tool behavior.
+  #
+  # Example:
+  #   class Calculator < RubyLLM::Tool
+  #     description "Performs arithmetic calculations"
+  #     param :expression, type: :string, desc: "Math expression to evaluate"
+  #
+  #     def execute(expression:)
+  #       eval(expression).to_s
+  #     end
+  #   end
   class Tool
     class << self
       def description(text = nil)

data/lib/ruby_llm/tool_call.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module RubyLLM
+  # Represents a function call from an AI model to a Tool.
+  # Encapsulates the function name, arguments, and execution results
+  # in a clean Ruby interface.
+  #
+  # Example:
+  #   tool_call = ToolCall.new(
+  #     id: "call_123",
+  #     name: "calculator",
+  #     arguments: { expression: "2 + 2" }
+  #   )
   class ToolCall
     attr_reader :id, :name, :arguments
 

data/lib/ruby_llm/version.rb

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

data/lib/ruby_llm.rb

@@ -7,6 +7,9 @@ require 'logger'
 require 'event_stream_parser'
 require 'securerandom'
 
+# A delightful Ruby interface to modern AI language models.
+# Provides a unified way to interact with models from OpenAI, Anthropic and others
+# with a focus on developer happiness and convention over configuration.
 module RubyLLM
   class Error < StandardError; end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre13
+  version: 0.1.0.pre14
 platform: ruby
 authors:
 - Carmine Paolino
@@ -344,6 +344,7 @@ files:
 - bin/console
 - bin/setup
 - lib/ruby_llm.rb
+- lib/ruby_llm/active_record/acts_as.rb
 - lib/ruby_llm/chat.rb
 - lib/ruby_llm/chunk.rb
 - lib/ruby_llm/configuration.rb