ai-chat 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 975e7f80044ac46d72ad1c08e290d7fa71b43048fe76d68784d3961c36efde95
-  data.tar.gz: cf0a2b5fcee3e6ee413580419c992efe6c50e5935be875f2e82d8a740c7d15fb
+  metadata.gz: ece58b865d212ce788931ee3e7322b457bbe6ed8495e4374b55ecf697b44e55c
+  data.tar.gz: dd4bf5e24a5190eba63c662d93dcaaad24886b7f16cfbec5aebc37a9f3530cd9
 SHA512:
-  metadata.gz: fe727e64a0388922db85c3085dea85c6622b88c886cbb25fc660dc9bad8291205a1904a19f611457ac83cbe673a299db4d97f0b658e236de0e3ccccb46f44aac
-  data.tar.gz: 4be9d9a80ea39e20ef2c11d8142f9403b7b43f46c8f4ccc5a80f88a027980be11b1e882165e67e0380d2a8982e0e4bbd3489585cac3c4a0a291d46a75813d53d
+  metadata.gz: dcb3587c00724b1da3d04adb2b9a7413225680b80971bd08db127edab6d7f18e52958b7511f3aa7e13cb95f40961f8889cae3f0cc892913930547d5a7887d452
+  data.tar.gz: e831f86fecfa31cf28df66910fc6ca98c66a9ad8290709431a0e5e9b8a6e31965ba7af9d5a00dbcf3f907427abe8901abf23a1cd136b26bc2ebffe260b6334ed

data/README.md

@@ -39,6 +39,7 @@ The `examples/` directory contains focused examples for specific features:
 - `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-5.1 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-5.1 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,7 +227,7 @@ d.generate!                         # Generate a response
 
 ### Model
 
-By default, the gem uses OpenAI's `gpt-5.1` 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
@@ -219,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
@@ -460,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:
@@ -470,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:
@@ -482,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:
@@ -497,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"]
 ```
 
@@ -508,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
@@ -519,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
@@ -582,11 +669,11 @@ The `reasoning_effort` parameter guides the model on how many reasoning tokens t
 - `"medium"`: Balances speed and reasoning accuracy.
 - `"high"`: Favors more complete reasoning.
 
