ai-chat 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3ac8b911bbb322ec7470c226ed15f524b520ca927ccb50eb53d1beba9579e21
-  data.tar.gz: e15f7f7c3f8f06819357b16e853eb8937eb543c8d8f5079e61a5e2ce3599448e
+  metadata.gz: 6b050afeef6a27a67c0125c131e9f2825a0201cf1c1781f7f87750705b150ea8
+  data.tar.gz: d87412fd5c1439eaad5eba3d919b6cbb7dfc795e762199beaeb28825dc1d0281
 SHA512:
-  metadata.gz: e78959fc4366d03d9cbc96e218f77283001af9e9a49b1753c9944040bb8de1fd7c25635cbfb40543a7abead39614cfd68a4ad9d3958907b56023651c44d395e3
-  data.tar.gz: 448d2cdc7892504079edff0028f820bbe384a440e06fc109ac8b4d131e903c196c5ca1f3ff1103615dfeb4b80c3cc6e8b8a08ddbfb5ab044d84c4eb7aa580563
+  metadata.gz: d7e6064820465b1ce64d2fa551e5e92fdf4bb74f6a817e4473a28f69541e431cd84deec12dce1df08fba16041baf27f120e7b37ec6721d40201d138f7f563f69
+  data.tar.gz: f13ebe743b083cd8089fa28e1de37750416b03ce0414eb0b754454f16a1b0bd080abb71c6e2c5b966462b6bda5dc9893dfd530060997a177fce493b1e0782eee

data/README.md

@@ -1,6 +1,44 @@
-# OpenAI Chat
+# AI Chat
 
-This gem provides a class called `OpenAI::Chat` that is intended to make it as easy as possible to use OpenAI's cutting-edge generative AI models.
+This gem provides a class called `AI::Chat` that is intended to make it as easy as possible to use OpenAI's cutting-edge generative AI models.
+
+## Examples
+
+This gem includes comprehensive example scripts that showcase all features and serve as both documentation and validation tests. To explore the capabilities:
+
+### Quick Start
+
+```bash
+# Run a quick overview of key features (takes ~1 minute)
+bundle exec ruby examples/01_quick.rb
+```
+
+### Run All Examples
+
+```bash
+# Run the complete test suite demonstrating all features
+bundle exec ruby examples/all.rb
+```
+
+### Individual Feature Examples
+
+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.)
+
+Each example is self-contained and can be run individually:
+```bash
+bundle exec ruby examples/[filename]
+```
 
 ## Installation
 
@@ -9,7 +47,7 @@ This gem provides a class called `OpenAI::Chat` that is intended to make it as e
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "openai-chat", "< 1.0.0"
+gem "ai-chat", "< 1.0.0"
 ```
 
 And then, at a command prompt:
@@ -23,7 +61,7 @@ bundle install
 Or, install it directly with:
 
 ```
-gem install openai-chat
+gem install ai-chat
 ```
 
 ## Simplest usage
@@ -31,10 +69,10 @@ gem install openai-chat
 In your Ruby program:
 
 ```ruby
-require "openai/chat"
+require "ai-chat"
 
-# Create an instance of OpenAI::Chat
-a = OpenAI::Chat.new
+# Create an instance of AI::Chat
+a = AI::Chat.new
 
 # Build up your conversation by adding messages
 a.add("If the Ruby community had an official motto, what might it be?")
@@ -50,7 +88,7 @@ a.generate! # => "Matz is nice and so we are nice" (or similar)
 pp 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 => #<OpenAI::Chat::Response id=resp_abc... model=gpt-4.1-nano tokens=12>}
+#      {:role=>"assistant", :content=>"Matz is nice and so we are nice", :response => #<AI::Chat::Response id=resp_abc... model=gpt-4.1-nano tokens=12>}
 #    ]
 
 # Continue the conversation
