ruby_llm 1.0.0 → 1.1.0rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c357c02ad6d779fab06975f3e06d6d699fe8860b99f05af4f4f89116c0c02868
-  data.tar.gz: e1379dcae9b2077b5bde9dd2a1f1a110151db15286ffa3503e9f596f64eb05fb
+  metadata.gz: 7f1ca42c438f99a40f6ada6ab87e23377403d9d6c8db6049d54960308b6dd42f
+  data.tar.gz: 0467734c40a0a64505b8f4de2eea4b929e2b0c615fedb3fe88d75f8cf20040de
 SHA512:
-  metadata.gz: 131ffdba032ec5844b1cd893ab3c712ee0a821faedc640ea4a2affc399f8c497a85b7a4c4e98daf13b7b7f52a1905e9135da4e94fd13967b96f47b02cd42a524
-  data.tar.gz: 75415cab8eba778d7b5d7918309dea8ea0e48bca1aca0ef13214835aec8ee9993bd943ff08efd827c5577636c6aa60ad998a6c81eac973e7cadd0061ce428fa2
+  metadata.gz: ed886fb15081ce27309c0e583223e62adf171907f0f047344763e9eae5ede4dbb96657bb1b69dde9e68bc1ed56acedb93717273067236e40104dddcc09886f33
+  data.tar.gz: 7f2aa9c50cfd1a525273256ff014712944c976229f6b90fe338decaf2525bcb82f19dec187d14795ce0891a7fceadb5c048905c8afa8066b0ddbe37d54c48edd

data/README.md

@@ -2,13 +2,16 @@
 
 A delightful Ruby way to work with AI. No configuration madness, no complex callbacks, no handler hell – just beautiful, expressive Ruby code.
 
-<div style="display: flex; align-items: center; flex-wrap: wrap; gap: 4px;">
+<div style="display: flex; align-items: center; flex-wrap: wrap; margin-bottom: 1em">
   <img src="https://upload.wikimedia.org/wikipedia/commons/4/4d/OpenAI_Logo.svg" alt="OpenAI" height="40" width="120">
-  &nbsp;&nbsp;&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;
+  &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;
+  &nbsp;&nbsp;
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-color.svg" alt="Bedrock" height="40">
+  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-text.svg" alt="Bedrock" height="40" width="120">
+  &nbsp;&nbsp;
   <img src="https://upload.wikimedia.org/wikipedia/commons/e/ec/DeepSeek_logo.svg" alt="DeepSeek" height="40" width="120">
 </div>
 
@@ -27,7 +30,7 @@ RubyLLM fixes all that. One beautiful API for everything. One consistent format.
 
 ## Features
 
-- 💬 **Chat** with OpenAI, Anthropic, Gemini, and DeepSeek models
+- 💬 **Chat** with OpenAI, Anthropic, Gemini, AWS Bedrock Anthropic, and DeepSeek models
 - 👁️ **Vision and Audio** understanding
 - 📄 **PDF Analysis** for analyzing documents
 - 🖼️ **Image generation** with DALL-E and other providers
@@ -52,6 +55,11 @@ chat.ask "Describe this meeting", with: { audio: "meeting.wav" }
 # Analyze documents
 chat.ask "Summarize this document", with: { pdf: "contract.pdf" }
 
+# Stream responses in real-time
+chat.ask "Tell me a story about a Ruby programmer" do |chunk|
+  print chunk.content
+end
+
 # Generate images
 RubyLLM.paint "a sunset over mountains in watercolor style"
 
@@ -59,16 +67,22 @@ RubyLLM.paint "a sunset over mountains in watercolor style"
 RubyLLM.embed "Ruby is elegant and expressive"
 
 # Let AI use your code
-class Calculator < RubyLLM::Tool
-  description "Performs calculations"
-  param :expression, type: :string, desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+  param :latitude, desc: "Latitude (e.g., 52.5200)"
+  param :longitude, desc: "Longitude (e.g., 13.4050)"
+
+  def execute(latitude:, longitude:)
+    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
+
+    response = Faraday.get(url)
+    data = JSON.parse(response.body)
+  rescue => e
+    { error: e.message }
   end
 end
 