-By default, `reasoning_effort` is `nil`, which means no reasoning parameter is sent to the API. For `gpt-5.1` (the default model), this is equivalent to `"none"` reasoning.
+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
@@ -594,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-5.1 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-5.1"
-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:
@@ -631,7 +718,18 @@ chat.generate!
 puts chat.last_response_id # => "resp_xyz789..." (a new ID)
 ```
 
-This is particularly useful for managing background tasks. When you make a request in background mode, you can immediately get the `last_response_id` to track, retrieve, or cancel that specific job later from a different process.
+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
 
@@ -663,64 +761,117 @@ chat.generate!  # Uses the loaded conversation
 
 ## 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
 
-# Access item data
-page.data.each do |item|
+# 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.]
+
+# 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
@@ -743,80 +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
-
-- **Streaming responses**: Real-time streaming as the AI generates its response
-- **Cost tracking**: Automatic calculation and tracking of API costs
-- **Token usage helpers**: Convenience methods like `total_tokens` to sum usage across all responses in a conversation
-
-## TODO: Missing Test Coverage
-
-The following gem-specific logic would benefit from additional RSpec test coverage:
-
-1. **Schema format normalization** - The `wrap_schema_if_needed` method detects and wraps 3 different input formats (raw, named, already-wrapped). This complex conditional logic could silently regress.
-
-2. **Multimodal content array building** - The `add` method builds nested structures when images/files are provided, handling `image`/`images` and `file`/`files` parameters with specific ordering (text → images → files).
-
-3. **File classification and processing** - `classify_obj` and `process_file_input` distinguish URLs vs file paths vs file-like objects, with MIME type detection determining encoding behavior.
-
-4. **Message preparation after response** - `prepare_messages_for_api` has slicing logic that only sends messages after the last response, preventing re-sending entire conversation history.
-
-These are all gem-specific transformations (not just OpenAI pass-through) that could regress without proper test coverage.
-
-## TODO: Code Quality
-
-Address Reek warnings (`bundle exec reek`). Currently 29 warnings for code smells like:
-
-- `TooManyStatements` in several methods
-- `DuplicateMethodCall` in `extract_and_save_files`, `verbose`, etc.
-- `RepeatedConditional` for `proxy` checks
-- `FeatureEnvy` in `parse_response` and `wait_for_response`
-
-These don't affect functionality but indicate areas for refactoring.
-
-Then, add `quality` back as a CI check.
-
-## 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).

data/ai-chat.gemspec

@@ -2,9 +2,9 @@
 
 Gem::Specification.new do |spec|
   spec.name = "ai-chat"
-  spec.version = "0.4.0"
-  spec.authors = ["Raghu Betina"]
-  spec.email = ["raghu@firstdraft.com"]
+  spec.version = "0.5.0"
+  spec.authors = ["Raghu Betina", "Jelani Woods"]
+  spec.email = ["raghu@firstdraft.com", "jelani@firstdraft.com"]
   spec.homepage = "https://github.com/firstdraft/ai-chat"
   spec.summary = "A beginner-friendly Ruby interface for OpenAI's API"
   spec.license = "MIT"

data/lib/ai/amazing_print.rb

@@ -1,4 +1,22 @@
 require "amazing_print"
+
+# Fix AmazingPrint's colorless method to strip HTML tags in addition to ANSI codes.
+# Without this, alignment is broken when html: true because colorless_size
+# doesn't account for <kbd> tag lengths.
+# TODO: Remove if https://github.com/amazing-print/amazing_print/pull/146 is merged.
+module AmazingPrint
+  module Formatters
+    class BaseFormatter
+      alias_method :original_colorless, :colorless
+
+      def colorless(string)
+        result = original_colorless(string)
+        result.gsub(/<kbd[^>]*>|<\/kbd>/, "")
+      end
+    end
+  end
+end
+
 # :reek:IrresponsibleModule
 module AmazingPrint
   module AI
@@ -27,33 +45,11 @@ module AmazingPrint
       end
     end
 
-    # :reek:DuplicateMethodCall
     # :reek:FeatureEnvy
-    # :reek:NilCheck
-    # :reek:TooManyStatements
     def format_ai_chat(chat)
-      vars = []
-
-      # Format messages with truncation
-      if chat.instance_variable_defined?(:@messages)
-        messages = chat.instance_variable_get(:@messages).map do |msg|
-          truncated_msg = msg.dup
-          if msg[:content].is_a?(String) && msg[:content].length > 80
-            truncated_msg[:content] = msg[:content][0..77] + "..."
-          end
-          truncated_msg
-        end
-        vars << ["@messages", messages]
+      vars = chat.inspectable_attributes.map do |(name, value)|
+        [name.to_s, value]
       end
-
-      # Add other variables (except sensitive ones)
-      skip_vars = [:@api_key, :@client, :@messages]
-      chat.instance_variables.sort.each do |var|
-        next if skip_vars.include?(var)
-        value = chat.instance_variable_get(var)
-        vars << [var.to_s, value] unless value.nil?
-      end
-
       format_object(chat, vars)
     end
 
@@ -65,10 +61,13 @@ module AmazingPrint
         "#{name}: #{inspector.awesome(value)}"
       end
 
+      lt = @options[:html] ? "&lt;" : "<"
+      gt = @options[:html] ? "&gt;" : ">"
+
       if @options[:multiline]
-        "#<#{object.class}\n#{data.map { |line| "  #{line}" }.join("\n")}\n>"
+        "##{lt}#{object.class}\n#{data.map { |line| "  #{line}" }.join("\n")}\n#{gt}"
       else
-        "#<#{object.class} #{data.join(", ")}>"
+        "##{lt}#{object.class} #{data.join(", ")}#{gt}"
       end
     end
   end

data/lib/ai/chat.rb

@@ -12,7 +12,6 @@ require "tty-spinner"
 require "timeout"
 
 require_relative "http"
-include AI::Http
 
 module AI
   # :reek:MissingSafeMethod { exclude: [ generate! ] }
@@ -21,6 +20,8 @@ module AI
   # :reek:InstanceVariableAssumption
   # :reek:IrresponsibleModule
   class Chat
+    include AI::Http
+
     # :reek:Attribute
     attr_accessor :background, :code_interpreter, :conversation_id, :image_generation, :image_folder, :messages, :model, :proxy, :reasoning_effort, :web_search
     attr_reader :client, :last_response_id, :schema, :schema_file
@@ -31,7 +32,7 @@ module AI
       @api_key = api_key || ENV.fetch(api_key_env_var)
       @messages = []
       @reasoning_effort = nil
-      @model = "gpt-5.1"
+      @model = "gpt-5.2"
       @client = OpenAI::Client.new(api_key: @api_key)
       @last_response_id = nil
       @proxy = false
@@ -47,7 +48,7 @@ module AI
       json = if proxy
         uri = URI(PROXY_URL + "api.openai.com/v1/responses")
         parameters = {
-          model: "gpt-5.1",
+          model: "gpt-5.2",
           input: [
             {role: :system, content: system_prompt},
             {role: :user, content: description}
@@ -60,7 +61,7 @@ module AI
       else
         client = OpenAI::Client.new(api_key: api_key)
         response = client.responses.create(
-          model: "gpt-5.1",
+          model: "gpt-5.2",
           input: [
             {role: :system, content: system_prompt},
             {role: :user, content: description}
@@ -84,15 +85,12 @@ module AI
     # :reek:TooManyStatements
     # :reek:NilCheck
     def add(content, role: "user", response: nil, status: nil, image: nil, images: nil, file: nil, files: nil)
-      if image.nil? && images.nil? && file.nil? && files.nil?
-        message = {
-          role: role,
-          content: content,
-          response: response
-        }
-        message[:content] = content if content
-        message[:status] = status if status
-        messages.push(message)
+      message = if image.nil? && images.nil? && file.nil? && files.nil?
+        msg = Message[role: role]
+        msg[:content] = content if content
+        msg[:response] = response if response
+        msg[:status] = status if status
+        msg
       else
         text_and_files_array = [
           {
@@ -122,14 +120,15 @@ module AI
           text_and_files_array.push(process_file_input(file))
         end
 
-        messages.push(
-          {
-            role: role,
-            content: text_and_files_array,
-            status: status
-          }
-        )
+        Message[
+          role: role,
+          content: text_and_files_array,
+          status: status
+        ]
       end
+
+      messages.push(message)
+      message
     end
 
     def system(message)
@@ -189,10 +188,10 @@ module AI
       messages.last
     end
 
-    def items(order: :asc)
+    def get_items(order: :asc)
       raise "No conversation_id set. Call generate! first to create a conversation." unless conversation_id
 
-      if proxy
+      raw_items = if proxy
         uri = URI(PROXY_URL + "api.openai.com/v1/conversations/#{conversation_id}/items?order=#{order}")
         response_hash = send_request(uri, content_type: "json", method: "get")
 
@@ -215,62 +214,50 @@ module AI
       else
         client.conversations.items.list(conversation_id, order: order)
       end
+
+      Items.new(raw_items, conversation_id: conversation_id)
     end
 
-    def verbose
-      page = items
+    def inspectable_attributes
+      attrs = []
+
+      # 1. Model and reasoning (configuration)
+      attrs << [:@model, @model]
+      attrs << [:@reasoning_effort, @reasoning_effort]
+
+      # 2. Conversation state
+      attrs << [:@conversation_id, @conversation_id]
+      attrs << [:@last_response_id, @last_response_id] if @last_response_id
 
-      box_width = 78
-      inner_width = box_width - 4
+      # 3. Messages (the main content, without response details)
+      display_messages = @messages.map { |msg| msg.except(:response) }
+      attrs << [:@messages, display_messages]
 
-      puts
-      puts "┌#{"─" * (box_width - 2)}┐"
-      puts "│ Conversation: #{conversation_id.ljust(inner_width - 14)} │"
-      puts "│ Items: #{page.data.length.to_s.ljust(inner_width - 7)} │"
-      puts "└#{"─" * (box_width - 2)}┘"
-      puts
+      # 4. Optional features (only if enabled/changed from default)
+      attrs << [:@proxy, @proxy] if @proxy != false
+      attrs << [:@image_generation, @image_generation] if @image_generation != false
+      attrs << [:@image_folder, @image_folder] if @image_folder != "./images"
 
-      ap page.data, limit: 10, indent: 2
+      # 5. Optional state (only if set)
+      attrs << [:@background, @background] if @background
+      attrs << [:@code_interpreter, @code_interpreter] if @code_interpreter
+      attrs << [:@web_search, @web_search] if @web_search
+      attrs << [:@schema, @schema] if @schema
+      attrs << [:@schema_file, @schema_file] if @schema_file
+
+      attrs
     end
 
     def inspect
-      "#<#{self.class.name} @messages=#{messages.inspect} @model=#{@model.inspect} @schema=#{@schema.inspect} @reasoning_effort=#{@reasoning_effort.inspect}>"
+      ai(plain: !$stdout.tty?, multiline: true)
     end
 
-    # Support for Ruby's pp (pretty print)
-    # :reek:TooManyStatements
-    # :reek:NilCheck
-    # :reek:FeatureEnvy
-    # :reek:DuplicateMethodCall
-    # :reek:UncommunicativeParameterName
-    def pretty_print(q)
-      q.group(1, "#<#{self.class}", ">") do
-        q.breakable
-
-        # Show messages with truncation
-        q.text "@messages="
-        truncated_messages = @messages.map do |msg|
-          truncated_msg = msg.dup
-          if msg[:content].is_a?(String) && msg[:content].length > 80
-            truncated_msg[:content] = msg[:content][0..77] + "..."
-          end
-          truncated_msg
-        end
-        q.pp truncated_messages
-
-        # Show other instance variables (except sensitive ones)
-        skip_vars = [:@messages, :@api_key, :@client]
-        instance_variables.sort.each do |var|
-          next if skip_vars.include?(var)
-          value = instance_variable_get(var)
-          unless value.nil?
-            q.text ","
-            q.breakable
-            q.text "#{var}="
-            q.pp value
-          end
-        end
-      end
+    def to_html
+      AI.wrap_html(ai(html: true, multiline: true))
+    end
+
+    def pretty_inspect
+      "#{inspect}\n"
     end
 
     private
@@ -312,7 +299,7 @@ module AI
       parameters[:background] = background if background
       parameters[:tools] = tools unless tools.empty?
       parameters[:text] = schema if schema
-      parameters[:reasoning] = {effort: reasoning_effort} if reasoning_effort
+      parameters[:reasoning] = {effort: reasoning_effort, summary: "auto"} if reasoning_effort
 
       create_conversation unless conversation_id
       parameters[:conversation] = conversation_id
@@ -387,12 +374,12 @@ module AI
         message.dig(:response, :id) == response_id
       end
 
-      message = {
+      message = Message[
         role: "assistant",
         content: response_content,
         response: chat_response,
         status: response_status
-      }
+      ]
 
       message.store(:images, image_filenames) unless image_filenames.empty?
 
@@ -400,8 +387,9 @@ module AI
         messages[existing_message_position] = message
       else
         messages.push(message)
-        message
       end
+
+      message
     end
 
     def cancel_request

data/lib/ai/items.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module AI
+  class Items < SimpleDelegator
+    def initialize(response, conversation_id:)
+      super(response)
+      @conversation_id = conversation_id
+    end
+
+    def to_html
+      AI.wrap_html(build_output(html: true))
+    end
+
+    def inspect
+      build_output(html: false, plain: !$stdout.tty?)
+    end
+
+    def pretty_inspect
+      "#{inspect}\n"
+    end
+
+    def pretty_print(q)
+      q.output << inspect
+    end
+
+    private
+
+    def build_output(html: false, plain: false)
+      box = build_box
+      items_output = data.ai(html: html, plain: plain, limit: 100, indent: 2, index: true)
+
+      if html
+        "<pre>#{box}</pre>\n#{items_output}"
+      else
+        "#{box}\n#{items_output}"
+      end
+    end
+
+    def build_box
+      box_width = 78
+      inner_width = box_width - 4
+
+      lines = []
+      lines << "┌#{"─" * (box_width - 2)}┐"
+      lines << "│ Conversation: #{@conversation_id.to_s.ljust(inner_width - 14)} │"
+      lines << "│ Items: #{data.length.to_s.ljust(inner_width - 7)} │"
+      lines << "└#{"─" * (box_width - 2)}┘"
+
+      lines.join("\n")
+    end
+  end
+end

data/lib/ai/message.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AI
+  class Message < Hash
+    def inspect
+      ai(plain: !$stdout.tty?, index: false)
+    end
+
+    def pretty_inspect
+      "#{inspect}\n"
+    end
+
+    # IRB's ColorPrinter calls pretty_print and re-colorizes text,
+    # which escapes our ANSI codes. Write directly to output to bypass.
+    def pretty_print(q)
+      q.output << inspect
+    end
+
+    def to_html
+      AI.wrap_html(ai(html: true, index: false))
+    end
+  end
+end

data/lib/ai-chat.rb

@@ -1,3 +1,14 @@
+module AI
+  HTML_PRE_STYLE = "background-color: #1e1e1e; color: #d4d4d4; padding: 1em; white-space: pre-wrap; word-wrap: break-word;"
+
+  def self.wrap_html(html)
+    html = html.gsub("<pre>", "<pre style=\"#{HTML_PRE_STYLE}\">")
+    html.respond_to?(:html_safe) ? html.html_safe : html
+  end
+end
+
+require_relative "ai/message"
+require_relative "ai/items"
 require_relative "ai/chat"
 
 # Load amazing_print extension if amazing_print is available

metadata

@@ -1,10 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: ai-chat
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Raghu Betina
+- Jelani Woods
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -143,6 +144,7 @@ dependencies:
         version: '11.1'
 email:
 - raghu@firstdraft.com
+- jelani@firstdraft.com
 executables: []
 extensions: []
 extra_rdoc_files:
@@ -156,6 +158,8 @@ files:
 - lib/ai/amazing_print.rb
 - lib/ai/chat.rb
 - lib/ai/http.rb
+- lib/ai/items.rb
+- lib/ai/message.rb
 - lib/prompts/schema_generator.md
 homepage: https://github.com/firstdraft/ai-chat
 licenses:
@@ -181,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.1
 specification_version: 4
 summary: A beginner-friendly Ruby interface for OpenAI's API
 test_files: []