ai-chat 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dd73c65bb0fa8183801233a76038c8e9a32f86268ab113311317a47f72504db
-  data.tar.gz: 8a6541039268eee87a035f7547d767919962b8f20573e06618700e05ea72ffe6
+  metadata.gz: ece58b865d212ce788931ee3e7322b457bbe6ed8495e4374b55ecf697b44e55c
+  data.tar.gz: dd4bf5e24a5190eba63c662d93dcaaad24886b7f16cfbec5aebc37a9f3530cd9
 SHA512:
-  metadata.gz: b2564b32f5f1c69e8749eb079339d120cbfbf71ce9c5870cfb7b47ea81891ec11dbc9290b59f2b49b35830f59d7f0817d3dcaa558bc5ef1d97309a0a26da3733
-  data.tar.gz: ae9ebf5fd4b0a1001e6fb047585c852055c43cfc2b7af7fc3385ed8df355aec260e2ba6e80a2443b9104648a49356124974353317d3818449413fe923ab27a0a
+  metadata.gz: dcb3587c00724b1da3d04adb2b9a7413225680b80971bd08db127edab6d7f18e52958b7511f3aa7e13cb95f40961f8889cae3f0cc892913930547d5a7887d452
+  data.tar.gz: e831f86fecfa31cf28df66910fc6ca98c66a9ad8290709431a0e5e9b8a6e31965ba7af9d5a00dbcf3f907427abe8901abf23a1cd136b26bc2ebffe260b6334ed

data/README.md

@@ -26,19 +26,20 @@ The `examples/` directory contains focused examples for specific features:
 
 - `01_quick.rb` - Quick overview of key features
 - `02_core.rb` - Core functionality (basic chat, messages, responses)
-- `03_configuration.rb` - Configuration options (API keys, models, reasoning effort)
-- `04_multimodal.rb` - Basic file and image handling
-- `05_file_handling_comprehensive.rb` - Advanced file handling (PDFs, text files, Rails uploads)
-- `06_structured_output.rb` - Basic structured output with schemas
-- `07_structured_output_comprehensive.rb` - All 6 supported schema formats
-- `08_advanced_usage.rb` - Advanced patterns (chaining, web search)
-- `09_edge_cases.rb` - Error handling and edge cases
-- `10_additional_patterns.rb` - Less common usage patterns (direct add method, web search + schema, etc.)
-- `11_mixed_content.rb` - Combining text and images in messages
-- `12_image_generation.rb` - Using the image generation tool
-- `13_code_interpreter.rb` - Using the code interpreter tool
-- `14_background_mode.rb` - Running responses in background mode
-- `15_conversation_features_comprehensive.rb` - All conversation features (auto-creation, inspection, loading, forking)
+- `03_multimodal.rb` - Basic file and image handling
+- `04_file_handling_comprehensive.rb` - Advanced file handling (PDFs, text files, Rails uploads)
+- `05_structured_output.rb` - Basic structured output with schemas
+- `06_structured_output_comprehensive.rb` - All 6 supported schema formats
+- `07_edge_cases.rb` - Error handling and edge cases
+- `08_additional_patterns.rb` - Less common usage patterns (direct add method, web search + schema, etc.)
+- `09_mixed_content.rb` - Combining text and images in messages
+- `10_image_generation.rb` - Using the image generation tool
+- `11_code_interpreter.rb` - Using the code interpreter tool
+- `12_background_mode.rb` - Running responses in background mode
+- `13_conversation_features_comprehensive.rb` - Conversation features (auto-creation, continuity, inspection)
+- `14_schema_generation.rb` - Generate JSON schemas from natural language
+- `15_proxy.rb` - Proxy support for student accounts
+- `16_get_items.rb` - Inspecting conversation items (reasoning, web searches, image generation)
 
 Each example is self-contained and can be run individually:
 ```bash
@@ -83,22 +84,44 @@ a = AI::Chat.new
 a.add("If the Ruby community had an official motto, what might it be?")
 
 # See the convo so far - it's just an array of hashes!
-pp a.messages
-# => [{:role=>"user", :content=>"If the Ruby community had an official motto, what might it be?"}]
+a.messages
+# => [
+#        {
+#               :role => "user",
+#            :content => "If the Ruby community had an official motto, what might it be?"
+#        }
+#    ]
 
 # Generate the next message using AI
-a.generate! # => { :role => "assistant", :content => "Matz is nice and so we are nice" (or similar) }
+a.generate!
+# => {
+#           :role => "assistant",
+#        :content => "Matz is nice and so we are nice",
+#       :response => { ... }
+#    }
 
 # Your array now includes the assistant's response
-pp a.messages
+a.messages
 # => [
-#      {:role=>"user", :content=>"If the Ruby community had an official motto, what might it be?"},
-#      {:role=>"assistant", :content=>"Matz is nice and so we are nice", :response => { id=resp_abc... model=gpt-4.1-nano tokens=12 } }
+#        {
+#               :role => "user",
+#            :content => "If the Ruby community had an official motto, what might it be?"
+#        },
+#        {
+#               :role => "assistant",
+#            :content => "Matz is nice and so we are nice",
+#           :response => { id: "resp_abc...", model: "gpt-5.2", ... }
+#        }
 #    ]
 
 # Continue the conversation
 a.add("What about Rails?")
-a.generate! # => { :role => "assistant", :content => "Convention over configuration."} 
+a.generate!
+# => {
+#           :role => "assistant",
+#        :content => "Convention over configuration.",
+#       :response => { ... }
+#    } 
 ```
 
 ## Understanding the Data Structure