@@ -70,7 +108,7 @@ That's it! You're building something like this:
 [
   {:role => "system", :content => "You are a helpful assistant"},
   {:role => "user", :content => "Hello!"},
-  {:role => "assistant", :content => "Hi there! How can I help you today?", :response => #<OpenAI::Chat::Response id=resp_abc... model=gpt-4.1-nano tokens=12>}
+  {:role => "assistant", :content => "Hi there! How can I help you today?", :response => #<AI::Chat::Response id=resp_abc... model=gpt-4.1-nano tokens=12>}
 ]
 ```
 
@@ -79,9 +117,9 @@ That last bit, under `:response`, is an object that represents the JSON that the
 ## Adding Different Types of Messages
 
 ```ruby
-require "openai/chat"
+require "ai-chat"
 
-b = OpenAI::Chat.new
+b = AI::Chat.new
 
 # Add system instructions
 b.add("You are a helpful assistant that talks like Shakespeare.", role: "system")
@@ -105,7 +143,7 @@ b.generate! # => "Methinks 'tis 'Ruby doth bring joy to all who craft with care'
 Instead of always specifying the role, you can use these shortcuts:
 
 ```ruby
-c = OpenAI::Chat.new
+c = AI::Chat.new
 
 # These are equivalent:
 c.add("You are helpful", role: "system")
@@ -130,7 +168,7 @@ We use the `add` method (and its shortcuts) to build up an array because:
 
 ```ruby
 # In a Rails app, you might do:
-d = OpenAI::Chat.new
+d = AI::Chat.new
 d.messages = @conversation.messages  # Load existing messages
 d.user("What should I do next?")     # Add a new question
 d.generate!                         # Generate a response
@@ -143,7 +181,7 @@ d.generate!                         # Generate a response
 By default, the gem uses OpenAI's `gpt-4.1-nano` model. If you want to use a different model, you can set it:
 
 ```ruby
-e = OpenAI::Chat.new
+e = AI::Chat.new
 e.model = "o4-mini"
 ```
 
@@ -167,13 +205,13 @@ The gem by default looks for an environment variable called `OPENAI_API_KEY` and
 You can specify a different environment variable name:
 
 ```ruby
-f = OpenAI::Chat.new(api_key_env_var: "MY_OPENAI_TOKEN")
+f = AI::Chat.new(api_key_env_var: "MY_OPENAI_TOKEN")
 ```
 
 Or, you can pass an API key in directly:
 
 ```ruby
-g = OpenAI::Chat.new(api_key: "your-api-key-goes-here")
+g = AI::Chat.new(api_key: "your-api-key-goes-here")
 ```
 
 ## Inspecting Your Conversation
@@ -181,7 +219,7 @@ g = OpenAI::Chat.new(api_key: "your-api-key-goes-here")
 You can call `.messages` to get an array containing the conversation so far:
 
 ```ruby
-h = OpenAI::Chat.new
+h = AI::Chat.new
 h.system("You are a helpful cooking assistant")
 h.user("How do I boil an egg?")
 h.generate!
@@ -203,12 +241,33 @@ h.last
 # => "Here's how to boil an egg..."
 ```
 
+## 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.
+
+```ruby
+m = AI::Chat.new
+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`:
+
+```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)):
 
 ```ruby
-i = OpenAI::Chat.new
+i = AI::Chat.new
 
 i.system("You are an expert nutritionist. The user will describe a meal. Estimate the calories, carbs, fat, and protein.")
 
@@ -224,10 +283,34 @@ response = i.generate!
 response[:total_calories]  # => 285
 ```
 
-You can also provide the equivalent Ruby `Hash` rather than a `String` containing JSON.
+### Schema Formats
+
+The gem supports multiple schema formats to accommodate different preferences and use cases. The gem will automatically wrap your schema in the correct format for the API.
+
+#### 1. Full Schema with `format` Key (Most Explicit)
+```ruby
+# When you need complete control over the schema structure
+i.schema = {
+  format: {
+    type: :json_schema,
+    name: "nutrition_values",
+    strict: true,
+    schema: {
+      type: "object",
+      properties: {
+        fat: { type: "number", description: "The amount of fat in grams." },
+        protein: { type: "number", description: "The amount of protein in grams." }
+      },
+      required: ["fat", "protein"],
+      additionalProperties: false
+    }
+  }
+}
+```
 
+#### 2. Schema with `name`, `strict`, and `schema` Keys
 ```ruby
-# Equivalent to assigning the String above
+# The format shown in OpenAI's documentation
 i.schema = {
   name: "nutrition_values",
   strict: true,
@@ -235,25 +318,55 @@ i.schema = {
     type: "object",
     properties: {
       fat: { type: "number", description: "The amount of fat in grams." },
-      protein: { type: "number", description: "The amount of protein in grams." },
-      carbs: { type: "number", description: "The amount of carbohydrates in grams." },
-      total_calories: { type: "number", description:
-        "The total calories calculated based on fat, protein, and carbohydrates." }
+      protein: { type: "number", description: "The amount of protein in grams." }
     },
-    required: [:fat, :protein, :carbs, :total_calories],
+    required: [:fat, :protein],
     additionalProperties: false
   }
 }
 ```
 
-The keys can be `String`s or `Symbol`s.
+#### 3. Simple JSON Schema Object
+```ruby
+# The simplest format - just provide the schema itself
+# The gem will wrap it with sensible defaults (name: "response", strict: true)
+i.schema = {
+  type: "object",
+  properties: {
+    fat: { type: "number", description: "The amount of fat in grams." },
+    protein: { type: "number", description: "The amount of protein in grams." }
+  },
+  required: ["fat", "protein"],
+  additionalProperties: false
+}
+```
+
+#### 4. JSON String Formats
+All the above formats also work as JSON strings:
+
+```ruby
+# As a JSON string with full format
+i.schema = '{"format":{"type":"json_schema","name":"nutrition_values","strict":true,"schema":{...}}}'
+
+# As a JSON string with name/strict/schema
+i.schema = '{"name":"nutrition_values","strict":true,"schema":{...}}'
+
+# As a simple JSON schema string
+i.schema = '{"type":"object","properties":{...}}'
+```
+
+### Schema Notes
+
+- The keys can be `String`s or `Symbol`s.
+- The gem automatically converts your schema to the format expected by the API.
+- When a schema is set, `generate!` returns a parsed Ruby Hash with symbolized keys, not a String.
 
 ## Including Images
 
 You can include images in your chat messages using the `user` method with the `image` or `images` parameter:
 
 ```ruby
-j = OpenAI::Chat.new
+j = AI::Chat.new
 
 # Send a single image
 j.user("What's in this image?", image: "path/to/local/image.jpg")
@@ -277,18 +390,130 @@ The gem supports three types of image inputs:
 - **File paths**: Pass a string with a path to a local image file
 - **File-like objects**: Pass an object that responds to `read` (like `File.open("image.jpg")` or Rails uploaded files)
 
-## Web Search
+## Including Files
 
-To give the model access to real-time information from the internet, you can enable the `web_search` feature. This uses OpenAI's built-in `web_search_preview` tool.
+You can include files (PDFs, text files, etc.) in your messages using the `file` or `files` parameter:
 
 ```ruby
-m = OpenAI::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
+k = AI::Chat.new
+
+# Send a single file
+k.user("Summarize this document", file: "report.pdf")
+k.generate!
+
+# Send multiple files
+k.user("Compare these documents", files: ["doc1.pdf", "doc2.txt", "data.json"])
+k.generate!
 ```
 
-**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.
+Files are handled intelligently based on their type:
+- **PDFs**: Sent as file attachments for the model to analyze
+- **Text files**: Content is automatically extracted and sent as text
+- **Other formats**: The gem attempts to read them as text if possible
+
+## Mixed Content (Images + Files)
+
+You can send images and files together in a single message:
+
+```ruby
+l = AI::Chat.new
+
+# Mix image and file in one message
+l.user("Compare this photo with the document", 
+       image: "photo.jpg", 
+       file: "document.pdf")
+l.generate!
+
+# Mix multiple images and files
+l.user("Analyze all these materials",
+       images: ["chart1.png", "chart2.png"],
+       files: ["report.pdf", "data.csv"])
+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! # => "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! # => "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:
+
+```ruby
+a = AI::Chat.new
+a.image_generation = true
+a.user("Draw a picture of a kitten")
+a.generate! # => "Here is your picture of a kitten:"
+```
+
+By default, images are saved to `./images`. You can configure a different location:
+
+```ruby
+a = AI::Chat.new
+a.image_generation = true
+a.image_folder = "./my_images"
+a.user("Draw a picture of a kitten")
+a.generate! # => "Here is your picture of a kitten:"
+```
+
+Images are saved in timestamped subfolders using ISO 8601 basic format. For example:
+- `./images/20250804T11303912_resp_abc123/001.png`
+- `./images/20250804T11303912_resp_abc123/002.png` (if multiple images)
+
+The folder structure ensures images are organized chronologically and by response.
+
+The messages array will now look like this:
+
+```ruby
+pp 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 ...>}
+# ]
+```
+
+You can access the image filenames in several ways:
+
+```ruby
+# From the last message
+images = a.messages.last[:images]
+# => ["./images/20250804T11303912_resp_abc123/001.png"]
+
+# From the response object
+images = a.messages.last[:response].images
+# => ["./images/20250804T11303912_resp_abc123/001.png"]
+```
+
+Note: Unlike with user-provided input images, OpenAI _does_ store AI-generated output images. So, if you make another API request using the same chat, previous images generated by the model in the conversation history will automatically be used — you don't have to re-send them. This allows you to easily refine an image with user input over multi-turn chats.
+
+```ruby
+a = AI::Chat.new
+a.image_generation = true
+a.image_folder = "./images"
+a.user("Draw a picture of a kitten")
+a.generate! # => "Here is a picture of a kitten:"
+a.user("Make it even cuter")
+a.generate! # => "Here is the kitten, but even cuter:"
+```
 
 ## Building Conversations Without API Calls
 
@@ -296,7 +521,7 @@ You can manually add assistant messages without making API calls, which is usefu
 
 ```ruby
 # Create a new chat instance
-k = OpenAI::Chat.new
+k = AI::Chat.new
 
 # Add previous messages
 k.system("You are a helpful assistant who provides information about planets.")
@@ -316,14 +541,14 @@ response = k.generate!
 puts response
 ```
 
-With this, you can loop through any conversation's history (perhaps after retrieving it from your database), recreate an `OpenAI::Chat`, and then continue it.
+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
 
 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:
 
 ```ruby
-l = OpenAI::Chat.new
+l = AI::Chat.new
 l.model = "o3-mini"
 l.reasoning_effort = "medium" # Can be "low", "medium", or "high"
 
@@ -343,7 +568,7 @@ Setting to `nil` disables the reasoning parameter.
 When you call `generate!` or `generate!`, the gem stores additional information about the API response:
 
 ```ruby
-t = OpenAI::Chat.new
+t = AI::Chat.new
 t.user("Hello!")
 t.generate!
 
@@ -352,19 +577,14 @@ pp t.messages.last
 # => {
 #      :role => "assistant",
 #      :content => "Hello! How can I help you today?",
-#      :response => #<OpenAI::Chat::Response id=resp_abc... model=gpt-4.1-nano tokens=12>
+#      :response => #<AI::Response id=resp_abc... model=gpt-4.1-nano tokens=12>
 #    }
 
 # Access detailed information
-response = t.last_response
+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}
-
-# Helper methods
-t.last_response_id    # => "resp_abc123..."
-t.last_usage          # => {:prompt_tokens=>5, :completion_tokens=>7, :total_tokens=>12}
-t.total_tokens        # => 12
 ```
 
 This information is useful for:
@@ -373,20 +593,20 @@ 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, pick up an old conversation at that point in time:
+You can also, if you know a response ID, continue an old conversation by setting the `previous_response_id`:
 
 ```ruby
-t = OpenAI::Chat.new
+t = AI::Chat.new
 t.user("Hello!")
 t.generate!
-old_id = t.last_response_id # => "resp_abc123..."
+old_id = t.last[:response].id # => "resp_abc123..."
 
 # Some time in the future...
 
-u = OpenAI::Chat.new
-u.pick_up_from("resp_abc123...")
-u.messages # => [
-#      {:role=>"assistant", :response => #<OpenAI::Chat::Response id=resp_abc...}
+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!
@@ -400,7 +620,7 @@ You can use `.messages=()` to assign an `Array` of `Hashes`. Each `Hash` must ha
 
 ```ruby
 # Using the planet example with array of hashes
-p = OpenAI::Chat.new
+p = AI::Chat.new
 
 # Set all messages at once instead of calling methods sequentially
 p.messages = [
@@ -423,7 +643,7 @@ You can still include images:
 
 ```ruby
 # Create a new chat instance
-q = OpenAI::Chat.new
+q = AI::Chat.new
 
 # With images
 q.messages = [
@@ -446,7 +666,7 @@ If your chat history is contained in an `ActiveRecord::Relation`, you can assign
 # Load from ActiveRecord
 @thread = Thread.find(42)
 
-r = OpenAI::Chat.new
+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
@@ -466,7 +686,7 @@ In order for the above to "magically" work, there are a few requirements. Your A
 If your columns have different names:
 
 ```ruby
-s = OpenAI::Chat.new
+s = AI::Chat.new
 s.configure_message_attributes(
   role: :message_type,     # Your column for role
   content: :message_body,  # Your column for content
@@ -485,13 +705,13 @@ add_column :messages, :openai_response, :text
 
 # In your model
 class Message < ApplicationRecord
-  serialize :openai_response, OpenAI::Chat::Response
+  serialize :openai_response, AI::Chat::Response
 end
 
 # Usage
 @thread = Thread.find(42)
 
-t = OpenAI::Chat.new
+t = AI::Chat.new
 t.posts = @thread.messages
 t.user("Hello!")
 t.generate!
@@ -511,13 +731,12 @@ last_message.openai_response.usage # => {:prompt_tokens=>10, ...}
 
 While this gem includes specs, they use mocked API responses. To test with real API calls:
 
-1. Navigate to the test program directory: `cd demo`
-2. Create a `.env` file in the test_program directory with your API credentials:
+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
     ```
-3. Install dependencies: `bundle install`
-4. Run the test program: `ruby demo.rb`
+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.

data/ai-chat.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "ai-chat"
-  spec.version = "0.1.1"
+  spec.version = "0.2.1"
   spec.authors = ["Raghu Betina"]
   spec.email = ["raghu@firstdraft.com"]
   spec.homepage = "https://github.com/firstdraft/ai-chat"
@@ -18,12 +18,11 @@ Gem::Specification.new do |spec|
     "source_code_uri" => "https://github.com/firstdraft/ai-chat"
   }
 
-
   spec.required_ruby_version = "~> 3.2"
-  spec.add_dependency "zeitwerk", "~> 2.7"
-  spec.add_dependency "openai", "~> 0.14"
-  spec.add_runtime_dependency "mime-types", "~> 3.0"
-  spec.add_runtime_dependency "base64", "~> 0.1"  # Works for all Ruby versions
+  spec.add_runtime_dependency "openai", "~> 0.16"
+  spec.add_runtime_dependency "marcel", "~> 1.0"
+  spec.add_runtime_dependency "base64", "> 0.1.1"
+  spec.add_runtime_dependency "json", "~> 2.0"
 
   spec.add_development_dependency "dotenv"
   spec.add_development_dependency "refinements", "~> 11.1"

data/lib/ai/chat.rb

@@ -1,31 +1,41 @@
 # frozen_string_literal: true
 
 require "base64"
-require "mime-types"
+require "json"
+require "marcel"
 require "openai"
+require "pathname"
+require "stringio"
+require "fileutils"
 
 require_relative "response"
 
 module AI
-  # Main namespace.
+  # :reek:MissingSafeMethod { exclude: [ generate! ] }
+  # :reek:TooManyMethods
+  # :reek:TooManyInstanceVariables
+  # :reek:InstanceVariableAssumption
+  # :reek:IrresponsibleModule
   class Chat
-    def self.loader(registry = Zeitwerk::Registry)
-      @loader ||= registry.loaders.each.find { |loader| loader.tag == "ai-chat" }
-    end
-
-    attr_accessor :messages, :schema, :model, :web_search
-    attr_reader :reasoning_effort, :client
+    # :reek:Attribute
+    attr_accessor :messages, :model, :web_search, :previous_response_id, :image_generation, :image_folder
+    attr_reader :reasoning_effort, :client, :schema
 
     VALID_REASONING_EFFORTS = [:low, :medium, :high].freeze
-    
+
     def initialize(api_key: nil, api_key_env_var: "OPENAI_API_KEY")
-      @api_key = api_key || ENV.fetch(api_key_env_var)
+      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
+      @image_generation = false
+      @image_folder = "./images"
     end
 
+    # :reek:TooManyStatements
+    # :reek:NilCheck
     def add(content, role: "user", response: nil, image: nil, images: nil, file: nil, files: nil)
       if image.nil? && images.nil? && file.nil? && files.nil?
         messages.push(
@@ -44,41 +54,25 @@ module AI
           }
         ]
 
-        if images && !images.empty?
-          images_array = images.map do |image|
-            {
-              type: "input_image",
-              image_url: process_file(image)
-            }
-          end
+        all_images = []
+        all_images << image if image
+        all_images.concat(Array(images)) if images
 
-          text_and_files_array += images_array
-        elsif image
+        all_images.each do |img|
           text_and_files_array.push(
             {
               type: "input_image",
-              image_url: process_file(image)
+              image_url: process_image_input(img)
             }
           )
-        elsif files && !files.empty?
-          files_array = files.map do |file|
-            {
-              type: "input_file",
-              filename: "test",
-              file_data: process_file(file)
-            }
-          end
+        end
 
-          text_and_files_array += files_array
-        else
-          text_and_files_array.push(
-            {
-              type: "input_file",
-              filename: "test",
-              file_data: process_file(file)
-            }
-          )
+        all_files = []
+        all_files << file if file
+        all_files.concat(Array(files)) if files
 
+        all_files.each do |file|
+          text_and_files_array.push(process_file_input(file))
         end
 
         messages.push(
@@ -97,69 +91,75 @@ module AI
     def user(message, image: nil, images: nil, file: nil, files: nil)
       add(message, role: "user", image: image, images: images, file: file, files: files)
     end
-    
+
     def assistant(message, response: nil)
       add(message, role: "assistant", response: response)
     end
 
+    # :reek:NilCheck
+    # :reek:TooManyStatements
     def generate!
       response = create_response
 
-      if web_search
-        message = response.output.last.content.first.text
-        chat_response = Response.new(response)
-        assistant(message, response: chat_response)
-      elsif schema
-        # filtering out refusals...
-        json_response = response.output.flat_map { _1.content }.select { _1.is_a?(OpenAI::Models::Responses::ResponseOutputText)}.first.text
-        chat_response = Response.new(response)
-        message = JSON.parse(json_response, symbolize_names: true)
-        assistant(message, response: chat_response)
+      chat_response = Response.new(response)
+
+      text_response = extract_text_from_response(response)
+
+      image_filenames = extract_and_save_images(response)
+
+      chat_response.images = image_filenames
+
+      message = if schema
+        if text_response.nil? || text_response.empty?
+          raise ArgumentError, "No text content in response to parse as JSON for schema: #{schema.inspect}"
+        end
+        JSON.parse(text_response, symbolize_names: true)
       else
-        message = response.output.last.content.first.text
-        chat_response = Response.new(response)
+        text_response
+      end
+
+      if image_filenames.empty?
         assistant(message, response: chat_response)
+      else
+        messages.push(
+          {
+            role: "assistant",
+            content: message,
+            images: image_filenames,
+            response: chat_response
+          }.compact
+        )
       end
 
-      message
-    end
+      self.previous_response_id = response.id
 
-    def pick_up_from(response_id)
-      response = client.responses.retrieve(response_id)
-      chat_response = Response.new(response)
-      message = response.output.flat_map { _1.content }.select { _1.is_a?(OpenAI::Models::Responses::ResponseOutputText)}.first.text
-      assistant(message, response: chat_response)
       message
     end
 
+    # :reek:NilCheck
+    # :reek:TooManyStatements
     def reasoning_effort=(value)
       if value.nil?
         @reasoning_effort = nil
-      else
-        # Convert string to symbol if needed
-        symbol_value = value.is_a?(String) ? value.to_sym : value
+        return
+      end
 
-        if VALID_REASONING_EFFORTS.include?(symbol_value)
-          @reasoning_effort = symbol_value
-        else
-          valid_values = VALID_REASONING_EFFORTS.map { |v| ":#{v} or \"#{v}\"" }.join(", ")
-          raise ArgumentError, "Invalid reasoning_effort value: '#{value}'. Must be one of: #{valid_values}"
-        end
+      normalized_value = value.to_sym
+
+      if VALID_REASONING_EFFORTS.include?(normalized_value)
+        @reasoning_effort = normalized_value
+      else
+        valid_values = VALID_REASONING_EFFORTS.map { |valid_value| ":#{valid_value} or \"#{valid_value}\"" }.join(", ")
+        raise ArgumentError, "Invalid reasoning_effort value: '#{value}'. Must be one of: #{valid_values}"
       end
     end
-  
+
     def schema=(value)
       if value.is_a?(String)
-        @schema = JSON.parse(value, symbolize_names: true)
-        unless @schema.key?(:format) || @schema.key?("format")
-          @schema = { format: @schema }
-        end
+        parsed = JSON.parse(value, symbolize_names: true)
+        @schema = wrap_schema_if_needed(parsed)
       elsif value.is_a?(Hash)
-        if value.key?(:format) || value.key?("format")
-          @schema = value
-        else
-          @schema = { format: value }
-        end
+        @schema = wrap_schema_if_needed(value)
       else
         raise ArgumentError, "Invalid schema value: '#{value}'. Must be a String containing JSON or a Hash."
       end
@@ -169,50 +169,70 @@ module AI
       messages.last
     end
 
-    def last_response
-      last[:response]
-    end
-
-    def last_response_id
-      last_response&.id
-    end
-
     def inspect
       "#<#{self.class.name} @messages=#{messages.inspect} @model=#{@model.inspect} @schema=#{@schema.inspect} @reasoning_effort=#{@reasoning_effort.inspect}>"
     end
 
     private
 
-    # Custom exception class for input classification errors.
     class InputClassificationError < StandardError; end
 
+    # :reek:FeatureEnvy
+    # :reek:ManualDispatch
+    def extract_filename(obj)
+      if obj.respond_to?(:original_filename)
+        obj.original_filename
+      elsif obj.respond_to?(:path)
+        File.basename(obj.path)
+      else
+        raise InputClassificationError,
+          "Unable to determine filename from file object. File objects must respond to :original_filename or :path"
+      end
+    end
+
+    # :reek:TooManyStatements
     def create_response
       parameters = {
-        model: model,
-        input: strip_responses(messages),
-        tools: tools,
-        text: schema,
-        reasoning: {
-          effort: reasoning_effort
-        }.compact
-      }.compact
-      parameters = parameters.delete_if { |k, v| v.empty? }
+        model: model
+      }
+
+      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
+
+      messages_to_send = prepare_messages_for_api
+      parameters[:input] = strip_responses(messages_to_send) unless messages_to_send.empty?
+
       client.responses.create(**parameters)
     end
 
+    def prepare_messages_for_api
+      return messages unless previous_response_id
+
+      previous_response_index = messages.find_index { |message| message[:response]&.id == previous_response_id }
+
+      if previous_response_index
+        messages[(previous_response_index + 1)..] || []
+      else
+        messages
+      end
+    end
+
+    # :reek:DuplicateMethodCall
+    # :reek:FeatureEnvy
+    # :reek:ManualDispatch
+    # :reek:TooManyStatements
     def classify_obj(obj)
       if obj.is_a?(String)
-        # Attempt to parse as a URL.
         begin
           uri = URI.parse(obj)
           if uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
             return :url
           end
         rescue URI::InvalidURIError
-          # Not a valid URL; continue to check if it's a file path.
         end
 
-        # Check if the string represents a local file path (must exist on disk).
         if File.exist?(obj)
           :file_path
         else
@@ -220,7 +240,6 @@ module AI
             "String provided is neither a valid URL (must start with http:// or https://) nor an existing file path on disk. Received value: #{obj.inspect}"
         end
       elsif obj.respond_to?(:read)
-        # For non-String objects, check if it behaves like a file.
         :file_like
       else
         raise InputClassificationError,
@@ -228,57 +247,217 @@ module AI
       end
     end
 
-    def process_file(obj)
+    # :reek:DuplicateMethodCall
+    # :reek:ManualDispatch
+    # :reek:TooManyStatements
+    def process_file_input(obj)
       case classify_obj(obj)
       when :url
-        obj
+        {
+          type: "input_file",
+          file_url: obj
+        }
       when :file_path
-        file_path = obj
+        mime_type = Marcel::MimeType.for(Pathname.new(obj))
 
-        mime_type = MIME::Types.type_for(file_path).first.to_s
+        if mime_type == "application/pdf"
+          pdf_data = File.binread(obj)
+          {
+            type: "input_file",
+            filename: File.basename(obj),
+            file_data: encode_as_data_uri(pdf_data, mime_type)
+          }
+        else
+          begin
+            content = File.read(obj, encoding: "UTF-8")
+            # Verify the content can be encoded as JSON (will raise if not)
+            JSON.generate({text: content})
+            {
+              type: "input_text",
+              text: content
+            }
+          rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError, JSON::GeneratorError
+            raise InputClassificationError,
+              "Unable to read #{File.basename(obj)} as text. Only PDF and text files are supported."
+          end
+        end
+      when :file_like
+        filename = extract_filename(obj)
 
-        image_data = File.binread(file_path)
+        content = obj.read
+        obj.rewind if obj.respond_to?(:rewind)
 
-        base64_string = Base64.strict_encode64(image_data)
+        mime_type = Marcel::MimeType.for(StringIO.new(content), name: filename)
 
-        "data:#{mime_type};base64,#{base64_string}"
-      when :file_like
-        filename = if obj.respond_to?(:path)
-          obj.path
-        elsif obj.respond_to?(:original_filename)
-          obj.original_filename
+        if mime_type == "application/pdf"
+          {
+            type: "input_file",
+            filename: filename,
+            file_data: encode_as_data_uri(content, mime_type)
+          }
         else
-          "unknown"
+          begin
+            text_content = content.force_encoding("UTF-8")
+            JSON.generate({text: text_content})
+            {
+              type: "input_text",
+              text: text_content
+            }
+          rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError, JSON::GeneratorError
+            raise InputClassificationError,
+              "Unable to read #{filename} as text. Only PDF and text files are supported."
+          end
         end
+      end
+    end
 
-        mime_type = MIME::Types.type_for(filename).first.to_s
-        mime_type = "image/jpeg" if mime_type.empty?
-
+    # :reek:ManualDispatch
+    # :reek:TooManyStatements
+    def process_image_input(obj)
+      case classify_obj(obj)
+      when :url
+        obj
+      when :file_path
+        mime_type = Marcel::MimeType.for(Pathname.new(obj))
+        image_data = File.binread(obj)
+        encode_as_data_uri(image_data, mime_type)
+      when :file_like
+        filename = extract_filename(obj)
         file_data = obj.read
         obj.rewind if obj.respond_to?(:rewind)
-
-        base64_string = Base64.strict_encode64(file_data)
-
-        "data:#{mime_type};base64,#{base64_string}"
+        mime_type = Marcel::MimeType.for(StringIO.new(file_data), name: filename)
+        encode_as_data_uri(file_data, mime_type)
       end
     end
 
+    # :reek:UtilityFunction
+    def encode_as_data_uri(data, mime_type)
+      "data:#{mime_type};base64,#{Base64.strict_encode64(data)}"
+    end
+
+    # :reek:DuplicateMethodCall
+    # :reek:UtilityFunction
     def strip_responses(messages)
-      messages.each do |message|
-        message.delete(:response) if message.key?(:response)
-        message[:content] = JSON.generate(message[:content]) if message[:content].is_a?(Hash)
+      messages.map do |message|
+        stripped = message.dup
+        stripped.delete(:response)
+        stripped[:content] = JSON.generate(stripped[:content]) if stripped[:content].is_a?(Hash)
+        stripped
       end
     end
 
     def tools
       tools_list = []
       if web_search
-        tools_list << { type: "web_search_preview" } 
+        tools_list << {type: "web_search_preview"}
+      end
+      if image_generation
+        tools_list << {type: "image_generation"}
+      end
+      tools_list
+    end
+
+    def extract_text_from_response(response)
+      response.output.flat_map { |output|
+        output.respond_to?(:content) ? output.content : []
+      }.compact.find { |content|
+        content.is_a?(OpenAI::Models::Responses::ResponseOutputText)
+      }&.text
+    end
+
+    # :reek:FeatureEnvy
+    def wrap_schema_if_needed(schema)
+      if schema.key?(:format) || schema.key?("format")
+        schema
+      elsif (schema.key?(:name) || schema.key?("name")) &&
+          (schema.key?(:schema) || schema.key?("schema")) &&
+          (schema.key?(:strict) || schema.key?("strict"))
+        {
+          format: schema.merge(type: :json_schema)
+        }
+      else
+        {
+          format: {
+            type: :json_schema,
+            name: "response",
+            schema: schema,
+            strict: true
+          }
+        }
+      end
+      tools_list
+    end
+
+    # :reek:DuplicateMethodCall
+    # :reek:FeatureEnvy
+    # :reek:ManualDispatch
+    # :reek:TooManyStatements
+    def extract_and_save_images(response)
+      image_filenames = []
+
+      image_outputs = response.output.select { |output|
+        output.respond_to?(:type) && output.type == :image_generation_call
+      }
+
+      return image_filenames if image_outputs.empty?
+
+      # ISO 8601 basic format with centisecond precision
+      timestamp = Time.now.strftime("%Y%m%dT%H%M%S%2N")
+
+      subfolder_name = "#{timestamp}_#{response.id}"
+      subfolder_path = File.join(image_folder || "./images", subfolder_name)
+      FileUtils.mkdir_p(subfolder_path)
+
+      image_outputs.each_with_index do |output, index|
+        next unless output.respond_to?(:result) && output.result
+
+        begin
+          image_data = Base64.strict_decode64(output.result)
+
+          filename = "#{(index + 1).to_s.rjust(3, "0")}.png"
+          filepath = File.join(subfolder_path, filename)
+
+          File.binwrite(filepath, image_data)
+
+          image_filenames << filepath
+        rescue => error
+          warn "Failed to save image: #{error.message}"
+        end
       end
+
+      image_filenames
+    end
+
+    # :reek:UtilityFunction
+    # :reek:ManualDispatch
+    def extract_text_from_response(response)
+      response.output.flat_map { |output|
+        output.respond_to?(:content) ? output.content : []
+      }.compact.find { |content|
+        content.is_a?(OpenAI::Models::Responses::ResponseOutputText)
+      }&.text
     end
 
-    def extract_message(response)
-      response.output.flat_map { _1.content }.select { _1.is_a?(OpenAI::Models::Responses::ResponseOutputText)}.first.text
+    # :reek:UtilityFunction
+    def wrap_schema_if_needed(schema)
+      if schema.key?(:format) || schema.key?("format")
+        schema
+      elsif (schema.key?(:name) || schema.key?("name")) &&
+          (schema.key?(:schema) || schema.key?("schema")) &&
+          (schema.key?(:strict) || schema.key?("strict"))
+        {
+          format: schema.merge(type: :json_schema)
+        }
+      else
+        {
+          format: {
+            type: :json_schema,
+            name: "response",
+            schema: schema,
+            strict: true
+          }
+        }
+      end
     end
   end
 end

data/lib/ai/response.rb

@@ -1,12 +1,17 @@
 module AI
+  # :reek:IrresponsibleModule
+  # :reek:TooManyInstanceVariables
   class Response
     attr_reader :id, :model, :usage, :total_tokens
+    # :reek:Attribute
+    attr_accessor :images
 
     def initialize(response)
       @id = response.id
       @model = response.model
       @usage = response.usage.to_h.slice(:input_tokens, :output_tokens, :total_tokens)
       @total_tokens = @usage[:total_tokens]
+      @images = []
     end
   end
-end
+end

data/lib/ai-chat.rb

@@ -1 +1 @@
-require_relative "ai/chat"
+require_relative "ai/chat"

metadata

@@ -1,71 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: ai-chat
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Raghu Betina
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-07-29 00:00:00.000000000 Z
+date: 2025-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: zeitwerk
+  name: openai
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '0.16'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '0.16'
 - !ruby/object:Gem::Dependency
-  name: openai
+  name: marcel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.14'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.14'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: mime-types
+  name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
-  name: base64
+  name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -94,7 +94,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '11.1'
-description:
+description: 
 email:
 - raghu@firstdraft.com
 executables: []
@@ -109,7 +109,6 @@ files:
 - lib/ai-chat.rb
 - lib/ai/chat.rb
 - lib/ai/response.rb
-- lib/ai_chat.rb
 homepage: https://github.com/firstdraft/ai-chat
 licenses:
 - MIT
@@ -120,7 +119,7 @@ metadata:
   label: AI Chat
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/firstdraft/ai-chat
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -135,8 +134,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.4.6
+signing_key: 
 specification_version: 4
 summary: A beginner-friendly Ruby interface for OpenAI's API
 test_files: []

data/lib/ai_chat.rb

@@ -1,6 +0,0 @@
-  require "zeitwerk"
-  loader = Zeitwerk::Loader.for_gem
-  loader.inflector.inflect("ai" => "AI")
-  loader.setup
-
-  require_relative "ai/chat"