-chat.with_tool(Calculator).ask "What's 123 * 456?"
+chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
 ```
 
 ## Installation
@@ -88,10 +102,16 @@ Configure with your API keys:
 
 ```ruby
 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
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+  config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
+  config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)
+  config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
+
+  # Bedrock
+  config.bedrock_api_key = ENV.fetch('AWS_ACCESS_KEY_ID', nil)
+  config.bedrock_secret_key = ENV.fetch('AWS_SECRET_ACCESS_KEY', nil)
+  config.bedrock_region = ENV.fetch('AWS_REGION', nil)
+  config.bedrock_session_token = ENV.fetch('AWS_SESSION_TOKEN', nil)
 end
 ```
 
@@ -115,6 +135,9 @@ chat.ask "Tell me a story about a Ruby programmer" do |chunk|
   print chunk.content
 end
 
+# Set personality or behavior with instructions (aka system prompts) - available from 1.1.0
+chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
+
 # 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" }
@@ -145,8 +168,12 @@ class ToolCall < ApplicationRecord
   acts_as_tool_call
 end
 
-# In your controller
-chat = Chat.create!(model_id: "gpt-4o-mini")
+# In a background job
+chat = Chat.create! model_id: "gpt-4o-mini"
+
+# Set personality or behavior with instructions (aka system prompts) - they're persisted too! - available from 1.1.0
+chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
+
 chat.ask("What's your favorite Ruby gem?") do |chunk|
   Turbo::StreamsChannel.broadcast_append_to(
     chat,
@@ -182,6 +209,18 @@ chat.with_tool(Search).ask "Find documents about Ruby 3.3 features"
 
 Check out the guides at https://rubyllm.com for deeper dives into conversations with tools, streaming responses, embedding generations, and more.
 
+## Contributing
+
+We welcome contributions to RubyLLM!
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on how to:
+- Run the test suite
+- Add new features
+- Update documentation
+- Re-record VCR cassettes when needed
+
+We appreciate your help making RubyLLM better!
+
 ## License
 
-Released under the MIT License.
+Released under the MIT License.

data/lib/ruby_llm/active_record/acts_as.rb

@@ -9,7 +9,7 @@ module RubyLLM
       extend ActiveSupport::Concern
 
       class_methods do # rubocop:disable Metrics/BlockLength
-        def acts_as_chat(message_class: 'Message', tool_call_class: 'ToolCall') # rubocop:disable Metrics/MethodLength
+        def acts_as_chat(message_class: 'Message', tool_call_class: 'ToolCall')
           include ChatMethods
 
           @message_class = message_class.to_s
@@ -21,12 +21,6 @@ module RubyLLM
                    dependent: :destroy
 
           delegate :complete,
-                   :with_tool,
-                   :with_tools,
-                   :with_model,
-                   :with_temperature,
-                   :on_new_message,
-                   :on_end_message,
                    :add_message,
                    to: :to_llm
         end
@@ -85,6 +79,51 @@ module RubyLLM
              .on_end_message { |msg| persist_message_completion(msg) }
       end
 
+      def with_instructions(instructions, replace: false)
+        transaction do
+          # If replace is true, remove existing system messages
+          messages.where(role: :system).destroy_all if replace
+
+          # Create the new system message
+          messages.create!(
+            role: :system,
+            content: instructions
+          )
+        end
+        to_llm.with_instructions(instructions)
+        self
+      end
+
+      def with_tool(tool)
+        to_llm.with_tool(tool)
+        self
+      end
+
+      def with_tools(*tools)
+        to_llm.with_tools(*tools)
+        self
+      end
+
+      def with_model(model_id, provider: nil)
+        to_llm.with_model(model_id, provider: provider)
+        self
+      end
+
+      def with_temperature(temperature)
+        to_llm.with_temperature(temperature)
+        self
+      end
+
+      def on_new_message(&)
+        to_llm.on_new_message(&)
+        self
+      end
+
+      def on_end_message(&)
+        to_llm.on_end_message(&)
+        self
+      end
+
       def ask(message, &)
         message = { role: :user, content: message }
         messages.create!(**message)

data/lib/ruby_llm/aliases.json

@@ -0,0 +1,65 @@
+{
+  "claude-3-5-sonnet": {
+    "anthropic": "claude-3-5-sonnet-20241022",
+    "bedrock": "anthropic.claude-3-5-sonnet-20241022-v2:0"
+  },
+  "claude-3-5-haiku": {
+    "anthropic": "claude-3-5-haiku-20241022",
+    "bedrock": "anthropic.claude-3-5-haiku-20241022-v1:0"
+  },
+  "claude-3-7-sonnet": {
+    "anthropic": "claude-3-7-sonnet-20250219",
+    "bedrock": "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
+  },
+  "claude-3-opus": {
+    "anthropic": "claude-3-opus-20240229",
+    "bedrock": "anthropic.claude-3-opus-20240229-v1:0"
+  },
+  "claude-3-sonnet": {
+    "anthropic": "claude-3-sonnet-20240229",
+    "bedrock": "anthropic.claude-3-sonnet-20240229-v1:0"
+  },
+  "claude-3-haiku": {
+    "anthropic": "claude-3-haiku-20240307",
+    "bedrock": "anthropic.claude-3-haiku-20240307-v1:0"
+  },
+  "claude-3": {
+    "anthropic": "claude-3-sonnet-20240229",
+    "bedrock": "anthropic.claude-3-sonnet-20240229-v1:0"
+  },
+  "claude-2": {
+    "anthropic": "claude-2.0",
+    "bedrock": "anthropic.claude-2.0"
+  },
+  "claude-2-1": {
+    "anthropic": "claude-2.1",
+    "bedrock": "anthropic.claude-2.1"
+  },
+  "gpt-4o": {
+    "openai": "gpt-4o-2024-11-20"
+  },
+  "gpt-4o-mini": {
+    "openai": "gpt-4o-mini-2024-07-18"
+  },
+  "gpt-4-turbo": {
+    "openai": "gpt-4-turbo-2024-04-09"
+  },
+  "gemini-1.5-flash": {
+    "gemini": "gemini-1.5-flash-002"
+  },
+  "gemini-1.5-flash-8b": {
+    "gemini": "gemini-1.5-flash-8b-001"
+  },
+  "gemini-1.5-pro": {
+    "gemini": "gemini-1.5-pro-002"
+  },
+  "gemini-2.0-flash": {
+    "gemini": "gemini-2.0-flash-001"
+  },
+  "o1": {
+    "openai": "o1-2024-12-17"
+  },
+  "o3-mini": {
+    "openai": "o3-mini-2025-01-31"
+  }
+}

data/lib/ruby_llm/aliases.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Manages model aliases, allowing users to reference models by simpler names
+  # that map to specific model versions across different providers.
+  #
+  # Aliases are defined in aliases.json and follow the format:
+  #   {
+  #     "simple-name": {
+  #       "provider1": "specific-version-for-provider1",
+  #       "provider2": "specific-version-for-provider2"
+  #     }
+  #   }
+  class Aliases
+    class << self
+      # Resolves a model ID to its provider-specific version
+      #
+      # @param model_id [String] the model identifier or alias
+      # @param provider_slug [String, Symbol, nil] optional provider to resolve for
+      # @return [String] the resolved model ID or the original if no alias exists
+      def resolve(model_id, provider = nil)
+        return model_id unless aliases[model_id]
+
+        if provider
+          aliases[model_id][provider.to_s] || model_id
+        else
+          # Get native provider's version
+          aliases[model_id].values.first || model_id
+        end
+      end
+
+      # Returns the loaded aliases mapping
+      # @return [Hash] the aliases mapping
+      def aliases
+        @aliases ||= load_aliases
+      end
+
+      # Loads aliases from the JSON file
+      # @return [Hash] the loaded aliases
+      def load_aliases
+        file_path = File.expand_path('aliases.json', __dir__)
+        if File.exist?(file_path)
+          JSON.parse(File.read(file_path))
+        else
+          {}
+        end
+      end
+
+      # Reloads aliases from disk
+      # @return [Hash] the reloaded aliases
+      def reload!
+        @aliases = load_aliases
+      end
+    end
+  end
+end

data/lib/ruby_llm/chat.rb

@@ -13,10 +13,10 @@ module RubyLLM
 
     attr_reader :model, :messages, :tools
 
-    def initialize(model: nil)
+    def initialize(model: nil, provider: nil)
       model_id = model || RubyLLM.config.default_model
-      self.model = model_id
-      @temperature = @model.metadata['family'] == 'o1' ? 1 : 0.7
+      with_model(model_id, provider: provider)
+      @temperature = 0.7
       @messages = []
       @tools = {}
       @on = {
@@ -32,6 +32,11 @@ module RubyLLM
 
     alias say ask
 
+    def with_instructions(instructions)
+      add_message role: :system, content: instructions
+      self
+    end
+
     def with_tool(tool)
       unless @model.supports_functions
         raise UnsupportedFunctionsError, "Model #{@model.id} doesn't support function calling"
@@ -47,13 +52,9 @@ module RubyLLM
       self
     end
 
-    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
+    def with_model(model_id, provider: nil)
+      @model = Models.find model_id, provider
+      @provider = Provider.providers[@model.provider.to_sym] || raise(Error, "Unknown provider: #{@model.provider}")
       self
     end
 

data/lib/ruby_llm/configuration.rb

@@ -14,6 +14,10 @@ module RubyLLM
                   :anthropic_api_key,
                   :gemini_api_key,
                   :deepseek_api_key,
+                  :bedrock_api_key,
+                  :bedrock_secret_key,
+                  :bedrock_region,
+                  :bedrock_session_token,
                   :default_model,
                   :default_embedding_model,
                   :default_image_model,

data/lib/ruby_llm/error.rb

@@ -19,15 +19,21 @@ module RubyLLM
     end
   end
 
-  class ModelNotFoundError < StandardError; end
+  # Error classes for non-HTTP errors
+  class ConfigurationError < StandardError; end
   class InvalidRoleError < StandardError; end
+  class ModelNotFoundError < StandardError; end
   class UnsupportedFunctionsError < StandardError; end
-  class UnauthorizedError < Error; end
-  class PaymentRequiredError < Error; end
-  class ServiceUnavailableError < Error; end
+
+  # Error classes for different HTTP status codes
   class BadRequestError < Error; end
+  class ForbiddenError < Error; end
+  class OverloadedError < Error; end
+  class PaymentRequiredError < Error; end
   class RateLimitError < Error; end
   class ServerError < Error; end
+  class ServiceUnavailableError < Error; end
+  class UnauthorizedError < Error; end
 
   # Faraday middleware that maps provider-specific API errors to RubyLLM errors.
   # Uses provider's parse_error method to extract meaningful error messages.
@@ -56,12 +62,17 @@ module RubyLLM
           raise UnauthorizedError.new(response, message || 'Invalid API key - check your credentials')
         when 402
           raise PaymentRequiredError.new(response, message || 'Payment required - please top up your account')
+        when 403
+          raise ForbiddenError.new(response,
+                                   message || 'Forbidden - you do not have permission to access this resource')
         when 429
           raise RateLimitError.new(response, message || 'Rate limit exceeded - please wait a moment')
         when 500
           raise ServerError.new(response, message || 'API server error - please try again')
         when 502..503
           raise ServiceUnavailableError.new(response, message || 'API server unavailable - please try again later')
+        when 529
+          raise OverloadedError.new(response, message || 'Service overloaded - please try again later')
         else
           raise Error.new(response, message || 'An unknown error occurred')
         end