@@ -111,9 +134,19 @@ That's it! You're building something like this:
 
 ```ruby
 [
-  {:role => "system", :content => "You are a helpful assistant"},
-  {:role => "user", :content => "Hello!"},
-  {:role => "assistant", :content => "Hi there! How can I help you today?", :response => { id=resp_abc... model=gpt-4.1-nano tokens=12 } }
+    {
+           :role => "system",
+        :content => "You are a helpful assistant"
+    },
+    {
+           :role => "user",
+        :content => "Hello!"
+    },
+    {
+           :role => "assistant",
+        :content => "Hi there! How can I help you today?",
+        :response => { id: "resp_abc...", model: "gpt-5.2", ... }
+    }
 ]
 ```
 
@@ -133,14 +166,25 @@ b.add("You are a helpful assistant that talks like Shakespeare.", role: "system"
 b.add("If the Ruby community had an official motto, what might it be?")
 
 # Check what we've built
-pp b.messages
+b.messages
 # => [
-#      {:role=>"system", :content=>"You are a helpful assistant that talks like Shakespeare."},
-#      {:role=>"user", :content=>"If the Ruby community had an official motto, what might it be?"}
+#        {
+#               :role => "system",
+#            :content => "You are a helpful assistant that talks like Shakespeare."
+#        },
+#        {
+#               :role => "user",
+#            :content => "If the Ruby community had an official motto, what might it be?"
+#        }
 #    ]
 
 # Generate a response
-b.generate! # => { :role => "assistant", :content => "Methinks 'tis 'Ruby doth bring joy to all who craft with care'" }
+b.generate!
+# => {
+#           :role => "assistant",
+#        :content => "Methinks 'tis 'Ruby doth bring joy to all who craft with care'",
+#       :response => { ... }
+#    }
 ```
 
 ### Convenience Methods
@@ -183,25 +227,14 @@ d.generate!                         # Generate a response
 
 ### Model
 
-By default, the gem uses OpenAI's `gpt-4.1-nano` model. If you want to use a different model, you can set it:
+By default, the gem uses OpenAI's `gpt-5.2` model. If you want to use a different model, you can set it:
 
 ```ruby
 e = AI::Chat.new
-e.model = "o4-mini"
+e.model = "gpt-4o"
 ```
 
-As of 2025-07-29, the list of chat models that you probably want to choose from are:
-
-#### Foundation models 
-
-- gpt-4.1-nano
-- gpt-4.1-mini
-- gpt-4.1
-
-#### Reasoning models
-
-- o4-mini
-- o3
+See [OpenAI's model documentation](https://platform.openai.com/docs/models) for available models.
 
 ### API key
 
@@ -230,11 +263,20 @@ h.user("How do I boil an egg?")
 h.generate!
 
 # See the whole conversation
-pp h.messages
+h.messages
 # => [
-#      {:role=>"system", :content=>"You are a helpful cooking assistant"},
-#      {:role=>"user", :content=>"How do I boil an egg?"},
-#      {:role=>"assistant", :content=>"Here's how to boil an egg..."}
+#        {
+#               :role => "system",
+#            :content => "You are a helpful cooking assistant"
+#        },
+#        {
+#               :role => "user",
+#            :content => "How do I boil an egg?"
+#        },
+#        {
+#               :role => "assistant",
+#            :content => "Here's how to boil an egg..."
+#        }
 #    ]
 
 # Get just the last response
@@ -248,7 +290,7 @@ h.last[:content]
 
 ## Web Search
 
-To give the model access to real-time information from the internet, you can enable web searching. This uses OpenAI's built-in `web_search_preview` tool.
+To give the model access to real-time information from the internet, you can enable web searching. This uses OpenAI's built-in `web_search` tool.
 
 ```ruby
 m = AI::Chat.new
@@ -257,17 +299,6 @@ m.user("What are the latest developments in the Ruby language?")
 m.generate! # This may use web search to find current information
 ```
 
-**Note:** This feature requires a model that supports the `web_search_preview` tool, such as `gpt-4o` or `gpt-4o-mini`. The gem will attempt to use a compatible model if you have `web_search` enabled.
-
-If you don't want the model to use web search, set `web_search` to `false` (this is the default):
-
-```ruby
-m = AI::Chat.new
-m.web_search = false
-m.user("What are the latest developments in the Ruby language?")
-m.generate! # This definitely won't use web search to find current information
-```
-
 ## Structured Output
 
 Get back Structured Output by setting the `schema` attribute (I suggest using [OpenAI's handy tool for generating the JSON Schema](https://platform.openai.com/docs/guides/structured-outputs)):
@@ -474,27 +505,6 @@ l.generate!
 
 **Note**: Images should use `image:`/`images:` parameters, while documents should use `file:`/`files:` parameters.
 
-## Re-sending old images and files
-
-Note: if you generate another API request using the same chat, old images and files in the conversation history will not be re-sent by default. If you really want to re-send old images and files, then you must set `previous_response_id` to `nil`:
-
-```ruby
-a = AI::Chat.new
-a.user("What color is the object in this photo?", image: "thing.png")
-a.generate! # => "Red"
-a.user("What is the object in the photo?")
-a.generate! # => { :content => "I don't see a photo", ... }
-
-b = AI::Chat.new
-b.user("What color is the object in this photo?", image: "thing.png")
-b.generate! # => "Red"
-b.user("What is the object in the photo?")
-b.previous_response_id = nil
-b.generate! # => { :content => "An apple", ... }
-```
-
-If you don't set `previous_response_id` to `nil`, the model won't have the old image(s) to work with.
-
 ## Image generation
 
 You can enable OpenAI's image generation tool:
@@ -503,7 +513,11 @@ You can enable OpenAI's image generation tool:
 a = AI::Chat.new
 a.image_generation = true
 a.user("Draw a picture of a kitten")
-a.generate! # => { :content => "Here is your picture of a kitten:", ... }
+a.generate!
+# => {
+#        :content => "Here is your picture of a kitten:",
+#       :response => { ... }
+#    }
 ```
 
 By default, images are saved to `./images`. You can configure a different location:
@@ -513,7 +527,11 @@ a = AI::Chat.new
 a.image_generation = true
 a.image_folder = "./my_images"
 a.user("Draw a picture of a kitten")
-a.generate! # => { :content => "Here is your picture of a kitten:", ... }
+a.generate!
+# => {
+#        :content => "Here is your picture of a kitten:",
+#       :response => { ... }
+#    }
 ```
 
 Images are saved in timestamped subfolders using ISO 8601 basic format. For example:
@@ -525,11 +543,19 @@ The folder structure ensures images are organized chronologically and by respons
 The messages array will now look like this:
 
 ```ruby
-pp a.messages
+a.messages
 # => [
-#   {:role=>"user", :content=>"Draw a picture of a kitten"},
-#   {:role=>"assistant", :content=>"Here is your picture of a kitten:", :images => ["./images/20250804T11303912_resp_abc123/001.png"], :response => #<Response ...>}
-# ]
+#        {
+#               :role => "user",
+#            :content => "Draw a picture of a kitten"
+#        },
+#        {
+#               :role => "assistant",
+#            :content => "Here is your picture of a kitten:",
+#             :images => [ "./images/20250804T11303912_resp_abc123/001.png" ],
+#           :response => { ... }
+#        }
+#    ]
 ```
 
 You can access the image filenames in several ways:
@@ -540,7 +566,7 @@ images = a.messages.last[:images]
 # => ["./images/20250804T11303912_resp_abc123/001.png"]
 
 # From the response object
-images = a.messages.last[:response].images
+images = a.messages.last.dig(:response, :images)
 # => ["./images/20250804T11303912_resp_abc123/001.png"]
 ```
 
@@ -551,9 +577,11 @@ a = AI::Chat.new
 a.image_generation = true
 a.image_folder = "./images"
 a.user("Draw a picture of a kitten")
-a.generate! # => { :content => "Here is a picture of a kitten:", ... }
+a.generate!
+# => { :content => "Here is a picture of a kitten:", ... }
 a.user("Make it even cuter")
-a.generate! # => { :content => "Here is the kitten, but even cuter:", ... }
+a.generate!
+# => { :content => "Here is the kitten, but even cuter:", ... }
 ```
 
 ## Code Interpreter
@@ -562,7 +590,23 @@ a.generate! # => { :content => "Here is the kitten, but even cuter:", ... }
 y = AI::Chat.new
 y.code_interpreter = true
 y.user("Plot y = 2x*3 when x is -5 to 5.")
-y.generate! # => {:content => "Here is the graph.", ... }
+y.generate!
+# => { :content => "Here is the graph.", ... }
+```
+
+## Background mode
+
+If you want to start a response and poll for it later, set `background = true` before calling `generate!`:
+
+```ruby
+chat = AI::Chat.new
+chat.background = true
+chat.user("Write a short description about a sci-fi novel about a rat in space.")
+chat.generate!
+
+# Poll until it completes (this updates the existing assistant message)
+message = chat.get_response(wait: true, timeout: 600)
+puts message[:content]
 ```
 
 ## Proxying Through prepend.me
@@ -608,29 +652,28 @@ puts response
 
 With this, you can loop through any conversation's history (perhaps after retrieving it from your database), recreate an `AI::Chat`, and then continue it.
 
-## Reasoning Models
+## Reasoning Effort
 
-When using reasoning models like `o3` or `o4-mini`, you can specify a reasoning effort level to control how much reasoning the model does before producing its final response:
+You can control how much reasoning the model does before producing its response:
 
 ```ruby
 l = AI::Chat.new
-l.model = "o3-mini"
-l.reasoning_effort = "medium" # Can be "low", "medium", or "high"
+l.reasoning_effort = "low" # Can be "low", "medium", or "high"
 
 l.user("What does this error message mean? <insert error message>")
 l.generate!
 ```
 
-The `reasoning_effort` parameter guides the model on how many reasoning tokens to generate before creating a response to the prompt. Options are:
+The `reasoning_effort` parameter guides the model on how many reasoning tokens to generate. Options are:
 - `"low"`: Favors speed and economical token usage.
-- `"medium"`: (Default) Balances speed and reasoning accuracy.
+- `"medium"`: Balances speed and reasoning accuracy.
 - `"high"`: Favors more complete reasoning.
 
-Setting to `nil` disables the reasoning parameter.
+By default, `reasoning_effort` is `nil`, which means no reasoning parameter is sent to the API. For `gpt-5.2` (the default model), this is equivalent to `"none"` reasoning.
 
 ## Advanced: Response Details
 
-When you call `generate!` or `generate!`, the gem stores additional information about the API response:
+When you call `generate!` (or later call `get_response` in background mode), the gem stores additional information about the API response:
 
 ```ruby
 t = AI::Chat.new
@@ -638,18 +681,18 @@ t.user("Hello!")
 t.generate!
 
 # Each assistant message includes a response object
-pp t.messages.last
+t.messages.last
 # => {
-#      :role => "assistant",
-#      :content => "Hello! How can I help you today?",
-#      :response => { id=resp_abc... model=gpt-4.1-nano tokens=12 }
+#           :role => "assistant",
+#        :content => "Hello! How can I help you today?",
+#       :response => { id: "resp_abc...", model: "gpt-5.2", ... }
 #    }
 
 # Access detailed information
 response = t.last[:response]
 response[:id]           # => "resp_abc123..."
-response[:model]        # => "gpt-4.1-nano"
-response[:usage]        # => {:prompt_tokens=>5, :completion_tokens=>7, :total_tokens=>12}
+response[:model]        # => "gpt-5.2"
+response[:usage]        # => {:input_tokens=>5, :output_tokens=>7, :total_tokens=>12}
 ```
 
 This information is useful for:
@@ -658,26 +701,35 @@ This information is useful for:
 - Understanding which model was actually used.
 - Future features like cost tracking.
 
-You can also, if you know a response ID, continue an old conversation by setting the `previous_response_id`:
+### Last Response ID
+
+In addition to the `response` object inside each message, the `AI::Chat` instance also provides a convenient reader, `last_response_id`, which always holds the ID of the most recent response.
 
 ```ruby
-t = AI::Chat.new
-t.user("Hello!")
-t.generate!
-old_id = t.last[:response][:id] # => "resp_abc123..."
+chat = AI::Chat.new
+chat.user("Hello")
+chat.generate!
 
-# Some time in the future...
+puts chat.last_response_id # => "resp_abc123..."
 
-u = AI::Chat.new
-u.previous_response_id = "resp_abc123..."
-u.user("What did I just say?")
-u.generate! # Will have context from the previous conversation}
-#    ]
-u.user("What should we do next?")
-u.generate!
+chat.user("Goodbye")
+chat.generate!
+
+puts chat.last_response_id # => "resp_xyz789..." (a new ID)
 ```
 
-Unless you've stored the previous messages somewhere yourself, this technique won't bring them back. But OpenAI remembers what they were, so that you can at least continue the conversation. (If you're using a reasoning model, this technique also preserves all of the model's reasoning.)
+This is particularly useful for background mode workflows. If you want to retrieve or cancel a background response from a different process, use `OpenAI::Client` directly:
+
+```ruby
+require "openai"
+
+client = OpenAI::Client.new(api_key: ENV.fetch("OPENAI_API_KEY"))
+
+response_id = "resp_abc123..." # e.g., load from your database
+response = client.responses.retrieve(response_id)
+
+client.responses.cancel(response_id) unless response.status.to_s == "completed"
+```
 
 ### Automatic Conversation Management
 
@@ -707,68 +759,119 @@ chat.user("Continue our discussion")
 chat.generate!  # Uses the loaded conversation
 ```
 
-**Note on forking:** If you want to "fork" a conversation (create a branch), you can still use `previous_response_id`. If both `conversation_id` and `previous_response_id` are set, the gem will use `previous_response_id` and warn you.
-
 ## Inspecting Conversation Details
 
-The gem provides two methods to inspect what happened during a conversation:
-
-### `items` - Programmatic Access
-
-Returns the raw conversation items for programmatic use (displaying in views, filtering, etc.):
+The `get_items` method fetches all conversation items (messages, tool calls, reasoning, etc.) from the API for both programmatic use and debugging:
 
 ```ruby
 chat = AI::Chat.new
+chat.reasoning_effort = "high"  # Enable reasoning summaries
 chat.web_search = true
 chat.user("Search for Ruby tutorials")
 chat.generate!
 
 # Get all conversation items (chronological order by default)
-page = chat.items
+chat.get_items
+
+# Output in IRB/Rails console:
+# ┌────────────────────────────────────────────────────────────────────────────┐
+# │ Conversation: conv_6903c1eea6cc819695af3a1b1ebf9b390c3db5e8ec021c9a        │
+# │ Items: 8                                                                   │
+# └────────────────────────────────────────────────────────────────────────────┘
+#
+# [detailed colorized output of all items including web searches,
+#  reasoning summaries, tool calls, messages, etc.]
 
-# Access item data
-page.data.each do |item|
+# Iterate over items programmatically
+chat.get_items.data.each do |item|
   case item.type
   when :message
     puts "#{item.role}: #{item.content.first.text}"
   when :web_search_call
-    puts "Web search: #{item.action.query}"
-    puts "Results: #{item.results.length}"
+    puts "Web search: #{item.action.query}" if item.action.respond_to?(:query) && item.action.query
   when :reasoning
-    puts "Reasoning: #{item.summary.first.text}"
+    # Reasoning summaries show a high-level view of the model's reasoning
+    if item.summary&.first
+      puts "Reasoning: #{item.summary.first.text}"
+    end
+  when :image_generation_call
+    puts "Image generated" if item.result
   end
 end
 
 # For long conversations, you can request reverse chronological order
 # (useful for pagination to get most recent items first)
-recent_items = chat.items(order: :desc)
+recent_items = chat.get_items(order: :desc)
 ```
 
-### `verbose` - Terminal Output
-
-Pretty-prints the entire conversation with all details for debugging and learning:
-
-```ruby
-chat.verbose
-
-# Output:
-# ┌────────────────────────────────────────────────────────────────────────────┐
-# │ Conversation: conv_6903c1eea6cc819695af3a1b1ebf9b390c3db5e8ec021c9a        │
-# │ Items: 3                                                                   │
-# └────────────────────────────────────────────────────────────────────────────┘
-#
-# [detailed colorized output of all items including web searches,
-#  reasoning, tool calls, messages, etc.]
-```
+When `reasoning_effort` is set, the API returns reasoning summaries (e.g., "Planning Ruby version search", "Confirming image tool usage"). Note that not all reasoning items have summaries - some intermediate steps may be empty.
 
 This is useful for:
 - **Learning** how the model uses tools (web search, code interpreter, etc.)
 - **Debugging** why the model made certain decisions
 - **Understanding** the full context beyond just the final response
+- **Transparency** into the model's reasoning process
+
+### HTML Output for ERB Templates
+
+All display objects have a `to_html` method for rendering in ERB templates:
+
+```erb
+<%# Display a chat object %>
+<%= @chat.to_html %>
+
+<%# Display individual messages %>
+<% @chat.messages.each do |msg| %>
+  <%= msg.to_html %>
+<% end %>
+
+<%# Display conversation items (quick debug view) %>
+<%= @chat.get_items.to_html %>
+```
+
+The HTML output includes a dark background to match the terminal aesthetic.
+
+You can also loop over `get_items.data` to build custom displays showing reasoning steps, tool calls, etc.:
+
+```erb
+<% @chat.get_items.data.each do |item| %>
+  <% case item.type.to_s %>
+  <% when "message" %>
+    <div class="message <%= item.role %>">
+      <strong><%= item.role.capitalize %>:</strong>
+      <% if item.content&.first %>
+        <% content = item.content.first %>
+        <% if content.type.to_s == "input_text" %>
+          <%= content.text %>
+        <% elsif content.type.to_s == "output_text" %>
+          <%= content.text %>
+        <% end %>
+      <% end %>
+    </div>
+  <% when "reasoning" %>
+    <% if item.summary&.first %>
+      <details class="reasoning">
+        <summary>Reasoning</summary>
+        <%= item.summary.first.text %>
+      </details>
+    <% end %>
+  <% when "web_search_call" %>
+    <% if item.action.respond_to?(:query) && item.action.query %>
+      <div class="web-search">
+        Searched: "<%= item.action.query %>"
+      </div>
+    <% end %>
+  <% when "image_generation_call" %>
+    <div class="image-generation">
+      Image generated
+    </div>
+  <% end %>
+<% end %>
+```
 
 ## Setting messages directly
 
-You can use `.messages=()` to assign an `Array` of `Hashes`. Each `Hash` must have keys `:role` and `:content`, and optionally `:image` or `:images`:
+You can use `.messages=()` to assign an `Array` of `Hashes` (text-only). Each `Hash` must have keys `:role` and `:content`:
 
 ```ruby
 # Using the planet example with array of hashes
@@ -791,53 +894,8 @@ response = p.generate!
 puts response
 ```
 
-You can still include images:
-
-```ruby
-# Create a new chat instance
-q = AI::Chat.new
-
-# With images
-q.messages = [
-  { role: "system", content: "You are a helpful assistant." },
-  { role: "user", content: "What's in this image?", image: "path/to/image.jpg" },
-]
-
-# With multiple images
-q.messages = [
-  { role: "system", content: "You are a helpful assistant." },
-  { role: "user", content: "Compare these images", images: ["image1.jpg", "image2.jpg"] }
-]
-```
-
-## Other Features Being Considered
-
-- **Session management**: Save and restore conversations by ID
-- **Streaming responses**: Real-time streaming as the AI generates its response
-- **Cost tracking**: Automatic calculation and tracking of API costs
-
-## Testing with Real API Calls
-
-While this gem includes specs, they use mocked API responses. To test with real API calls:
-
-1. Create a `.env` file at the project root with your API credentials:
-    ```
-    # Your OpenAI API key
-    OPENAI_API_KEY=your_openai_api_key_here
-    ```
-2. Install dependencies: `bundle install`
-3. Run the examples: `bundle exec ruby examples/all.rb`
-
-This test program runs through all the major features of the gem, making real API calls to OpenAI.
+For images/files, prefer using `chat.user(..., image:/images:/file:/files:)` so the gem can build the correct multimodal structure.
 
 ## Contributing
 
-When contributing to this project:
-
-1. **Code Style**: This project uses StandardRB for linting. Run `bundle exec standardrb --fix` before committing to automatically fix style issues.
-
-2. **Testing**: Ensure all specs pass with `bundle exec rspec`.
-
-3. **Examples**: If adding a feature, consider adding an example in the `examples/` directory.
-
-4. **Documentation**: Update the README if your changes affect the public API.
+See [CONTRIBUTING.md](CONTRIBUTING.md).