ruby_llm 0.1.0.pre19 → 0.1.0.pre21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 230db2439975e0515e1f128a286222c06de3de1b7eff0b77631bc9e4fa2df338
-  data.tar.gz: 25846959e0c3d2c411d82825077b4ff112bef0aea7910e87f5b3336fd58f8dca
+  metadata.gz: 5e413abd8ebadc4f30b5dc080113d9e40405117128bc8156bb7d9b0086f76956
+  data.tar.gz: 9a6971f4f5d7f709a4783b9f816589ca2b7e11199d1189bd5c946a8154d2a529
 SHA512:
-  metadata.gz: b082f5426e1c0d4ef426df99c5cca9463943b525e113b11aa9d60b799ebe6b0ae77fcc347a06d922b98316b402f8eb9a6a716ddd5e45c26ef86458eb4405d17c
-  data.tar.gz: c8a8a42ef3e0e8eb676fae0a28a26103c0dd1ff66be9753bb13d448f3114fb05d862fe78eee5f7599b6e2edd28a8d78c4e1fcd64ca87e163cecf1725f73351ff
+  metadata.gz: bdc7ad9b3e63755d398cfcc514103532d065a72bbf0eb7219496fc4c278e62b80cede1c9cadc75f3dbdb194cb655fb843d04a77d9860fd5665f5af34419f68eb
+  data.tar.gz: c4056980199b29e41993e1f7b092d760328b21e6327c427ad1a9ef09f4e5521482bb9a3cc9c1d0eba3380b18127541b583ebbd7d4780057df1e838c9bba48793

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Carmine Paolino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -19,9 +19,7 @@ Or install it yourself:
 gem install ruby_llm
 ```
 
-## Quick Start
-
-RubyLLM makes it dead simple to start chatting with AI models:
+## Configuration
 
 ```ruby
 require 'ruby_llm'
@@ -31,7 +29,13 @@ RubyLLM.configure do |config|
   config.openai_api_key = ENV['OPENAI_API_KEY']
   config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
 end
+```
+
+## Quick Start
+
+RubyLLM makes it dead simple to start chatting with AI models:
 
+```ruby
 # Start a conversation
 chat = RubyLLM.chat
 chat.ask "What's the best way to learn Ruby?"
@@ -82,16 +86,13 @@ Need vector embeddings for your text? RubyLLM makes it simple:
 
 ```ruby
 # Get embeddings with the default model
-vector = RubyLLM.embed "Hello, world!"
+RubyLLM.embed "Hello, world!"
 
 # Use a specific model
-vector = RubyLLM.embed(
-  "Ruby is awesome!",
-  model: "text-embedding-3-large"
-)
+RubyLLM.embed "Ruby is awesome!", model: "text-embedding-3-large"
 
 # Process multiple texts at once
-vectors = RubyLLM.embed([
+RubyLLM.embed([
   "First document",
   "Second document",
   "Third document"
@@ -172,6 +173,21 @@ chat.ask "What's 123 * 456?"
 # D, -- RubyLLM: Tool calculator returned: "56088"
 ```
 
+## Error Handling
+
+RubyLLM wraps provider errors in clear Ruby exceptions:
+
+```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}"
+end
+```
+
 ## 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:
@@ -242,14 +258,14 @@ That's it! Now you can use chats straight from your models:
 
 ```ruby
 # Create a new chat
-chat = Chat.create!(model_id: "gpt-4")
+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)
+  broadcast_chunk chunk
 end
 
 # Everything is persisted automatically
@@ -307,7 +323,7 @@ The persistence works seamlessly with background jobs:
 ```ruby
 class ChatJob < ApplicationJob
   def perform(chat_id, message)
-    chat = Chat.find(chat_id)
+    chat = Chat.find chat_id
 
     chat.ask(message) do |chunk|
       # Optional: Broadcast chunks for real-time updates
@@ -341,8 +357,8 @@ class WeatherTool < RubyLLM::Tool
 end
 
 # Use tools with your persisted chats
