ai-chat 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12727b49e500d9c3c117b0d8a4df291f0b050eae0b12c90d7cd992ac93881c42
-  data.tar.gz: 2ebf913f409bdfbebcc5cd12d8a4a87346be894564d75a6c7811157b9619ecce
+  metadata.gz: b21d17972572c7c6282aa2a40c539f48967b47caad6ac0f80f99046337436576
+  data.tar.gz: b27033cec74910347d8f965e7aa4928b888a0d42aa8f14c48bc229014522cf7d
 SHA512:
-  metadata.gz: 3707fdf80a68ce541b0c4fb3ab362f2404e2b0e78a3e7bd86ec140702f4b2939a6c2740b12a58d39212aceb24607c87648948f5d93bb5fcacffbf7200e35e2e0
-  data.tar.gz: 9d3e23578c90251da1fb08351aafe48fa5c7a82ec330644a6cffbe156fd42d58bcfbebd42be93df5a7a680cddfe0855c8dc2770ef3c8a0a70f2c4d4e8fa894f8
+  metadata.gz: 5fd677c3e077c29a9777c1c1fa57108798d39ad09fed0093db12ce0819c9a4a204bbc8cbbfd84b4236df48b9ee7e3a0ea0469d29745188d1a22d3f5789f5c65a
+  data.tar.gz: 4edb6917f52330c5a8dd27e825e1cc27201da82ab8cc7e4988d0514b3ed92969f0b8369be4ceec44fbaa3684545774060430ca110730e5dfe753686c4f292526

data/README.md

@@ -34,6 +34,11 @@ The `examples/` directory contains focused examples for specific features:
 - `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)
 
 Each example is self-contained and can be run individually:
 ```bash
@@ -243,17 +248,18 @@ h.last[:content]
 
 ## Web Search
 
-To give the model access to real-time information from the internet, we enable the `web_search` feature by default. 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_preview` tool.
 
 ```ruby
 m = AI::Chat.new
+m.web_search = true
 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`:
+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
@@ -525,6 +531,21 @@ y.user("Plot y = 2x*3 when x is -5 to 5.")
 y.generate! # => {:content => "Here is the graph.", ... }
 ```
 
+## Proxying Through prepend.me
+
+You can proxy API calls through [prepend.me](https://prepend.me/).
+
+```rb
+chat = AI::Chat.new
+chat.proxy = true
+chat.user("Tell me a story")
+chat.generate!
+puts chat.last[:content]
+# => "Once upon a time..."
+```
+
+When proxy is enabled, **you must use the API key provided by prepend.me** in place of a real OpenAI API key. Refer to [the section on API keys](#api-key) for options on how to set your key.
+
 ## Building Conversations Without API Calls
 
 You can manually add assistant messages without making API calls, which is useful when reconstructing a past conversation:
@@ -624,6 +645,93 @@ u.generate!
 
 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.)
 
+### Automatic Conversation Management
+
+Starting with your first `generate!` call, the gem automatically creates and manages a conversation with OpenAI. This conversation is stored server-side and tracks all messages, tool calls, reasoning, and other items.
+
+```ruby
+chat = AI::Chat.new
+chat.user("Hello")
+chat.generate!
+
+# Conversation ID is automatically set
+puts chat.conversation_id  # => "conv_abc123..."
+
+# Continue the conversation - context is automatically maintained
+chat.user("What did I just say?")
+chat.generate!  # Uses the same conversation automatically
+```
+
+You can also load an existing conversation from your database:
+
+```ruby
+# Load stored conversation_id from your database
+chat = AI::Chat.new
+chat.conversation_id = @thread.conversation_id  # From your database
+
+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.):
+
+```ruby
+chat = AI::Chat.new
+chat.web_search = true
+chat.user("Search for Ruby tutorials")
+chat.generate!
+
+# Get all conversation items (chronological order by default)
+page = chat.items
+
+# Access item data
+page.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}"
+  when :reasoning
+    puts "Reasoning: #{item.summary.first.text}"
+  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)
+```
+
+### `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.]
+```
+
+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
+
 ## 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`:
