Provide access to raw response object from Faraday (#304)

## What this does

<!-- Clear description of what this PR does and why -->
Give callers access to the Faraday response on a property of the Message
called "raw"

## Type of change

- [x] New feature

## Scope check

- [x] I read the [Contributing
Guide](https://github.com/crmne/ruby_llm/blob/main/CONTRIBUTING.md)
- [x] This aligns with RubyLLM's focus on **LLM communication**
- [x] This isn't application-specific logic that belongs in user code
- [x] This benefits most users, not just my specific use case

## Quality check

- [x] I ran `overcommit --install` and all hooks pass
- [x] I tested my changes thoroughly
- [x] I updated documentation if needed
- [x] I didn't modify auto-generated files manually (`models.json`,
`aliases.json`)

## API changes

- [x] New public methods/classes

## Related issues

<!-- Link issues: "Fixes #123" or "Related to #123" -->
Resolves #301

---------

Co-authored-by: Mike Robbins <mrobbins@alum.mit.edu>

Author: tpaulshippy

docs/guides/chat.md

@@ -487,6 +487,17 @@ end
 chat.ask "What is metaprogramming in Ruby?"
 ```
 
+## Raw Responses
+
+You can access the raw response from the API provider with `response.raw`.
+
+```ruby
+response = chat.ask("What is the capital of France?")
+puts response.raw.body
+```
+
+The raw response is a `Faraday::Response` object, which you can use to access the headers, body, and status code.
+
 ## Next Steps
 
 This guide covered the core `Chat` interface. Now you might want to explore:

lib/ruby_llm/message.rb

@@ -7,7 +7,7 @@ module RubyLLM
   class Message
     ROLES = %i[system user assistant tool].freeze
 
-    attr_reader :role, :tool_calls, :tool_call_id, :input_tokens, :output_tokens, :model_id
+    attr_reader :role, :tool_calls, :tool_call_id, :input_tokens, :output_tokens, :model_id, :raw
     attr_writer :content
 
     def initialize(options = {})
@@ -18,6 +18,7 @@ def initialize(options = {})
       @output_tokens = options[:output_tokens]
       @model_id = options[:model_id]
       @tool_call_id = options[:tool_call_id]
+      @raw = options[:raw]
 
       ensure_valid_role
     end

lib/ruby_llm/providers/anthropic/chat.rb

@@ -57,22 +57,23 @@ def parse_completion_response(response)
           text_content = extract_text_content(content_blocks)
           tool_use_blocks = Tools.find_tool_uses(content_blocks)
 
-          build_message(data, text_content, tool_use_blocks)
+          build_message(data, text_content, tool_use_blocks, response)
         end
 
         def extract_text_content(blocks)
           text_blocks = blocks.select { |c| c['type'] == 'text' }
           text_blocks.map { |c| c['text'] }.join
         end
 
-        def build_message(data, content, tool_use_blocks)
+        def build_message(data, content, tool_use_blocks, response)
           Message.new(
             role: :assistant,
             content: content,
             tool_calls: Tools.parse_tool_calls(tool_use_blocks),
             input_tokens: data.dig('usage', 'input_tokens'),
             output_tokens: data.dig('usage', 'output_tokens'),
-            model_id: data['model']
+            model_id: data['model'],
+            raw: response
           )
         end
 

lib/ruby_llm/providers/bedrock/streaming/base.rb

@@ -34,15 +34,15 @@ def stream_response(connection, payload, &block)
                                                                                          payload:)
             accumulator = StreamAccumulator.new
 
-            connection.post stream_url, payload do |req|
+            response = connection.post stream_url, payload do |req|
               req.headers.merge! build_headers(signature.headers, streaming: block_given?)
               req.options.on_data = handle_stream do |chunk|
                 accumulator.add chunk
                 block.call chunk
               end
             end
 
-            accumulator.to_message
+            accumulator.to_message(response)
           end
 
           def handle_stream(&block)

lib/ruby_llm/providers/gemini/chat.rb

@@ -81,7 +81,8 @@ def parse_completion_response(response)
             tool_calls: tool_calls,
             input_tokens: data.dig('usageMetadata', 'promptTokenCount'),
             output_tokens: data.dig('usageMetadata', 'candidatesTokenCount'),
-            model_id: data['modelVersion'] || response.env.url.path.split('/')[3].split(':')[0]
+            model_id: data['modelVersion'] || response.env.url.path.split('/')[3].split(':')[0],
+            raw: response
           )
         end
 

lib/ruby_llm/providers/openai/chat.rb

@@ -59,7 +59,8 @@ def parse_completion_response(response)
             tool_calls: parse_tool_calls(message_data['tool_calls']),
             input_tokens: data['usage']['prompt_tokens'],
             output_tokens: data['usage']['completion_tokens'],
-            model_id: data['model']
+            model_id: data['model'],
+            raw: response
           )
         end
 

lib/ruby_llm/stream_accumulator.rb

@@ -29,14 +29,15 @@ def add(chunk)
       RubyLLM.logger.debug inspect
     end
 
-    def to_message
+    def to_message(response)
       Message.new(
         role: :assistant,
         content: content.empty? ? nil : content,
         model_id: model_id,
         tool_calls: tool_calls_from_stream,
         input_tokens: @input_tokens.positive? ? @input_tokens : nil,
-        output_tokens: @output_tokens.positive? ? @output_tokens : nil
+        output_tokens: @output_tokens.positive? ? @output_tokens : nil,
+        raw: response
       )
     end
 

lib/ruby_llm/streaming.rb

@@ -11,7 +11,7 @@ module Streaming
     def stream_response(connection, payload, &block)
       accumulator = StreamAccumulator.new
 
-      connection.post stream_url, payload do |req|
+      response = connection.post stream_url, payload do |req|
         if req.options.respond_to?(:on_data)
           # Handle Faraday 2.x streaming with on_data method
           req.options.on_data = handle_stream do |chunk|
@@ -27,7 +27,7 @@ def stream_response(connection, payload, &block)
         end
       end
 
-      accumulator.to_message
+      accumulator.to_message(response)
     end
 
     def handle_stream(&block)