-chat = Chat.create!(model_id: "gpt-4")
-chat.chat.with_tool(WeatherTool.new)
+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?"
@@ -352,8 +368,6 @@ pp chat.messages.map(&:role)
 #=> [:user, :assistant, :tool, :assistant]
 ```
 
-Looking for more examples? Check out the [example Rails app](https://github.com/example/ruby_llm_rails) showing these patterns in action!
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt.
@@ -364,4 +378,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/crmne/
 
 ## License
 
-Released under the MIT License. See LICENSE.txt for details.
+Released under the MIT License. See [LICENSE](LICENSE) for details.

data/lib/ruby_llm/error.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Custom error class that wraps API errors from different providers
+  # into a consistent format with helpful error messages.
+  #
+  # Example:
+  #   begin
+  #     chat.ask "What's 2+2?"
+  #   rescue RubyLLM::Error => e
+  #     puts "Couldn't chat with AI: #{e.message}"
+  #   end
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(response = nil, message = nil)
+      @response = response
+      super(message || response&.body.to_s)
+    end
+  end
+
+  class UnauthorizedError < Error; end
+  class BadRequestError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+
+  # Faraday middleware that maps provider-specific API errors to RubyLLM errors.
+  # Uses provider's parse_error method to extract meaningful error messages.
+  class ErrorMiddleware < Faraday::Middleware
+    def initialize(app, provider: nil)
+      super(app)
+      @provider = provider
+    end
+
+    def call(env) # rubocop:disable Metrics/MethodLength
+      @app.call(env).on_complete do |response|
+        message = @provider&.parse_error(response)
+
+        case response.status
+        when 400
+          raise BadRequestError.new(response, message)
+        when 401
+          raise UnauthorizedError.new(response, 'Invalid API key - check your credentials')
+        when 429
+          raise RateLimitError.new(response, 'Rate limit exceeded - please wait a moment')
+        when 500..599
+          raise ServerError.new(response, 'API server error - please try again')
+        end
+      end
+    end
+  end
+end
+
+Faraday::Middleware.register_middleware(llm_errors: RubyLLM::ErrorMiddleware)

data/lib/ruby_llm/provider.rb

@@ -69,7 +69,7 @@ module RubyLLM
           f.request :json
           f.response :json
           f.adapter Faraday.default_adapter
-          f.use Faraday::Response::RaiseError
+          f.use :llm_errors, provider: self
           f.response :logger, RubyLLM.logger, { headers: false, bodies: true, errors: true, log_level: :debug }
         end
       end

data/lib/ruby_llm/providers/anthropic.rb

@@ -7,6 +7,10 @@ module RubyLLM
     class Anthropic # rubocop:disable Metrics/ClassLength
       include Provider
 
+      def parse_error(response)
+        JSON.parse(response.body).dig('error', 'message')
+      end
+
       private
 
       def api_base

data/lib/ruby_llm/providers/openai.rb

@@ -8,6 +8,10 @@ module RubyLLM
     class OpenAI # rubocop:disable Metrics/ClassLength
       include Provider
 
+      def parse_error(response)
+        JSON.parse(response.body).dig('error', 'message')
+      end
+
       private
 
       def api_base
@@ -43,13 +47,14 @@ module RubyLLM
             payload[:tools] = tools.map { |_, tool| tool_for(tool) }
             payload[:tool_choice] = 'auto'
           end
+          payload[:stream_options] = { include_usage: true } if stream
         end
       end
 
       def format_messages(messages)
         messages.map do |msg|
           {
-            role: msg.role.to_s,
+            role: format_role(msg.role),
             content: msg.content,
             tool_calls: format_tool_calls(msg.tool_calls),
             tool_call_id: msg.tool_call_id
@@ -57,6 +62,15 @@ module RubyLLM
         end
       end
 
+      def format_role(role)
+        case role
+        when :system
+          'developer'
+        else
+          role.to_s
+        end
+      end
+
       def build_embedding_payload(text, model:)
         {
           model: model,
@@ -156,14 +170,16 @@ module RubyLLM
         end.compact
       end
 
-      def handle_stream(&block)
+      def handle_stream(&block) # rubocop:disable Metrics/MethodLength
         to_json_stream do |data|
           block.call(
             Chunk.new(
               role: :assistant,
               model_id: data['model'],
               content: data.dig('choices', 0, 'delta', 'content'),
-              tool_calls: parse_tool_calls(data.dig('choices', 0, 'delta', 'tool_calls'), parse_arguments: false)
+              tool_calls: parse_tool_calls(data.dig('choices', 0, 'delta', 'tool_calls'), parse_arguments: false),
+              input_tokens: data.dig('usage', 'prompt_tokens'),
+              output_tokens: data.dig('usage', 'completion_tokens')
             )
           )
         end

data/lib/ruby_llm/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre19
+  version: 0.1.0.pre21
 platform: ruby
 authors:
 - Carmine Paolino
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-06 00:00:00.000000000 Z
+date: 2025-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -339,6 +339,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - bin/console
@@ -349,6 +350,7 @@ files:
 - lib/ruby_llm/chunk.rb
 - lib/ruby_llm/configuration.rb
 - lib/ruby_llm/embedding.rb
+- lib/ruby_llm/error.rb
 - lib/ruby_llm/message.rb
 - lib/ruby_llm/model_capabilities/anthropic.rb
 - lib/ruby_llm/model_capabilities/openai.rb