@@ -668,69 +776,6 @@ q.messages = [
 ]
 ```
 
-## Assigning `ActiveRecord::Relation`s
-
-If your chat history is contained in an `ActiveRecord::Relation`, you can assign it directly:
-
-```ruby
-# Load from ActiveRecord
-@thread = Thread.find(42)
-
-r = AI::Chat.new
-r.messages = @thread.posts.order(:created_at)
-r.user("What should we discuss next?")
-r.generate! # Creates a new post record, too
-```
-
-### Requirements
-
-In order for the above to "magically" work, there are a few requirements. Your ActiveRecord model must have:
-
-- `.role` method that returns "system", "user", or "assistant"
-- `.content` method that returns the message text
-- `.image` method (optional) for single images - can return URLs, file paths, or Active Storage attachments
-- `.images` method (optional) for multiple images
-
-### Custom Column Names
-
-If your columns have different names:
-
-```ruby
-s = AI::Chat.new
-s.configure_message_attributes(
-  role: :message_type,     # Your column for role
-  content: :message_body,  # Your column for content
-  image: :attachment       # Your column/association for images
-)
-s.messages = @conversation.messages
-```
-
-### Saving Responses with Metadata
-
-To preserve response metadata, add an `openai_response` column to your messages table:
-
-```ruby
-# In your migration
-add_column :messages, :openai_response, :text
-
-# In your model
-class Message < ApplicationRecord
-  serialize :openai_response, AI::Chat::Response
-end
-
-# Usage
-@thread = Thread.find(42)
-
-t = AI::Chat.new
-t.posts = @thread.messages
-t.user("Hello!")
-t.generate!
-
-# The saved message will include token usage, model info, etc.
-last_message = @thread.messages.last
-last_message.openai_response.usage # => {:prompt_tokens=>10, ...}
-```
-
 ## Other Features Being Considered
 
 - **Session management**: Save and restore conversations by ID
@@ -750,3 +795,15 @@ While this gem includes specs, they use mocked API responses. To test with real
 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.
+
+## 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.

data/ai-chat.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "ai-chat"
-  spec.version = "0.2.4"
+  spec.version = "0.3.0"
   spec.authors = ["Raghu Betina"]
   spec.email = ["raghu@firstdraft.com"]
   spec.homepage = "https://github.com/firstdraft/ai-chat"
@@ -12,20 +12,22 @@ Gem::Specification.new do |spec|
   spec.metadata = {
     "bug_tracker_uri" => "https://github.com/firstdraft/ai-chat/issues",
     "changelog_uri" => "https://github.com/firstdraft/ai-chat/blob/main/CHANGELOG.md",
-    "homepage_uri" => "https://github.com/firstdraft/ai-chat",
+    "homepage_uri" => "https://rubygems.org/gems/ai-chat",
     "label" => "AI Chat",
     "rubygems_mfa_required" => "true",
     "source_code_uri" => "https://github.com/firstdraft/ai-chat"
   }
 
   spec.required_ruby_version = "~> 3.2"
-  spec.add_runtime_dependency "openai", "~> 0.16"
+  spec.add_runtime_dependency "openai", "~> 0.34"
   spec.add_runtime_dependency "marcel", "~> 1.0"
-  spec.add_runtime_dependency "base64", "> 0.1.1"
+  spec.add_runtime_dependency "base64",  "~> 0.1", "> 0.1.1"
   spec.add_runtime_dependency "json", "~> 2.0"
+  spec.add_runtime_dependency "ostruct", "~> 0.2"
   spec.add_runtime_dependency "tty-spinner", "~> 0.9.3"
+  spec.add_runtime_dependency "amazing_print", "~> 1.8"
 
-  spec.add_development_dependency "dotenv"
+  spec.add_development_dependency "dotenv", ">= 1.0.0"
   spec.add_development_dependency "refinements", "~> 11.1"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

data/lib/ai/chat.rb

@@ -4,12 +4,16 @@ require "base64"
 require "json"
 require "marcel"
 require "openai"
+require "ostruct"
 require "pathname"
 require "stringio"
 require "fileutils"
 require "tty-spinner"
 require "timeout"
 
+require_relative "http"
+include AI::Http
+
 module AI
   # :reek:MissingSafeMethod { exclude: [ generate! ] }
   # :reek:TooManyMethods
@@ -18,22 +22,60 @@ module AI
   # :reek:IrresponsibleModule
   class Chat
     # :reek:Attribute
-    attr_accessor :background, :code_interpreter, :image_generation, :image_folder, :messages, :model, :previous_response_id, :web_search
+    attr_accessor :background, :code_interpreter, :conversation_id, :image_generation, :image_folder, :messages, :model, :proxy, :previous_response_id, :web_search
     attr_reader :reasoning_effort, :client, :schema
 
     VALID_REASONING_EFFORTS = [:low, :medium, :high].freeze
+    PROXY_URL = "https://prepend.me/".freeze
 
     def initialize(api_key: nil, api_key_env_var: "OPENAI_API_KEY")
-      api_key ||= ENV.fetch(api_key_env_var)
+      @api_key = api_key || ENV.fetch(api_key_env_var)
       @messages = []
       @reasoning_effort = nil
       @model = "gpt-4.1-nano"
-      @client = OpenAI::Client.new(api_key: api_key)
+      @client = OpenAI::Client.new(api_key: @api_key)
       @previous_response_id = nil
+      @proxy = false
       @image_generation = false
       @image_folder = "./images"
     end
 
+    def self.generate_schema!(description, api_key: nil, api_key_env_var: "OPENAI_API_KEY", proxy: false)
+      @api_key ||= ENV.fetch(api_key_env_var)
+      prompt_path = File.expand_path("../prompts/schema_generator.md", __dir__)
+      system_prompt = File.open(prompt_path).read
+
+      json = if proxy
+        uri = URI(PROXY_URL + "api.openai.com/v1/responses")
+        parameters = {
+          model: "o4-mini",
+          input: [
+            {role: :system, content: system_prompt},
+            {role: :user, content: description},
+          ],
+          text: {format: {type: "json_object"}},
+          reasoning: {effort: "high"}
+        }
+
+        send_request(uri, content_type: "json", parameters: parameters, method: "post")
+      else
+        client = OpenAI::Client.new(api_key: api_key)
+        response = client.responses.create(
+          model: "o4-mini",
+          input: [
+            {role: :system, content: system_prompt},
+            {role: :user, content: description}
+          ],
+          text: {format: {type: "json_object"}},
+          reasoning: {effort: "high"}
+        )
+
+        output_text = response.output_text
+        JSON.parse(output_text)
+      end
+      JSON.pretty_generate(json)
+    end
+
     # :reek:TooManyStatements
     # :reek:NilCheck
     def add(content, role: "user", response: nil, status: nil, image: nil, images: nil, file: nil, files: nil)
@@ -100,10 +142,11 @@ module AI
     # :reek:NilCheck
     # :reek:TooManyStatements
     def generate!
+      validate_api_key
       response = create_response
       parse_response(response)
 
-      self.previous_response_id = last.dig(:response, :id)
+      self.previous_response_id = last.dig(:response, :id) unless (conversation_id && !background)
       last
     end
 
@@ -115,7 +158,7 @@ module AI
       response = if wait
         wait_for_response(timeout)
       else
-        client.responses.retrieve(previous_response_id)
+        retrieve_response(previous_response_id)
       end
       parse_response(response)
     end
@@ -153,6 +196,50 @@ module AI
       messages.last
     end
 
+    def items(order: :asc)
+      raise "No conversation_id set. Call generate! first to create a conversation." unless conversation_id
+
+      if proxy
+        uri = URI(PROXY_URL + "api.openai.com/v1/conversations/#{conversation_id}/items?order=#{order.to_s}")
+        response_hash = send_request(uri, content_type: "json", method: "get")
+
+        if response_hash.key?(:data)
+          response_hash.dig(:data).map do |hash|
+            # Transform values to allow expected symbols that non-proxied request returns 
+
+            hash.transform_values! do |value|
+              if hash.key(value) == :type
+                value.to_sym
+              else
+                value
+              end
+            end
+          end
+          response_hash
+        end
+        # Convert to Struct to allow same interface as non-proxied request
+        create_deep_struct(response_hash)
+      else
+        client.conversations.items.list(conversation_id, order: order)
+      end
+    end
+
+    def verbose
+      page = items
+
+      box_width = 78
+      inner_width = box_width - 4
+
+      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
+
+      ap page.data, limit: 10, indent: 2
+    end
+
     def inspect
       "#<#{self.class.name} @messages=#{messages.inspect} @model=#{@model.inspect} @schema=#{@schema.inspect} @reasoning_effort=#{@reasoning_effort.inspect}>"
     end
@@ -164,9 +251,9 @@ module AI
     # :reek:DuplicateMethodCall
     # :reek:UncommunicativeParameterName
     def pretty_print(q)
-      q.group(1, "#<#{self.class}", '>') do
+      q.group(1, "#<#{self.class}", ">") do
         q.breakable
-        
+
         # Show messages with truncation
         q.text "@messages="
         truncated_messages = @messages.map do |msg|
@@ -177,7 +264,7 @@ module AI
           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|
@@ -196,6 +283,7 @@ module AI
     private
 
     class InputClassificationError < StandardError; end
+    class WrongAPITokenUsedError < StandardError; end
 
     # :reek:FeatureEnvy
     # :reek:ManualDispatch
@@ -210,6 +298,17 @@ module AI
       end
     end
 
+    def create_conversation
+      self.conversation_id = if proxy
+        uri = URI(PROXY_URL + "api.openai.com/v1/conversations")
+        response = send_request(uri, content_type: "json", method: "post")
+        response.dig(:id)
+      else
+        conversation = client.conversations.create
+        conversation.id
+      end
+    end
+
     # :reek:TooManyStatements
     def create_response
       parameters = {
@@ -220,27 +319,72 @@ module AI
       parameters[:tools] = tools unless tools.empty?
       parameters[:text] = schema if schema
       parameters[:reasoning] = {effort: reasoning_effort} if reasoning_effort
-      parameters[:previous_response_id] = previous_response_id if previous_response_id
+
+      if previous_response_id && conversation_id
+        warn "Both conversation_id and previous_response_id are set. Using previous_response_id for forking. Only set one."
+        parameters[:previous_response_id] = previous_response_id
+      elsif previous_response_id
+        parameters[:previous_response_id] = previous_response_id
+      elsif conversation_id
+        parameters[:conversation] = conversation_id
+      else
+        create_conversation
+      end
 
       messages_to_send = prepare_messages_for_api
       parameters[:input] = strip_responses(messages_to_send) unless messages_to_send.empty?
 
-      client.responses.create(**parameters)
+      if proxy
+        uri = URI(PROXY_URL + "api.openai.com/v1/responses")
+        send_request(uri, content_type: "json", parameters: parameters, method: "post")
+      else
+        client.responses.create(**parameters)
+      end
     end
 
     # :reek:NilCheck
     # :reek:TooManyStatements
     def parse_response(response)
-      text_response = response.output_text
-      image_filenames = extract_and_save_images(response)
-      response_id = response.id
-      response_usage = response.usage.to_h.slice(:input_tokens, :output_tokens, :total_tokens)
+      if proxy && response.is_a?(Hash)
+        response_messages = response.dig(:output).select do |output|
+          output.dig(:type) == "message"
+        end
+
+        message_contents = response_messages.map do |message|
+          message.dig(:content)
+        end.flatten
+
+        output_texts = message_contents.select do |content|
+          content[:type] == "output_text"
+        end
+
+        text_response = output_texts.map { |output| output[:text] }.join
+        response_id = response.dig(:id)
+        response_status = response.dig(:status).to_sym
+        response_model = response.dig(:model)
+        response_usage = response.dig(:usage)&.slice(:input_tokens, :output_tokens, :total_tokens)
+
+        if response.key?(:conversation)
+          self.conversation_id = response.dig(:conversation, :id)
+        end
+      else        
+        text_response = response.output_text
+        response_id = response.id
+        response_status = response.status
+        response_model = response.model
+        response_usage = response.usage.to_h.slice(:input_tokens, :output_tokens, :total_tokens)
+
+        if response.conversation
+          self.conversation_id = response.conversation.id
+        end
+      end
+      image_filenames = extract_and_save_images(response) + extract_and_save_files(response)
 
       chat_response = {
         id: response_id,
-        model: response.model,
-        usage: response_usage,
-        total_tokens: response_usage[:total_tokens],
+        model: response_model,
+        usage: response_usage || {},
+        total_tokens: response_usage&.fetch(:total_tokens, 0),
         images: image_filenames
       }.compact
 
@@ -261,7 +405,7 @@ module AI
         role: "assistant",
         content: response_content,
         response: chat_response,
-        status: response.status
+        status: response_status
       }
 
       message.store(:images, image_filenames) unless image_filenames.empty?
@@ -461,19 +605,31 @@ module AI
     def extract_and_save_images(response)
       image_filenames = []
 
-      image_outputs = response.output.select { |output|
-        output.respond_to?(:type) && output.type == :image_generation_call
-      }
+      if proxy
+        image_outputs = response.dig(:output).select { |output|
+          output.dig(:type) == "image_generation_call"
+        }
+      else       
+        image_outputs = response.output.select { |output|
+          output.respond_to?(:type) && output.type == :image_generation_call
+        }
+      end
 
       return image_filenames if image_outputs.empty?
 
-      subfolder_path = create_images_folder(response.id)
+      response_id = proxy ? response.dig(:id) : response.id
+      subfolder_path = create_images_folder(response_id)
 
       image_outputs.each_with_index do |output, index|
-        next unless output.respond_to?(:result) && output.result
+        if proxy
+          next unless output.key?(:result) && output.dig(:result)
+        else
+          next unless output.respond_to?(:result) && output.result
+        end
 
         warn_if_file_fails_to_save do
-          image_data = Base64.strict_decode64(output.result)
+          result = proxy ? output.dig(:result) : output.result
+          image_data = Base64.strict_decode64(result)
 
           filename = "#{(index + 1).to_s.rjust(3, "0")}.png"
           file_path = File.join(subfolder_path, filename)
@@ -498,10 +654,32 @@ module AI
     end
 
     def warn_if_file_fails_to_save
-      begin
-        yield
-      rescue => error
-        warn "Failed to save image: #{error.message}"
+      yield
+    rescue => error
+      warn "Failed to save image: #{error.message}"
+    end
+
+    def validate_api_key
+      openai_api_key_used = @api_key.start_with?("sk-proj")
+      proxy_api_key_used = !openai_api_key_used
+      proxy_enabled = proxy
+      proxy_disabled = !proxy
+
+      if openai_api_key_used && proxy_enabled
+        raise WrongAPITokenUsedError, <<~STRING
+          It looks like you're using an official API key from OpenAI with proxying enabled. When proxying is enabled you must use an OpenAI API key from prepend.me. Please disable proxy or update your API key before generating a response.
+        STRING
+      elsif proxy_api_key_used && proxy_disabled
+        raise WrongAPITokenUsedError, <<~STRING
+          It looks like you're using an unofficial OpenAI API key from prepend.me. When using an unofficial API key you must enable proxy before generating a response. Proxying is currently disabled, please enable it before generating a response.
+
+          Example:
+
+            chat = AI::Chat.new
+            chat.proxy = true
+            chat.user(...)
+            chat.generate!
+        STRING
       end
     end
 
@@ -512,41 +690,74 @@ module AI
     def extract_and_save_files(response)
       filenames = []
 
-      message_outputs = response.output.select do |output|
-        output.respond_to?(:type) && output.type == :message
-      end
-
-      outputs_with_annotations = message_outputs.map do |message|
-        message.content.find do |content|
-          content.respond_to?(:annotations) && content.annotations.length.positive?
+      if proxy
+        message_outputs = response.dig(:output).select do |output|
+          output.dig(:type) == "message"
+        end
+  
+        outputs_with_annotations = message_outputs.map do |message|
+          message.dig(:content).find do |content|
+            content.dig(:annotations).length.positive?
+          end
+        end.compact
+      else
+        message_outputs = response.output.select do |output|
+          output.respond_to?(:type) && output.type == :message
         end
-      end.compact
+  
+        outputs_with_annotations = message_outputs.map do |message|
+          message.content.find do |content|
+            content.respond_to?(:annotations) && content.annotations.length.positive?
+          end
+        end.compact
+      end
 
       return filenames if outputs_with_annotations.empty?
 
-      subfolder_path = create_images_folder(response.id)
-      annotations = outputs_with_annotations.map do |output|
-        output.annotations.find do |annotation|
-          annotation.respond_to?(:filename)
-        end
-      end.compact
-
-      annotations.each do |annotation|
-        container_id = annotation.container_id
-        file_id = annotation.file_id
-        filename = annotation.filename
+      response_id = proxy ? response.dig(:id) : response.id
+      subfolder_path = create_images_folder(response_id)
 
-        warn_if_file_fails_to_save do
-          container_content = client.containers.files.content
-          file_content = container_content.retrieve(file_id, container_id: container_id)
-          file_path = File.join(subfolder_path, filename)
-          File.open(file_path, "wb") do |file|
-            file.write(file_content.read)
+      if proxy
+        annotations = outputs_with_annotations.map do |output|
+          output.dig(:annotations).find do |annotation|
+            annotation.key?(:filename)
+          end
+        end.compact
+  
+        annotations.each do |annotation|
+          container_id = annotation.dig(:container_id)
+          file_id = annotation.dig(:file_id)
+          filename = annotation.dig(:filename)
+  
+          warn_if_file_fails_to_save do
+            file_content = retrieve_file(file_id, container_id: container_id)
+            file_path = File.join(subfolder_path, filename)
+            File.binwrite(file_path, file_content)
+            filenames << file_path
+          end
+        end
+      else
+        annotations = outputs_with_annotations.map do |output|
+          output.annotations.find do |annotation|
+            annotation.respond_to?(:filename)
+          end
+        end.compact
+  
+        annotations.each do |annotation|
+          container_id = annotation.container_id
+          file_id = annotation.file_id
+          filename = annotation.filename
+  
+          warn_if_file_fails_to_save do
+            file_content = retrieve_file(file_id, container_id: container_id)
+            file_path = File.join(subfolder_path, filename)
+            File.open(file_path, "wb") do |file|
+              file.write(file_content.read)
+            end
+            filenames << file_path
           end
-          filenames << file_path
         end
       end
-
       filenames
     end
 
@@ -561,13 +772,11 @@ module AI
     end
 
     def timeout_request(duration)
-      begin
-        Timeout.timeout(duration) do
-          yield
-        end
-      rescue Timeout::Error
-        client.responses.cancel(previous_response_id)
+      Timeout.timeout(duration) do
+        yield
       end
+    rescue Timeout::Error
+      client.responses.cancel(previous_response_id)
     end
 
     # :reek:DuplicateMethodCall
@@ -575,21 +784,56 @@ module AI
     def wait_for_response(timeout)
         spinner = TTY::Spinner.new("[:spinner] Thinking ...", format: :dots)
         spinner.auto_spin
-        api_response = client.responses.retrieve(previous_response_id)
+        api_response = retrieve_response(previous_response_id)
         number_of_times_polled = 0
         response = timeout_request(timeout) do
-          while api_response.status != :completed
+          status = if api_response.respond_to?(:status)
+            api_response.status
+          else 
+            api_response.dig(:status)&.to_sym
+          end
+
+          while status != :completed
             some_amount_of_seconds = calculate_wait(number_of_times_polled)
             sleep some_amount_of_seconds
             number_of_times_polled += 1
-            api_response = client.responses.retrieve(previous_response_id)
+            api_response = retrieve_response(previous_response_id)
+            status = if api_response.respond_to?(:status)
+              api_response.status
+            else
+              api_response.dig(:status)&.to_sym
+            end
           end
           api_response
         end
-
-        exit_message = response.status == :cancelled ? "request timed out" : "done!"
+        
+        status = if api_response.respond_to?(:status)
+          api_response.status
+        else 
+          api_response.dig(:status).to_sym
+        end
+        exit_message = status == :cancelled ? "request timed out" : "done!"
         spinner.stop(exit_message)
         response
     end
+
+    def retrieve_response(previous_response_id)
+      if proxy
+        uri = URI(PROXY_URL + "api.openai.com/v1/responses/#{previous_response_id}")
+        send_request(uri, content_type: "json", method: "get")
+      else
+        client.responses.retrieve(previous_response_id)
+      end
+    end
+
+    def retrieve_file(file_id, container_id: nil)
+      if proxy
+        uri = URI(PROXY_URL + "api.openai.com/v1/containers/#{container_id}/files/#{file_id}/content")
+        send_request(uri, method: "get")
+      else
+        container_content = client.containers.files.content
+        file_content = container_content.retrieve(file_id, container_id: container_id)
+      end
+    end
   end
 end

data/lib/ai/http.rb

@@ -0,0 +1,45 @@
+require "net/http"
+module AI
+  module Http
+    def send_request(uri, content_type: nil, parameters: nil, method:)
+      Net::HTTP.start(uri.host, 443, use_ssl: true) do |http|
+        headers = {
+          "Authorization" => "Bearer #{@api_key}"
+        }
+        if content_type
+          headers.store("Content-Type", "application/json")
+        end
+        net_http_method = "Net::HTTP::#{method.downcase.capitalize}"
+        client = Kernel.const_get(net_http_method)
+        request = client.new(uri, headers)
+
+        if parameters
+          request.body = parameters.to_json
+        end
+        response = http.request(request)
+
+        # Handle proxy server 503 HTML response
+        begin
+          if content_type
+            return JSON.parse(response.body, symbolize_names: true)
+          else
+            return response.body
+          end
+        rescue JSON::ParserError, TypeError => e
+          raise JSON::ParserError, "Failed to parse response from proxy: #{e.message}"
+        end
+      end
+    end
+
+    def create_deep_struct(value)
+      case value
+      when Hash
+        OpenStruct.new(value.transform_values { |hash_value| send __method__, hash_value })
+      when Array
+        value.map { |element| send __method__, element }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/prompts/schema_generator.md

@@ -0,0 +1,123 @@
+You are an expert at creating JSON Schemas for OpenAI's Structured Outputs feature.
+
+Generate a valid JSON Schema that follows these strict rules:
+
+## OUTPUT FORMAT
+Return a JSON object with this root structure:
+- "name": a short snake_case identifier for the schema
+- "strict": must be true
+- "schema": the actual JSON Schema object
+
+## SCHEMA REQUIREMENTS
+
+### Critical Rules:
+1. Root schema must be "type": "object" (not anyOf)
+2. Set "additionalProperties": false on ALL objects (including nested ones)
+3. ALL properties must be in "required" arrays (no optional fields unless using union types)
+4. Always specify "items" for arrays
+
+### Supported Types:
+- string, number, boolean, integer, object, array, enum, anyOf
+
+### Optional Fields:
+To make a field optional, use union types:
+- "type": ["string", "null"] for optional string
+- "type": ["number", "null"] for optional number
+- etc.
+
+### String Properties (use when appropriate):
+- "pattern": regex pattern (e.g., "^@[a-zA-Z0-9_]+$" for usernames)
+- "format": predefined formats (date-time, time, date, duration, email, hostname, ipv4, ipv6, uuid)
+- Example: {"type": "string", "format": "email", "description": "User's email address"}
+
+### Number Properties (use when appropriate):
+- "minimum": minimum value (inclusive)
+- "maximum": maximum value (inclusive)
+- "exclusiveMinimum": minimum value (exclusive)
+- "exclusiveMaximum": maximum value (exclusive)
+- "multipleOf": must be multiple of this value
+- Example: {"type": "number", "minimum": -130, "maximum": 130, "description": "Temperature in degrees"}
+
+### Array Properties (use when appropriate):
+- "minItems": minimum number of items
+- "maxItems": maximum number of items
+- Example: {"type": "array", "items": {...}, "minItems": 1, "maxItems": 10}
+
+### Enum Values:
+Use enums for fixed sets of values:
+- Example: {"type": "string", "enum": ["draft", "published", "archived"]}
+
+### Nested Objects:
+All nested objects MUST have:
+- "additionalProperties": false
+- Complete "required" arrays
+- Clear "description" fields
+
+### Recursive Schemas:
+Support recursion using "$ref":
+- Root recursion: {"$ref": "#"}
+- Definition reference: {"$ref": "#/$defs/node_name"}
+
+### Descriptions:
+Add clear, helpful "description" fields for all properties to guide the model.
+
+## CONSTRAINTS
+- Max 5000 properties total, 10 levels of nesting
+- Max 1000 enum values across all enums
+- Total string length of all names/values cannot exceed 120,000 chars
+
+## EXAMPLE OUTPUTS
+
+Simple example:
+{
+  "name": "user_profile",
+  "strict": true,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {"type": "string", "description": "User's full name"},
+      "age": {"type": "integer", "minimum": 0, "maximum": 150, "description": "User's age in years"},
+      "email": {"type": "string", "format": "email", "description": "User's email address"}
+    },
+    "required": ["name", "age", "email"],
+    "additionalProperties": false
+  }
+}
+
+Complex example with arrays and nesting:
+{
+  "name": "recipe_collection",
+  "strict": true,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "recipes": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {"type": "string", "description": "Recipe name"},
+            "ingredients": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {"type": "string"},
+                  "quantity": {"type": "string"}
+                },
+                "required": ["name", "quantity"],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": ["name", "ingredients"],
+          "additionalProperties": false
+        }
+      }
+    },
+    "required": ["recipes"],
+    "additionalProperties": false
+  }
+}
+
+Return ONLY the JSON object, no additional text or explanation.

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ai-chat
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Raghu Betina
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-09-08 00:00:00.000000000 Z
+date: 2025-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openai
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.34'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.34'
 - !ruby/object:Gem::Dependency
   name: marcel
   requirement: !ruby/object:Gem::Requirement
@@ -42,6 +41,9 @@ dependencies:
   name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
     - - ">"
       - !ruby/object:Gem::Version
         version: 0.1.1
@@ -49,6 +51,9 @@ dependencies:
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
     - - ">"
       - !ruby/object:Gem::Version
         version: 0.1.1
@@ -66,6 +71,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: tty-spinner
   requirement: !ruby/object:Gem::Requirement
@@ -80,20 +99,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.3
+- !ruby/object:Gem::Dependency
+  name: amazing_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: refinements
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +141,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '11.1'
-description: 
 email:
 - raghu@firstdraft.com
 executables: []
@@ -123,17 +155,18 @@ files:
 - lib/ai-chat.rb
 - lib/ai/amazing_print.rb
 - lib/ai/chat.rb
+- lib/ai/http.rb
+- lib/prompts/schema_generator.md
 homepage: https://github.com/firstdraft/ai-chat
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/firstdraft/ai-chat/issues
   changelog_uri: https://github.com/firstdraft/ai-chat/blob/main/CHANGELOG.md
-  homepage_uri: https://github.com/firstdraft/ai-chat
+  homepage_uri: https://rubygems.org/gems/ai-chat
   label: AI Chat
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/firstdraft/ai-chat
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -148,8 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A beginner-friendly Ruby interface for OpenAI's API
 test_files: []